雲識別 APIs 簡介

API 大全

REST API 介面協議與鑒權機制

CRS API 遵循標準 HTTP REST 傳輸標準。

Http Header

Authorization: <填入 APIKey 中取得的 Token>

Http 請求參數，分為兩種類型：

公共參數（總共包括這些，認證方式不同搭配不同使用）：
- appId
- timestamp（Long 長整型：1970年1月1日00:00:00 UTC 以來經過的毫秒數）
- apiKey
- signature（請求簽名，token 方式認證二選一）
CRS API 參數：API 自己的參數

API 文件不再描述認證用的公共參數

API Key 認證

認證方式分為兩種：

基於 Token 認證

Http 頭部 Authorization 包含 Token，公共參數包括：

appId

簽名認證

不用 Http 頭部 Authorization。

公共參數含有 signature 簽名資訊。所有參數納入簽名計算（影像除外）。

appId
timestamp
apiKey
signature

有關簽名計算的詳細演算法和程式碼，請參考文件 API Key 簽名方法。

使用範例與屬性解析

API 使用範例

這裡透過一個範例 —— 呼叫 API 介面建立一個目標影像，幫助開發者一窺 CRS API 請求過程，瞭解目標圖的屬性結構，以及介面輸入輸出。

生產環境建立目標圖前需要驗證更多，具體請參考最佳實踐來新建一個目標影像。

請求範例

新增一個 test-target.jpg 的目標影像檔案。建立目標圖時，影像檔案需經過 base64 編碼。

API 文件中會對請求參數做詳細說明。參考 API —— 建立目標影像，影像檔案 base64 編碼請求 API 。

POST /targets HTTP/1.1
Host:
Date: Mon, 1 Jan 2018 00:00:00 GMT
Content-Type: application/json
{
    "image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM...",
    "active":"1",
    "name":"easyar",
    "size":"5",
    "meta":"496fbbabc2b38ecs3460a...",
    "type":"ImageTarget",
    "timestamp": 1514736000000,
    "apiKey": "8b485c648c3056e79c2a85ee9b51f9dc",
    "appId": "C:CN1:f9f903c36da8bd64d71d491077bba...",
    "signature": "89985e2420899196db5bdf16b3c2ed0922c0c221"
}

返回範例

HTTP/1.1 200 OK
Content-Type: application/json
{
    "statusCode": 0,
    "result": {
        "targetId":"e61db301-e80f-4025-b822-9a00eb48d8d2",
        "trackingImage":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM..."，
        "name": "easyar",
        "size": "5",
        "meta": "496fbbabc2b38ecs3460a...",
        "type": "ImageTarget",
        "modified":1514735000000
        "active":"1"，
        "trackableRate": 0,
        "detectableRate": 0,
        “detectableDistinctiveness”：0,
        "detectableFeatureCount": 0,
        "trackableDistinctiveness": 0,
        "trackableFeatureCount": 0,
        "trackableFeatureDistribution": 0,
        "trackablePatchContrast": 0,
        "trackablePatchAmbiguity": 0
    },
    "timestamp": 1514736000000
}

響應格式

響應均採用統一格式。以下是一個範例：

{
  "statusCode": 119,
  "msg": "Parameter has errors",
  "date": "2022-06-15T09:56:30.000Z",
  "result":  //statusCode 為 0 的情況才有 result，如果發生錯誤，結果欄位為空
}

如上面範例所示，這是正常返回目標圖詳情結構，一個目標圖包括以下屬性

屬性	描述
targetId	目標圖的唯一 Id
trackingImage	處理後灰階圖的 base64 編碼，用於裝置端影像跟蹤
name	目標圖名稱
size	圖片尺寸大小，應用中疊加虛擬內容實用的尺寸
meta	使用者關聯資料，可以檔案可以文字或者 url，需要 base64 編碼
type	"ImageTarget"
active	啟用的目標圖才能識別到，停用以後將不被識別到
trackableRate	跟蹤難度評分，越小越好
detectableRate	識別綜合難度評分，越小越好
detectableDistinctiveness	識別可區分難度評分，越小越好
detectableFeatureCount	識別特徵方面難度評分，越小越好
trackableDistinctiveness	跟蹤可區分難度評分，越小越好
trackableFeatureCount	跟蹤特徵方面難度評分，越小越好
trackableFeatureDistribution	跟蹤特徵分佈難度評分，越小越好

錯誤碼

雲識別 APIs 錯誤碼說明

Table of Contents