Snapshot - Apply

Service:

Azure AI Services

API Version:

1.0-preview

Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.
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.
Applying 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 applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".
Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour 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. So the target subscription is required to apply the snapshot in 48 hours since its creation.
Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes 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.
One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.

• Free-tier subscription quota: 100 apply operations per month.
• S0-tier subscription quota: 100 apply operations per day.

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

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).
snapshotId	path	True	string uuid	Id referencing a particular snapshot.

Request Header

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

Request Body

Name	Required	Type	Description
objectId	True	string	User specified target object id to be created from the snapshot.
mode		SnapshotApplyMode	Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.

Responses

Name	Type	Description
202 Accepted		The snapshot applying task was queued successfully. Headers Operation-Location: string
Other Status Codes	APIError	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Apply snapshot example

Sample request

HTTP

POST {Endpoint}/face/v1.0-preview/snapshots/e58b3f08-1e8b-4165-81df-aa9858f233dc/apply


{
  "objectId": "target-face-list-id",
  "mode": "CreateNew"
}

Sample response

Status code:

202

Definitions

Name	Description
APIError	Error information returned by the API
ApplySnapshotRequest	Request body for applying snapshot operation.
Error	Error body.
SnapshotApplyMode	Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.

APIError

Error information returned by the API

Name	Type	Description
error	Error	Error body.

ApplySnapshotRequest

Request body for applying snapshot operation.

Name	Type	Default value	Description
mode	SnapshotApplyMode	CreateNew	Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.
objectId	string		User specified target object id to be created from the snapshot.

Error

Error body.

Name	Type	Description
code	string
message	string

SnapshotApplyMode

Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.

Name	Type	Description
CreateNew	string