package face
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License. See License.txt in the project root for license information.
//
// Code generated by Microsoft (R) AutoRest Code Generator.
// Changes may cause incorrect behavior and will be lost if the code is regenerated.
import (
"context"
"github.com/Azure/go-autorest/autorest"
"github.com/Azure/go-autorest/autorest/azure"
"github.com/Azure/go-autorest/autorest/validation"
"github.com/Azure/go-autorest/tracing"
"github.com/gofrs/uuid"
"net/http"
)
// SnapshotClient is the an API for face detection, verification, and identification.
type SnapshotClient struct {
BaseClient
}
// NewSnapshotClient creates an instance of the SnapshotClient client.
func NewSnapshotClient(endpoint string) SnapshotClient {
return SnapshotClient{New(endpoint)}
}
// Apply 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.
// Parameters:
// snapshotID - id referencing a particular snapshot.
// body - request body for applying a snapshot.
func (client SnapshotClient) Apply(ctx context.Context, snapshotID uuid.UUID, body ApplySnapshotRequest) (result autorest.Response, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/SnapshotClient.Apply")
defer func() {
sc := -1
if result.Response != nil {
sc = result.Response.StatusCode
}
tracing.EndSpan(ctx, sc, err)
}()
}
if err := validation.Validate([]validation.Validation{
{TargetValue: body,
Constraints: []validation.Constraint{{Target: "body.ObjectID", Name: validation.Null, Rule: true,
Chain: []validation.Constraint{{Target: "body.ObjectID", Name: validation.MaxLength, Rule: 64, Chain: nil},
{Target: "body.ObjectID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil},
}}}}}); err != nil {
return result, validation.NewError("face.SnapshotClient", "Apply", err.Error())
}
req, err := client.ApplyPreparer(ctx, snapshotID, body)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Apply", nil, "Failure preparing request")
return
}
resp, err := client.ApplySender(req)
if err != nil {
result.Response = resp
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Apply", resp, "Failure sending request")
return
}
result, err = client.ApplyResponder(resp)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Apply", resp, "Failure responding to request")
return
}
return
}
// ApplyPreparer prepares the Apply request.
func (client SnapshotClient) ApplyPreparer(ctx context.Context, snapshotID uuid.UUID, body ApplySnapshotRequest) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
pathParameters := map[string]interface{}{
"snapshotId": autorest.Encode("path", snapshotID),
}
preparer := autorest.CreatePreparer(
autorest.AsContentType("application/json; charset=utf-8"),
autorest.AsPost(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
autorest.WithPathParameters("/snapshots/{snapshotId}/apply", pathParameters),
autorest.WithJSON(body))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
// ApplySender sends the Apply request. The method will close the
// http.Response Body if it receives an error.
func (client SnapshotClient) ApplySender(req *http.Request) (*http.Response, error) {
return client.Send(req, autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...))
}
// ApplyResponder handles the response to the Apply request. The method always
// closes the http.Response Body.
func (client SnapshotClient) ApplyResponder(resp *http.Response) (result autorest.Response, err error) {
err = autorest.Respond(
resp,
azure.WithErrorUnlessStatusCode(http.StatusOK, http.StatusAccepted),
autorest.ByClosing())
result.Response = resp
return
}
// Delete delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will
// also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not
// delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation.
// Parameters:
// snapshotID - id referencing a particular snapshot.
func (client SnapshotClient) Delete(ctx context.Context, snapshotID uuid.UUID) (result autorest.Response, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/SnapshotClient.Delete")
defer func() {
sc := -1
if result.Response != nil {
sc = result.Response.StatusCode
}
tracing.EndSpan(ctx, sc, err)
}()
}
req, err := client.DeletePreparer(ctx, snapshotID)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Delete", nil, "Failure preparing request")
return
}
resp, err := client.DeleteSender(req)
if err != nil {
result.Response = resp
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Delete", resp, "Failure sending request")
return
}
result, err = client.DeleteResponder(resp)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Delete", resp, "Failure responding to request")
return
}
return
}
// DeletePreparer prepares the Delete request.
func (client SnapshotClient) DeletePreparer(ctx context.Context, snapshotID uuid.UUID) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
pathParameters := map[string]interface{}{
"snapshotId": autorest.Encode("path", snapshotID),
}
preparer := autorest.CreatePreparer(
autorest.AsDelete(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
autorest.WithPathParameters("/snapshots/{snapshotId}", pathParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
// DeleteSender sends the Delete request. The method will close the
// http.Response Body if it receives an error.
func (client SnapshotClient) DeleteSender(req *http.Request) (*http.Response, error) {
return client.Send(req, autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...))
}
// DeleteResponder handles the response to the Delete request. The method always
// closes the http.Response Body.
func (client SnapshotClient) DeleteResponder(resp *http.Response) (result autorest.Response, err error) {
err = autorest.Respond(
resp,
azure.WithErrorUnlessStatusCode(http.StatusOK),
autorest.ByClosing())
result.Response = resp
return
}
// Get retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and
// target subscriptions included in the applyScope in Snapshot - Take.
// Parameters:
// snapshotID - id referencing a particular snapshot.
func (client SnapshotClient) Get(ctx context.Context, snapshotID uuid.UUID) (result Snapshot, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/SnapshotClient.Get")
defer func() {
sc := -1
if result.Response.Response != nil {
sc = result.Response.Response.StatusCode
}
tracing.EndSpan(ctx, sc, err)
}()
}
req, err := client.GetPreparer(ctx, snapshotID)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Get", nil, "Failure preparing request")
return
}
resp, err := client.GetSender(req)
if err != nil {
result.Response = autorest.Response{Response: resp}
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Get", resp, "Failure sending request")
return
}
result, err = client.GetResponder(resp)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Get", resp, "Failure responding to request")
return
}
return
}
// GetPreparer prepares the Get request.
func (client SnapshotClient) GetPreparer(ctx context.Context, snapshotID uuid.UUID) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
pathParameters := map[string]interface{}{
"snapshotId": autorest.Encode("path", snapshotID),
}
preparer := autorest.CreatePreparer(
autorest.AsGet(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
autorest.WithPathParameters("/snapshots/{snapshotId}", pathParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
// GetSender sends the Get request. The method will close the
// http.Response Body if it receives an error.
func (client SnapshotClient) GetSender(req *http.Request) (*http.Response, error) {
return client.Send(req, autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...))
}
// GetResponder handles the response to the Get request. The method always
// closes the http.Response Body.
func (client SnapshotClient) GetResponder(resp *http.Response) (result Snapshot, err error) {
err = autorest.Respond(
resp,
azure.WithErrorUnlessStatusCode(http.StatusOK),
autorest.ByUnmarshallingJSON(&result),
autorest.ByClosing())
result.Response = autorest.Response{Response: resp}
return
}
// GetOperationStatus retrieve the status of a take/apply snapshot operation.
// Parameters:
// operationID - id referencing a particular take/apply snapshot operation.
func (client SnapshotClient) GetOperationStatus(ctx context.Context, operationID uuid.UUID) (result OperationStatus, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/SnapshotClient.GetOperationStatus")
defer func() {
sc := -1
if result.Response.Response != nil {
sc = result.Response.Response.StatusCode
}
tracing.EndSpan(ctx, sc, err)
}()
}
req, err := client.GetOperationStatusPreparer(ctx, operationID)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "GetOperationStatus", nil, "Failure preparing request")
return
}
resp, err := client.GetOperationStatusSender(req)
if err != nil {
result.Response = autorest.Response{Response: resp}
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "GetOperationStatus", resp, "Failure sending request")
return
}
result, err = client.GetOperationStatusResponder(resp)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "GetOperationStatus", resp, "Failure responding to request")
return
}
return
}
// GetOperationStatusPreparer prepares the GetOperationStatus request.
func (client SnapshotClient) GetOperationStatusPreparer(ctx context.Context, operationID uuid.UUID) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
pathParameters := map[string]interface{}{
"operationId": autorest.Encode("path", operationID),
}
preparer := autorest.CreatePreparer(
autorest.AsGet(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
autorest.WithPathParameters("/operations/{operationId}", pathParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
// GetOperationStatusSender sends the GetOperationStatus request. The method will close the
// http.Response Body if it receives an error.
func (client SnapshotClient) GetOperationStatusSender(req *http.Request) (*http.Response, error) {
return client.Send(req, autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...))
}
// GetOperationStatusResponder handles the response to the GetOperationStatus request. The method always
// closes the http.Response Body.
func (client SnapshotClient) GetOperationStatusResponder(resp *http.Response) (result OperationStatus, err error) {
err = autorest.Respond(
resp,
azure.WithErrorUnlessStatusCode(http.StatusOK),
autorest.ByUnmarshallingJSON(&result),
autorest.ByClosing())
result.Response = autorest.Response{Response: resp}
return
}
// List list all accessible snapshots with related information, including snapshots that were taken by the user, or
// snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take).
// Parameters:
// typeParameter - user specified object type as a search filter.
// applyScope - user specified snapshot apply scopes as a search filter. ApplyScope is an array of the target
// Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take.
func (client SnapshotClient) List(ctx context.Context, typeParameter SnapshotObjectType, applyScope []uuid.UUID) (result ListSnapshot, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/SnapshotClient.List")
defer func() {
sc := -1
if result.Response.Response != nil {
sc = result.Response.Response.StatusCode
}
tracing.EndSpan(ctx, sc, err)
}()
}
req, err := client.ListPreparer(ctx, typeParameter, applyScope)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "List", nil, "Failure preparing request")
return
}
resp, err := client.ListSender(req)
if err != nil {
result.Response = autorest.Response{Response: resp}
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "List", resp, "Failure sending request")
return
}
result, err = client.ListResponder(resp)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "List", resp, "Failure responding to request")
return
}
return
}
// ListPreparer prepares the List request.
func (client SnapshotClient) ListPreparer(ctx context.Context, typeParameter SnapshotObjectType, applyScope []uuid.UUID) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
queryParameters := map[string]interface{}{}
if len(string(typeParameter)) > 0 {
queryParameters["type"] = autorest.Encode("query", typeParameter)
}
if applyScope != nil && len(applyScope) > 0 {
queryParameters["applyScope"] = autorest.Encode("query", applyScope, ",")
}
preparer := autorest.CreatePreparer(
autorest.AsGet(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
autorest.WithPath("/snapshots"),
autorest.WithQueryParameters(queryParameters))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
// ListSender sends the List request. The method will close the
// http.Response Body if it receives an error.
func (client SnapshotClient) ListSender(req *http.Request) (*http.Response, error) {
return client.Send(req, autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...))
}
// ListResponder handles the response to the List request. The method always
// closes the http.Response Body.
func (client SnapshotClient) ListResponder(resp *http.Response) (result ListSnapshot, err error) {
err = autorest.Respond(
resp,
azure.WithErrorUnlessStatusCode(http.StatusOK),
autorest.ByUnmarshallingJSON(&result.Value),
autorest.ByClosing())
result.Response = autorest.Response{Response: resp}
return
}
// 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.
// Parameters:
// body - request body for taking a snapshot.
func (client SnapshotClient) Take(ctx context.Context, body TakeSnapshotRequest) (result autorest.Response, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/SnapshotClient.Take")
defer func() {
sc := -1
if result.Response != nil {
sc = result.Response.StatusCode
}
tracing.EndSpan(ctx, sc, err)
}()
}
if err := validation.Validate([]validation.Validation{
{TargetValue: body,
Constraints: []validation.Constraint{{Target: "body.ObjectID", Name: validation.Null, Rule: true,
Chain: []validation.Constraint{{Target: "body.ObjectID", Name: validation.MaxLength, Rule: 64, Chain: nil},
{Target: "body.ObjectID", Name: validation.Pattern, Rule: `^[a-z0-9-_]+$`, Chain: nil},
}},
{Target: "body.ApplyScope", Name: validation.Null, Rule: true, Chain: nil},
{Target: "body.UserData", Name: validation.Null, Rule: false,
Chain: []validation.Constraint{{Target: "body.UserData", Name: validation.MaxLength, Rule: 16384, Chain: nil}}}}}}); err != nil {
return result, validation.NewError("face.SnapshotClient", "Take", err.Error())
}
req, err := client.TakePreparer(ctx, body)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Take", nil, "Failure preparing request")
return
}
resp, err := client.TakeSender(req)
if err != nil {
result.Response = resp
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Take", resp, "Failure sending request")
return
}
result, err = client.TakeResponder(resp)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Take", resp, "Failure responding to request")
return
}
return
}
// TakePreparer prepares the Take request.
func (client SnapshotClient) TakePreparer(ctx context.Context, body TakeSnapshotRequest) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
preparer := autorest.CreatePreparer(
autorest.AsContentType("application/json; charset=utf-8"),
autorest.AsPost(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
autorest.WithPath("/snapshots"),
autorest.WithJSON(body))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
// TakeSender sends the Take request. The method will close the
// http.Response Body if it receives an error.
func (client SnapshotClient) TakeSender(req *http.Request) (*http.Response, error) {
return client.Send(req, autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...))
}
// TakeResponder handles the response to the Take request. The method always
// closes the http.Response Body.
func (client SnapshotClient) TakeResponder(resp *http.Response) (result autorest.Response, err error) {
err = autorest.Respond(
resp,
azure.WithErrorUnlessStatusCode(http.StatusOK, http.StatusAccepted),
autorest.ByClosing())
result.Response = resp
return
}
// Update update the information of a snapshot. Only the source subscription who took the snapshot can update the
// snapshot.
// Parameters:
// snapshotID - id referencing a particular snapshot.
// body - request body for updating a snapshot.
func (client SnapshotClient) Update(ctx context.Context, snapshotID uuid.UUID, body UpdateSnapshotRequest) (result autorest.Response, err error) {
if tracing.IsEnabled() {
ctx = tracing.StartSpan(ctx, fqdn+"/SnapshotClient.Update")
defer func() {
sc := -1
if result.Response != nil {
sc = result.Response.StatusCode
}
tracing.EndSpan(ctx, sc, err)
}()
}
req, err := client.UpdatePreparer(ctx, snapshotID, body)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Update", nil, "Failure preparing request")
return
}
resp, err := client.UpdateSender(req)
if err != nil {
result.Response = resp
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Update", resp, "Failure sending request")
return
}
result, err = client.UpdateResponder(resp)
if err != nil {
err = autorest.NewErrorWithError(err, "face.SnapshotClient", "Update", resp, "Failure responding to request")
return
}
return
}
// UpdatePreparer prepares the Update request.
func (client SnapshotClient) UpdatePreparer(ctx context.Context, snapshotID uuid.UUID, body UpdateSnapshotRequest) (*http.Request, error) {
urlParameters := map[string]interface{}{
"Endpoint": client.Endpoint,
}
pathParameters := map[string]interface{}{
"snapshotId": autorest.Encode("path", snapshotID),
}
preparer := autorest.CreatePreparer(
autorest.AsContentType("application/json; charset=utf-8"),
autorest.AsPatch(),
autorest.WithCustomBaseURL("{Endpoint}/face/v1.0", urlParameters),
autorest.WithPathParameters("/snapshots/{snapshotId}", pathParameters),
autorest.WithJSON(body))
return preparer.Prepare((&http.Request{}).WithContext(ctx))
}
// UpdateSender sends the Update request. The method will close the
// http.Response Body if it receives an error.
func (client SnapshotClient) UpdateSender(req *http.Request) (*http.Response, error) {
return client.Send(req, autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...))
}
// UpdateResponder handles the response to the Update request. The method always
// closes the http.Response Body.
func (client SnapshotClient) UpdateResponder(resp *http.Response) (result autorest.Response, err error) {
err = autorest.Respond(
resp,
azure.WithErrorUnlessStatusCode(http.StatusOK),
autorest.ByClosing())
result.Response = resp
return
}