Snapshot - Take

Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.
The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.
Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".
Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.
Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.
Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.

  • Free-tier subscription quota: 100 take operations per month.
  • S0-tier subscription quota: 100 take operations per day.
POST {Endpoint}/face/v1.0-preview/snapshots

URI Parameters

Name In Required Type Description
Endpoint
path True

string

Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).

Request Header

Name Required Type Description
Ocp-Apim-Subscription-Key True

string

Request Body

Name Required Type Description
applyScope True

string[]

User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.

objectId True

string

User specified source object id to take snapshot from.

type True

SnapshotObjectType

User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported.

userData

string

User specified data about the snapshot for any purpose. Length should not exceed 16KB.

Responses

Name Type Description
202 Accepted

The snapshot taking task was queued successfully.

Headers

Operation-Location: string

Other Status Codes

APIError

Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Take a snapshot example

Sample request

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."
}

Sample response

Definitions

Name Description
APIError

Error information returned by the API

Error

Error body.

SnapshotObjectType

Type of the source object in the snapshot, specified by the subscriber who created the snapshot when calling Snapshot - Take. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported.

TakeSnapshotRequest

Request body for taking snapshot operation.

APIError

Error information returned by the API

Name Type Description
error

Error

Error body.

Error

Error body.

Name Type Description
code

string

message

string

SnapshotObjectType

Type of the source object in the snapshot, specified by the subscriber who created the snapshot when calling Snapshot - Take. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported.

Name Type Description
FaceList

string

LargeFaceList

string

LargePersonGroup

string

PersonGroup

string

TakeSnapshotRequest

Request body for taking snapshot operation.

Name Type Description
applyScope

string[]

User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.

objectId

string

User specified source object id to take snapshot from.

type

SnapshotObjectType

User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported.

userData

string

User specified data about the snapshot for any purpose. Length should not exceed 16KB.