Snapshot - Take

服務:

Azure AI Services

API 版本:

1.0-preview

提交作業以擷取臉部清單、大型臉部清單、人員群組或大型人員群組的快照集，其中包含使用者指定的快照集類型、來源物件標識碼、套用範圍和選擇性的用戶數據。
快照集介面可讓使用者從一個臉部訂用帳戶備份並還原其臉部數據，並還原到另一個臉部訂用帳戶、位於相同區域或跨區域。 工作流程包含兩個階段，使用者會先呼叫 Snapshot - Take 來建立來源對象的複本，並將其儲存為快照集，然後呼叫 Snapshot - Apply 將快照集貼到目標訂用帳戶。 快照集會儲存在每個 Azure 實例) 集中位置 (，以便跨帳戶和區域套用快照集。
擷取快照集是異步操作。 作業標識碼可以從響應標頭中的 [作業位置] 欄位取得，以用於 OperationStatus - Get 來追蹤建立快照集的進度。 當作業狀態為「成功」時，快照集標識符將會包含在 OperationStatus - 取得回應的 “resourceLocation” 字段中。
快照集花費時間取決於來源物件中的人員和臉部項目數目。 其可能為秒數，或最多 1,000,000 人有多個臉部。
快照集會在快照集 - 擷取建立快照集之後，於 48 小時內自動過期並清除。 用戶可以使用快照集刪除快照集 - 在到期前隨時自行刪除。
針對特定物件建立快照集不會封鎖物件的任何其他作業。 所有只讀作業 (Get/List 和 Identify/FindSimilar/Verify) 都可以如往常執行。 對於所有可寫入的作業，包括 Add/Update/Delete 來源物件或其人員/臉部和訓練，它們不會遭到封鎖，但不建議這麼做，因為擷取期間，可寫入的更新可能不會反映在快照集上。 快照集擷取完成後，所有可讀取和可寫入的作業都可以正常運作。 快照集也會包含來源物件的定型結果，這表示在呼叫Identify/FindSimilar之前，套用快照集的目標訂用帳戶不需要重新定型目標物件。

• 免費層訂用帳戶配額：每月 100 個執行作業。
• S0 層訂用帳戶配額：每天 100 個執行作業。

POST {Endpoint}/face/v1.0-preview/snapshots

URI 參數

名稱	位於	必要	類型	Description
Endpoint	path	True	string	支援的認知服務端點 (通訊協定和主機名，例如： https://westus.api.cognitive.microsoft.com) 。

要求標頭

名稱	必要	類型	Description
Ocp-Apim-Subscription-Key	True	string

要求本文

名稱	必要	類型	Description
applyScope	True	string[]	使用者指定的快照集目標臉部訂用帳戶標識碼數位。 對於每個快照集，只有套用快照集範圍中包含的訂用帳戶 - 擷取可以套用它。
objectId	True	string	要從中擷取快照集的使用者指定來源物件標識碼。
type	True	SnapshotObjectType	要從中擷取快照集之來源對象的使用者指定類型。 目前支援FaceList、PersonGroup、LargeFaceList和 LargePersonGroup。
userData		string	用戶針對任何用途指定快照集的相關數據。 長度不應超過 16 KB。

回應

名稱	類型	Description
202 Accepted		快照集擷取工作已成功排入佇列。 標題 Operation-Location: string
Other Status Codes	APIError	錯誤回應。

安全性

Ocp-Apim-Subscription-Key

類型: apiKey
位於: header

範例

Take a snapshot example

範例要求

HTTP

POST {Endpoint}/face/v1.0-preview/snapshots


{
  "type": "FaceList",
  "objectId": "source-face-list-id",
  "applyScope": [
    "35230F59-AA9C-45E0-AB5E-C859BF1A5429",
    "64084E07-9B7F-4A98-BEA4-9986D3A1EDEB"
  ],
  "userData": "User-provided data attached to the snapshot."
}

範例回覆

狀態碼:

202

定義

名稱	Description
APIError	API 傳回的錯誤資訊
Error	錯誤本文。
SnapshotObjectType	快照集中來源對象的類型，由呼叫 Snapshot - Take 時建立快照集的訂閱者所指定。 目前支援FaceList、PersonGroup、LargeFaceList和 LargePersonGroup。
TakeSnapshotRequest	要求擷取快照集作業的本文。

APIError

API 傳回的錯誤資訊

名稱	類型	Description
error	Error	錯誤本文。

Error

錯誤本文。

名稱	類型	Description
code	string
message	string

SnapshotObjectType

快照集中來源對象的類型，由呼叫 Snapshot - Take 時建立快照集的訂閱者所指定。 目前支援FaceList、PersonGroup、LargeFaceList和 LargePersonGroup。

名稱	類型	Description
FaceList	string
LargeFaceList	string
LargePersonGroup	string
PersonGroup	string

TakeSnapshotRequest

要求擷取快照集作業的本文。

名稱	類型	Description
applyScope	string[]	使用者指定的快照集目標臉部訂用帳戶標識碼數位。 對於每個快照集，只有套用快照集範圍中包含的訂用帳戶 - 擷取可以套用它。
objectId	string	要從中擷取快照集的使用者指定來源物件標識碼。
type	SnapshotObjectType	要從中擷取快照集之來源對象的使用者指定類型。 目前支援FaceList、PersonGroup、LargeFaceList和 LargePersonGroup。
userData	string	用戶針對任何用途指定快照集的相關數據。 長度不應超過 16 KB。