api介面怎麼對接?你只需要注意這4點

Noah_WB發表於2023-02-28

原則上API介面設計一般出現在開發的詳細設計中,但是隨著諸多公司建立開放平臺,產品經理也逐漸需要能理解API介面,尤其是做平臺性的產品,還要學會定義介面。本文就關於產品經理在設計介面中需要定義什麼、需要注意什麼來展開陳述。

一、

在做介面設計時,如果是新手,建議多參考並瞭解不同開放平臺的介面樣式,比如百度、曠視、騰訊等,從中可以發現一些共識;

1、常用的通訊協議

呼叫第三方平臺介面需要進行系統間的通訊,目前常用的協議是http和https;簡單理解https是http的加密版,可以將使用者到服務端請求的資訊進行加密,避免因明文傳輸被截獲而獲知使用者資訊。

基於http協議的介面具有輕量級、跨平臺、和跨語言的特點,為了適應不同的開發者,目前各個第三方平臺都會提供基於各種常用語言的介面形式,因此大多采用http或https協議;舉例,百度、科大訊飛:筆者查閱了百度、騰訊、曠視、阿里的雲平臺發現在視覺方面均都採用的是https協議;對於視覺,圖片資料本身包含的資訊就很豐富,尤其是人臉,因此採用https還是有利於保護使用者隱私資訊的。

2、 介面的請求方式

瞭解介面的請求方式有助於瞭解使用者端和服務端間的互動方式,基於http協議的常用請求方式是post和get;兩者的主要區別如下:

(1)直觀區別:get請求方式是將請求引數放到url中,post是將引數放到requst body中,所帶來的的直接影響是get的請求引數存在長度限制,post無限制;其次是get將引數放到url中安全性弱於post;

(2)深度區別:get請求方式使用者端和服務端只產生一次互動,post請求方式使用者端會和服務端產生兩次互動,舉例:快遞小哥是使用者端,你是服務端,則get就像常來你們小區和你認識的快遞員直接將快件送到你家,你跟他說聲謝謝;post就像新來的快遞員先打個電話問下你在家嗎?你告訴他你在家呢,過了5分鐘他將快遞送到你家了,你跟他說聲謝謝;

目前百度、騰訊、曠視的影像識別介面均採用的是post請求方式。

3、介面響應機制

最後瞭解介面的響應機制:同步介面和非同步介面;簡單理解同步介面即實時返回訊息給呼叫方,非同步介面就是可以延遲返回訊息給呼叫方;實時性要求高的且只能線性工作的需要採用同步介面,其他可以優先使用非同步介面;當然不同的場景,同樣的服務介面會被要求同步或非同步;以人臉識別中的人臉註冊為例:

(1)刷臉支付:以支付寶為例,使用之前需要按照步驟採集人臉,後臺會呼叫人臉註冊將當前人臉註冊進人臉庫並和該支付寶賬號資訊繫結,這一步人臉註冊通常是同步介面,因為不會要求使用者在APP前等待太久,需要及時返回註冊成功資訊;

(2)客流系統:現在商超使用的客流系統一般已經採用人臉識別取代頭肩模型,這樣不僅可以統計人數還可以統計人次,其中對於首次識別的陌生人臉通常需要註冊進陌生人臉庫,這裡的人臉註冊一般為非同步介面,因為大型商超每天數十萬客流且對於陌生人無會員資訊,所以不需要實時註冊,只要進入佇列能在當日24小時內註冊完即可;

小結

以上關於API的介面常識在設計介面的時候,開發一般都會要求產品確定介面的響應機制;其他的開發都會自己完成;但作為開放平臺的產品經常會對接開發,多瞭解些常識既可以跟自己的開發有更多的共同語言溝通,也可以在對接使用者的時候可以跟使用者的開發簡單解釋。

二、核心業務欄位&介面約束

產品經理雖然不需要定義API所有的欄位資訊,但是跟業務需求有關的欄位產品經理需要明確清晰。

1、 入參

(1)鑑權欄位資訊

呼叫第三方平臺介面通常需要進行介面鑑權,服務端判斷使用者端是否有呼叫介面的許可權;這裡跟產品經理相關的是作為產品需要設計應用管理,包括:應用列表、應用建立、應用詳情、應用配置、應用刪除等操作;以百度AI平臺,應用列表如下:

其中AppID、API Key和Secret Key為建立應用時自動生成,介面鑑權所需要的access_token必須透過API key和Secret key請求服務端獲取。

(2)核心業務欄位

產品經理需要根據業務需求明確介面入參中需要哪些欄位資訊以及欄位支援的型別,以百度AI平臺的菜品識別為例:

業務需求:識別圖片中是哪種菜品;

產品需求:

輸入圖片,圖片支援通常採用和URL格式;

top_num,提高介面的通用性,方便使用者後續場景擴充套件,因此支援配置返回菜品數量且排序;

閾值,開放識別閾值,方便使用者根據實際識別效果調整,提高準確率;

注意點:設計介面核心業務欄位,要儘量提高介面的通用性,以此適配更多的使用者場景,比如top_num和閾值的開放,即泛化介面能力,將更多的主動權交由介面使用者配置。

(3)欄位資訊約束條件

欄位約束條件是為了保證介面的安全性,這點是產品經理跟業務方溝通達成一致後提供給開發小夥伴的;仍然以上面的菜品識別為例:

圖片需要限制檔案大小和解析度大小,檔案大小隻需要上限,解析度大小需要包括上限和下限,下限是為了保證演算法效果,比如在目標檢測中小目標容易檢測失敗;

top_num需要限制下限,不得小於0,不設上限,可以接受演算法返回的所有結果;

閾值根據格式確定,可以是0-100,可以是0-1;

注:設定引數的一點小技巧,為了保證演算法效果,有時演算法會預設設定引數,即使用者設定的閾值低於預設引數,則不接受輸入,採用預設,使用者是無感知的;

2、出參

呼叫介面就會有返回資訊,產品需要根據業務需求定義返回的核心欄位資訊,這次以百度AI開放平臺手勢識別為例,其中跟業務需求相關的關鍵欄位包括:

result_num、result,即一張圖片中識別的手勢結果數量,和具體的手勢資訊;

result為json陣列,包括手勢的類別、手勢檢測框的位置資訊【一般識別類演算法底層是檢測+識別兩步】、和手勢類別的置信度;

其中result中的一些欄位資訊,產品可以根據業務需求進行增減,比如目標檢測框的位置資訊,一般業務不需要就可以省略;

三、介面限流

介面限流也是為了保障系統的安全性,因為有時業務方因為業務擴充套件導致呼叫量激增,容易引起服務端當機;限流就類似於電閘的保險絲保證請求量超過介面上限時系統可以拒絕請求或排隊,以此保證系統的安全性;

產品經理需要實現對業務充分評估,給出合理評估量,如TPS(每秒處理的請求量);這樣既不會造成系統資源的浪費,也保證業務正常執行;

注:與上面介面響應機制對應,同步介面一般需要給出峰值tps和響應時間,非同步介面需要給出日調量即可;

四、介面測試

介面測試雖然是測試小姐姐的工作,測試內容也覆蓋眾多,但是作為產品可以簡單瞭解以下內容即可,如,

(1)介面可用性,即介面是否可以正常呼叫,正常返回結果,異常正確處理,正常返回錯誤碼等;

(2)業務需求覆蓋,即介面輸入輸出是否遵循產品需求文件描述;

(3)邊界規則遵循,即介面是否滿足業務規則和欄位約束條件;

(4)效能條件,通常介面上線前需要經過壓測達到效能指標才可,包括某併發量下的tps和耗時等;


來自 “ ITPUB部落格 ” ,連結:http://blog.itpub.net/70026910/viewspace-2937361/,如需轉載,請註明出處,否則將追究法律責任。

相關文章