diff --git a/packages/@azure/cognitiveservices-face/LICENSE.txt b/packages/@azure/cognitiveservices-face/LICENSE.txt index 5431ba98b936..8f3d856145c5 100644 --- a/packages/@azure/cognitiveservices-face/LICENSE.txt +++ b/packages/@azure/cognitiveservices-face/LICENSE.txt @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2018 Microsoft +Copyright (c) 2019 Microsoft Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/packages/@azure/cognitiveservices-face/README.md b/packages/@azure/cognitiveservices-face/README.md index 750819382ef7..10774c0f6160 100644 --- a/packages/@azure/cognitiveservices-face/README.md +++ b/packages/@azure/cognitiveservices-face/README.md @@ -9,7 +9,7 @@ This package contains an isomorphic SDK for FaceClient. ### How to Install -``` +```bash npm install @azure/cognitiveservices-face ``` @@ -19,13 +19,13 @@ npm install @azure/cognitiveservices-face ##### Install @azure/ms-rest-nodeauth -``` +```bash npm install @azure/ms-rest-nodeauth ``` ##### Sample code -```ts +```typescript import * as msRest from "@azure/ms-rest-js"; import * as msRestNodeAuth from "@azure/ms-rest-nodeauth"; import { FaceClient, FaceModels, FaceMappers } from "@azure/cognitiveservices-face"; @@ -49,7 +49,7 @@ msRestNodeAuth.interactiveLogin().then((creds) => { ##### Install @azure/ms-rest-browserauth -``` +```bash npm install @azure/ms-rest-browserauth ``` @@ -98,6 +98,3 @@ See https://github.com/Azure/ms-rest-browserauth to learn how to authenticate to ## Related projects - [Microsoft Azure SDK for Javascript](https://github.com/Azure/azure-sdk-for-js) - - -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fpackages%2F%40azure%2Fcognitiveservices-face%2FREADME.png) diff --git a/packages/@azure/cognitiveservices-face/lib/faceClient.ts b/packages/@azure/cognitiveservices-face/lib/faceClient.ts index 3fef6fece7c7..5ff32b3a1af4 100644 --- a/packages/@azure/cognitiveservices-face/lib/faceClient.ts +++ b/packages/@azure/cognitiveservices-face/lib/faceClient.ts @@ -23,6 +23,7 @@ class FaceClient extends FaceClientContext { largePersonGroupPerson: operations.LargePersonGroupPerson; largePersonGroup: operations.LargePersonGroupOperations; largeFaceList: operations.LargeFaceListOperations; + snapshot: operations.SnapshotOperations; /** * Initializes a new instance of the FaceClient class. @@ -40,6 +41,7 @@ class FaceClient extends FaceClientContext { this.largePersonGroupPerson = new operations.LargePersonGroupPerson(this); this.largePersonGroup = new operations.LargePersonGroupOperations(this); this.largeFaceList = new operations.LargeFaceListOperations(this); + this.snapshot = new operations.SnapshotOperations(this); } } diff --git a/packages/@azure/cognitiveservices-face/lib/faceClientContext.ts b/packages/@azure/cognitiveservices-face/lib/faceClientContext.ts index 0aab84a539fc..52112d92a093 100644 --- a/packages/@azure/cognitiveservices-face/lib/faceClientContext.ts +++ b/packages/@azure/cognitiveservices-face/lib/faceClientContext.ts @@ -11,7 +11,7 @@ import * as msRest from "@azure/ms-rest-js"; const packageName = "@azure/cognitiveservices-face"; -const packageVersion = "0.1.0"; +const packageVersion = "2.2.0"; export class FaceClientContext extends msRest.ServiceClient { endpoint: string; diff --git a/packages/@azure/cognitiveservices-face/lib/models/faceListOperationsMappers.ts b/packages/@azure/cognitiveservices-face/lib/models/faceListOperationsMappers.ts index 9be9b19aec6f..d952bcf47a51 100644 --- a/packages/@azure/cognitiveservices-face/lib/models/faceListOperationsMappers.ts +++ b/packages/@azure/cognitiveservices-face/lib/models/faceListOperationsMappers.ts @@ -9,6 +9,7 @@ */ export { + MetaDataContract, NameAndUserDataContract, APIError, ErrorModel, diff --git a/packages/@azure/cognitiveservices-face/lib/models/index.ts b/packages/@azure/cognitiveservices-face/lib/models/index.ts index 9f721780116c..7ceecbc80f7a 100644 --- a/packages/@azure/cognitiveservices-face/lib/models/index.ts +++ b/packages/@azure/cognitiveservices-face/lib/models/index.ts @@ -465,7 +465,7 @@ export interface FaceAttributes { age?: number; /** * @member {Gender} [gender] Possible gender of the face. Possible values - * include: 'male', 'female', 'genderless' + * include: 'male', 'female' */ gender?: Gender; /** @@ -538,6 +538,11 @@ export interface DetectedFace { * @member {string} [faceId] */ faceId?: string; + /** + * @member {RecognitionModel} [recognitionModel] Possible values include: + * 'recognition_01', 'recognition_02'. Default value: 'recognition_01' . + */ + recognitionModel?: RecognitionModel; /** * @member {FaceRectangle} faceRectangle */ @@ -570,7 +575,7 @@ export interface FindSimilarRequest { * face list, created in Face List - Create a Face List. Face list contains a * set of persistedFaceIds which are persisted and will never expire. * Parameter faceListId, largeFaceListId and faceIds should not be provided - * at the same time。 + * at the same time. */ faceListId?: string; /** @@ -854,14 +859,30 @@ export interface NameAndUserDataContract { userData?: string; } +/** + * @interface + * An interface representing MetaDataContract. + * A combination of user defined name and user specified data and recognition + * model name for largePersonGroup/personGroup, and largeFaceList/faceList. + * + * @extends NameAndUserDataContract + */ +export interface MetaDataContract extends NameAndUserDataContract { + /** + * @member {RecognitionModel} [recognitionModel] Possible values include: + * 'recognition_01', 'recognition_02'. Default value: 'recognition_01' . + */ + recognitionModel?: RecognitionModel; +} + /** * @interface * An interface representing FaceList. * Face list object. * - * @extends NameAndUserDataContract + * @extends MetaDataContract */ -export interface FaceList extends NameAndUserDataContract { +export interface FaceList extends MetaDataContract { /** * @member {string} faceListId FaceListId of the target face list. */ @@ -878,9 +899,9 @@ export interface FaceList extends NameAndUserDataContract { * An interface representing PersonGroup. * Person group object. * - * @extends NameAndUserDataContract + * @extends MetaDataContract */ -export interface PersonGroup extends NameAndUserDataContract { +export interface PersonGroup extends MetaDataContract { /** * @member {string} personGroupId PersonGroupId of the target person group. */ @@ -912,9 +933,9 @@ export interface Person extends NameAndUserDataContract { * An interface representing LargeFaceList. * Large face list object. * - * @extends NameAndUserDataContract + * @extends MetaDataContract */ -export interface LargeFaceList extends NameAndUserDataContract { +export interface LargeFaceList extends MetaDataContract { /** * @member {string} largeFaceListId LargeFaceListId of the target large face * list. @@ -927,9 +948,9 @@ export interface LargeFaceList extends NameAndUserDataContract { * An interface representing LargePersonGroup. * Large person group object. * - * @extends NameAndUserDataContract + * @extends MetaDataContract */ -export interface LargePersonGroup extends NameAndUserDataContract { +export interface LargePersonGroup extends MetaDataContract { /** * @member {string} largePersonGroupId LargePersonGroupId of the target large * person groups @@ -996,6 +1017,183 @@ export interface TrainingStatus { message?: string; } +/** + * @interface + * An interface representing ApplySnapshotRequest. + * Request body for applying snapshot operation. + * + */ +export interface ApplySnapshotRequest { + /** + * @member {string} objectId User specified target object id to be created + * from the snapshot. + */ + objectId: string; + /** + * @member {SnapshotApplyMode} [mode] 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. Possible values include: 'CreateNew'. Default value: + * 'CreateNew' . + */ + mode?: SnapshotApplyMode; +} + +/** + * @interface + * An interface representing Snapshot. + * Snapshot object. + * + */ +export interface Snapshot { + /** + * @member {string} id Snapshot id. + */ + id: string; + /** + * @member {string} account Azure Cognitive Service Face account id of the + * subscriber who created the snapshot by Snapshot - Take. + */ + account: string; + /** + * @member {SnapshotObjectType} type 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. Possible values include: 'FaceList', + * 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + */ + type: SnapshotObjectType; + /** + * @member {string[]} applyScope Array of the target Face subscription ids + * for the snapshot, specified by the user who created the snapshot when + * calling Snapshot - Take. For each snapshot, only subscriptions included in + * the applyScope of Snapshot - Take can apply it. + */ + applyScope: string[]; + /** + * @member {string} [userData] User specified data about the snapshot for any + * purpose. Length should not exceed 16KB. + */ + userData?: string; + /** + * @member {Date} createdTime A combined UTC date and time string that + * describes the created time of the snapshot. E.g. + * 2018-12-25T11:41:02.2331413Z. + */ + createdTime: Date; + /** + * @member {Date} lastUpdateTime A combined UTC date and time string that + * describes the last time when the snapshot was created or updated by + * Snapshot - Update. E.g. 2018-12-25T11:51:27.8705696Z. + */ + lastUpdateTime: Date; +} + +/** + * @interface + * An interface representing TakeSnapshotRequest. + * Request body for taking snapshot operation. + * + */ +export interface TakeSnapshotRequest { + /** + * @member {SnapshotObjectType} type User specified type for the source + * object to take snapshot from. Currently FaceList, PersonGroup, + * LargeFaceList and LargePersonGroup are supported. Possible values include: + * 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + */ + type: SnapshotObjectType; + /** + * @member {string} objectId User specified source object id to take snapshot + * from. + */ + objectId: string; + /** + * @member {string[]} applyScope 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. + */ + applyScope: string[]; + /** + * @member {string} [userData] User specified data about the snapshot for any + * purpose. Length should not exceed 16KB. + */ + userData?: string; +} + +/** + * @interface + * An interface representing UpdateSnapshotRequest. + * Request body for updating a snapshot, with a combination of user defined + * apply scope and user specified data. + * + */ +export interface UpdateSnapshotRequest { + /** + * @member {string[]} [applyScope] Array of the target Face subscription ids + * for the snapshot, specified by the user who created the snapshot when + * calling Snapshot - Take. For each snapshot, only subscriptions included in + * the applyScope of Snapshot - Take can apply it. + */ + applyScope?: string[]; + /** + * @member {string} [userData] User specified data about the snapshot for any + * purpose. Length should not exceed 16KB. + */ + userData?: string; +} + +/** + * @interface + * An interface representing OperationStatus. + * Operation status object. Operation refers to the asynchronous backend task + * including taking a snapshot and applying a snapshot. + * + */ +export interface OperationStatus { + /** + * @member {OperationStatusType} status Operation status: notstarted, + * running, succeeded, failed. If the operation is requested and waiting to + * perform, the status is notstarted. If the operation is ongoing in backend, + * the status is running. Status succeeded means the operation is completed + * successfully, specifically for snapshot taking operation, it illustrates + * the snapshot is well taken and ready to apply, and for snapshot applying + * operation, it presents the target object has finished creating by the + * snapshot and ready to be used. Status failed is often caused by editing + * the source object while taking the snapshot or editing the target object + * while applying the snapshot before completion, see the field "message" to + * check the failure reason. Possible values include: 'notstarted', + * 'running', 'succeeded', 'failed' + */ + status: OperationStatusType; + /** + * @member {Date} createdTime A combined UTC date and time string that + * describes the time when the operation (take or apply a snapshot) is + * requested. E.g. 2018-12-25T11:41:02.2331413Z. + */ + createdTime: Date; + /** + * @member {Date} [lastActionTime] A combined UTC date and time string that + * describes the last time the operation (take or apply a snapshot) is + * actively migrating data. The lastActionTime will keep increasing until the + * operation finishes. E.g. 2018-12-25T11:51:27.8705696Z. + */ + lastActionTime?: Date; + /** + * @member {string} [resourceLocation] When the operation succeeds + * successfully, for snapshot taking operation the snapshot id will be + * included in this field, and for snapshot applying operation, the path to + * get the target object will be returned in this field. + */ + resourceLocation?: string; + /** + * @member {string} [message] Show failure message when operation fails + * (omitted when operation succeeds). + */ + message?: string; +} + /** * @interface * An interface representing ImageUrl. @@ -1020,7 +1218,7 @@ export interface FaceFindSimilarOptionalParams extends msRest.RequestOptionsBase * face list, created in Face List - Create a Face List. Face list contains a * set of persistedFaceIds which are persisted and will never expire. * Parameter faceListId, largeFaceListId and faceIds should not be provided - * at the same time。 + * at the same time. */ faceListId?: string; /** @@ -1114,6 +1312,23 @@ export interface FaceDetectWithUrlOptionalParams extends msRest.RequestOptionsBa * each face attribute analysis has additional computational and time cost. */ returnFaceAttributes?: FaceAttributeType[]; + /** + * @member {RecognitionModel} [recognitionModel] Name of recognition model. + * Recognition model is used when the face features are extracted and + * associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A + * recognition model name can be provided when performing Face - Detect or + * (Large)FaceList - Create or (Large)PersonGroup - Create. The default value + * is 'recognition_01', if latest model needed, please explicitly specify the + * model you need. Possible values include: 'recognition_01', + * 'recognition_02'. Default value: 'recognition_01' . + */ + recognitionModel?: RecognitionModel; + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; } /** @@ -1167,6 +1382,23 @@ export interface FaceDetectWithStreamOptionalParams extends msRest.RequestOption * each face attribute analysis has additional computational and time cost. */ returnFaceAttributes?: FaceAttributeType[]; + /** + * @member {RecognitionModel} [recognitionModel] Name of recognition model. + * Recognition model is used when the face features are extracted and + * associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A + * recognition model name can be provided when performing Face - Detect or + * (Large)FaceList - Create or (Large)PersonGroup - Create. The default value + * is 'recognition_01', if latest model needed, please explicitly specify the + * model you need. Possible values include: 'recognition_01', + * 'recognition_02'. Default value: 'recognition_01' . + */ + recognitionModel?: RecognitionModel; + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; } /** @@ -1307,6 +1539,27 @@ export interface PersonGroupCreateOptionalParams extends msRest.RequestOptionsBa * 16KB. */ userData?: string; + /** + * @member {RecognitionModel} [recognitionModel] Possible values include: + * 'recognition_01', 'recognition_02'. Default value: 'recognition_01' . + */ + recognitionModel?: RecognitionModel; +} + +/** + * @interface + * An interface representing PersonGroupGetOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface PersonGroupGetOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; } /** @@ -1346,6 +1599,12 @@ export interface PersonGroupListOptionalParams extends msRest.RequestOptionsBase * 1000 . */ top?: number; + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; } /** @@ -1365,6 +1624,27 @@ export interface FaceListCreateOptionalParams extends msRest.RequestOptionsBase * 16KB. */ userData?: string; + /** + * @member {RecognitionModel} [recognitionModel] Possible values include: + * 'recognition_01', 'recognition_02'. Default value: 'recognition_01' . + */ + recognitionModel?: RecognitionModel; +} + +/** + * @interface + * An interface representing FaceListGetOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface FaceListGetOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; } /** @@ -1386,6 +1666,22 @@ export interface FaceListUpdateOptionalParams extends msRest.RequestOptionsBase userData?: string; } +/** + * @interface + * An interface representing FaceListListOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface FaceListListOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; +} + /** * @interface * An interface representing FaceListAddFaceFromUrlOptionalParams. @@ -1572,6 +1868,27 @@ export interface LargePersonGroupCreateOptionalParams extends msRest.RequestOpti * 16KB. */ userData?: string; + /** + * @member {RecognitionModel} [recognitionModel] Possible values include: + * 'recognition_01', 'recognition_02'. Default value: 'recognition_01' . + */ + recognitionModel?: RecognitionModel; +} + +/** + * @interface + * An interface representing LargePersonGroupGetOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface LargePersonGroupGetOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; } /** @@ -1611,6 +1928,12 @@ export interface LargePersonGroupListOptionalParams extends msRest.RequestOption * value: 1000 . */ top?: number; + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; } /** @@ -1630,6 +1953,27 @@ export interface LargeFaceListCreateOptionalParams extends msRest.RequestOptions * 16KB. */ userData?: string; + /** + * @member {RecognitionModel} [recognitionModel] Possible values include: + * 'recognition_01', 'recognition_02'. Default value: 'recognition_01' . + */ + recognitionModel?: RecognitionModel; +} + +/** + * @interface + * An interface representing LargeFaceListGetOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface LargeFaceListGetOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; } /** @@ -1651,6 +1995,22 @@ export interface LargeFaceListUpdateOptionalParams extends msRest.RequestOptions userData?: string; } +/** + * @interface + * An interface representing LargeFaceListListOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface LargeFaceListListOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {boolean} [returnRecognitionModel] A value indicating whether the + * operation should return 'recognitionModel' in response. Default value: + * false . + */ + returnRecognitionModel?: boolean; +} + /** * @interface * An interface representing LargeFaceListUpdateFaceOptionalParams. @@ -1734,13 +2094,131 @@ export interface LargeFaceListAddFaceFromStreamOptionalParams extends msRest.Req targetFace?: number[]; } +/** + * @interface + * An interface representing SnapshotTakeOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface SnapshotTakeOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {string} [userData] User specified data about the snapshot for any + * purpose. Length should not exceed 16KB. + */ + userData?: string; +} + +/** + * @interface + * An interface representing SnapshotListOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface SnapshotListOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {SnapshotObjectType} [type] User specified object type as a search + * filter. Possible values include: 'FaceList', 'LargeFaceList', + * 'LargePersonGroup', 'PersonGroup' + */ + type?: SnapshotObjectType; + /** + * @member {string[]} [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. + */ + applyScope?: string[]; +} + +/** + * @interface + * An interface representing SnapshotUpdateOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface SnapshotUpdateOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {string[]} [applyScope] Array of the target Face subscription ids + * for the snapshot, specified by the user who created the snapshot when + * calling Snapshot - Take. For each snapshot, only subscriptions included in + * the applyScope of Snapshot - Take can apply it. + */ + applyScope?: string[]; + /** + * @member {string} [userData] User specified data about the snapshot for any + * purpose. Length should not exceed 16KB. + */ + userData?: string; +} + +/** + * @interface + * An interface representing SnapshotApplyOptionalParams. + * Optional Parameters. + * + * @extends RequestOptionsBase + */ +export interface SnapshotApplyOptionalParams extends msRest.RequestOptionsBase { + /** + * @member {SnapshotApplyMode} [mode] 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. Possible values include: 'CreateNew'. Default value: + * 'CreateNew' . + */ + mode?: SnapshotApplyMode; +} + +/** + * @interface + * An interface representing SnapshotTakeHeaders. + * Defines headers for Take operation. + * + */ +export interface SnapshotTakeHeaders { + /** + * @member {string} [operationLocation] Operation location with an operation + * id used to track the progress of taking snapshot. The returned id is the + * operation id, rather than snapshot id. Snapshot id can be obtained only + * when the operation status becomes "succeeded" in OperationStatus - Get. + */ + operationLocation: string; +} + +/** + * @interface + * An interface representing SnapshotApplyHeaders. + * Defines headers for Apply operation. + * + */ +export interface SnapshotApplyHeaders { + /** + * @member {string} [operationLocation] Operation location with an operation + * id used to track the progress of applying the snapshot by OperationStatus + * - Get. + */ + operationLocation: string; +} + +/** + * Defines values for RecognitionModel. + * Possible values include: 'recognition_01', 'recognition_02' + * @readonly + * @enum {string} + */ +export type RecognitionModel = 'recognition_01' | 'recognition_02'; + /** * Defines values for Gender. - * Possible values include: 'male', 'female', 'genderless' + * Possible values include: 'male', 'female' * @readonly * @enum {string} */ -export type Gender = 'male' | 'female' | 'genderless'; +export type Gender = 'male' | 'female'; /** * Defines values for GlassesType. @@ -1806,6 +2284,30 @@ export type FindSimilarMatchMode = 'matchPerson' | 'matchFace'; */ export type TrainingStatusType = 'nonstarted' | 'running' | 'succeeded' | 'failed'; +/** + * Defines values for SnapshotApplyMode. + * Possible values include: 'CreateNew' + * @readonly + * @enum {string} + */ +export type SnapshotApplyMode = 'CreateNew'; + +/** + * Defines values for SnapshotObjectType. + * Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @readonly + * @enum {string} + */ +export type SnapshotObjectType = 'FaceList' | 'LargeFaceList' | 'LargePersonGroup' | 'PersonGroup'; + +/** + * Defines values for OperationStatusType. + * Possible values include: 'notstarted', 'running', 'succeeded', 'failed' + * @readonly + * @enum {string} + */ +export type OperationStatusType = 'notstarted' | 'running' | 'succeeded' | 'failed'; + /** * Defines values for FaceAttributeType. * Possible values include: 'age', 'gender', 'headPose', 'smile', 'facialHair', 'glasses', @@ -2498,3 +3000,90 @@ export type LargeFaceListAddFaceFromStreamResponse = PersistedFace & { parsedBody: PersistedFace; }; }; + +/** + * Contains response data for the take operation. + */ +export type SnapshotTakeResponse = SnapshotTakeHeaders & { + /** + * The underlying HTTP response. + */ + _response: msRest.HttpResponse & { + /** + * The parsed HTTP response headers. + */ + parsedHeaders: SnapshotTakeHeaders; + }; +}; + +/** + * Contains response data for the list operation. + */ +export type SnapshotListResponse = Array & { + /** + * The underlying HTTP response. + */ + _response: msRest.HttpResponse & { + /** + * The response body as text (string format) + */ + bodyAsText: string; + /** + * The response body as parsed JSON or XML + */ + parsedBody: Snapshot[]; + }; +}; + +/** + * Contains response data for the get operation. + */ +export type SnapshotGetResponse = Snapshot & { + /** + * The underlying HTTP response. + */ + _response: msRest.HttpResponse & { + /** + * The response body as text (string format) + */ + bodyAsText: string; + /** + * The response body as parsed JSON or XML + */ + parsedBody: Snapshot; + }; +}; + +/** + * Contains response data for the apply operation. + */ +export type SnapshotApplyResponse = SnapshotApplyHeaders & { + /** + * The underlying HTTP response. + */ + _response: msRest.HttpResponse & { + /** + * The parsed HTTP response headers. + */ + parsedHeaders: SnapshotApplyHeaders; + }; +}; + +/** + * Contains response data for the getOperationStatus operation. + */ +export type SnapshotGetOperationStatusResponse = OperationStatus & { + /** + * The underlying HTTP response. + */ + _response: msRest.HttpResponse & { + /** + * The response body as text (string format) + */ + bodyAsText: string; + /** + * The response body as parsed JSON or XML + */ + parsedBody: OperationStatus; + }; +}; diff --git a/packages/@azure/cognitiveservices-face/lib/models/largeFaceListOperationsMappers.ts b/packages/@azure/cognitiveservices-face/lib/models/largeFaceListOperationsMappers.ts index 2e388528472a..8fba6986942f 100644 --- a/packages/@azure/cognitiveservices-face/lib/models/largeFaceListOperationsMappers.ts +++ b/packages/@azure/cognitiveservices-face/lib/models/largeFaceListOperationsMappers.ts @@ -9,6 +9,7 @@ */ export { + MetaDataContract, NameAndUserDataContract, APIError, ErrorModel, diff --git a/packages/@azure/cognitiveservices-face/lib/models/largePersonGroupOperationsMappers.ts b/packages/@azure/cognitiveservices-face/lib/models/largePersonGroupOperationsMappers.ts index 99ed79ddce02..0a63319ef107 100644 --- a/packages/@azure/cognitiveservices-face/lib/models/largePersonGroupOperationsMappers.ts +++ b/packages/@azure/cognitiveservices-face/lib/models/largePersonGroupOperationsMappers.ts @@ -9,6 +9,7 @@ */ export { + MetaDataContract, NameAndUserDataContract, APIError, ErrorModel, diff --git a/packages/@azure/cognitiveservices-face/lib/models/largePersonGroupPersonMappers.ts b/packages/@azure/cognitiveservices-face/lib/models/largePersonGroupPersonMappers.ts index ad24b4b06ba7..6e4d194810cc 100644 --- a/packages/@azure/cognitiveservices-face/lib/models/largePersonGroupPersonMappers.ts +++ b/packages/@azure/cognitiveservices-face/lib/models/largePersonGroupPersonMappers.ts @@ -16,6 +16,7 @@ export { PersistedFace, UpdateFaceRequest, ImageUrl, + MetaDataContract, FaceList, PersonGroup, LargeFaceList, diff --git a/packages/@azure/cognitiveservices-face/lib/models/mappers.ts b/packages/@azure/cognitiveservices-face/lib/models/mappers.ts index 693512f304a8..c98bc63c10d2 100644 --- a/packages/@azure/cognitiveservices-face/lib/models/mappers.ts +++ b/packages/@azure/cognitiveservices-face/lib/models/mappers.ts @@ -698,8 +698,7 @@ export const FaceAttributes: msRest.CompositeMapper = { name: "Enum", allowedValues: [ "male", - "female", - "genderless" + "female" ] } }, @@ -812,6 +811,14 @@ export const DetectedFace: msRest.CompositeMapper = { name: "Uuid" } }, + recognitionModel: { + nullable: false, + serializedName: "recognitionModel", + defaultValue: 'recognition_01', + type: { + name: "String" + } + }, faceRectangle: { required: true, serializedName: "faceRectangle", @@ -1266,13 +1273,32 @@ export const NameAndUserDataContract: msRest.CompositeMapper = { } }; +export const MetaDataContract: msRest.CompositeMapper = { + serializedName: "MetaDataContract", + type: { + name: "Composite", + className: "MetaDataContract", + modelProperties: { + ...NameAndUserDataContract.type.modelProperties, + recognitionModel: { + nullable: false, + serializedName: "recognitionModel", + defaultValue: 'recognition_01', + type: { + name: "String" + } + } + } + } +}; + export const FaceList: msRest.CompositeMapper = { serializedName: "FaceList", type: { name: "Composite", className: "FaceList", modelProperties: { - ...NameAndUserDataContract.type.modelProperties, + ...MetaDataContract.type.modelProperties, faceListId: { required: true, serializedName: "faceListId", @@ -1306,7 +1332,7 @@ export const PersonGroup: msRest.CompositeMapper = { name: "Composite", className: "PersonGroup", modelProperties: { - ...NameAndUserDataContract.type.modelProperties, + ...MetaDataContract.type.modelProperties, personGroupId: { required: true, serializedName: "personGroupId", @@ -1357,7 +1383,7 @@ export const LargeFaceList: msRest.CompositeMapper = { name: "Composite", className: "LargeFaceList", modelProperties: { - ...NameAndUserDataContract.type.modelProperties, + ...MetaDataContract.type.modelProperties, largeFaceListId: { required: true, serializedName: "largeFaceListId", @@ -1379,7 +1405,7 @@ export const LargePersonGroup: msRest.CompositeMapper = { name: "Composite", className: "LargePersonGroup", modelProperties: { - ...NameAndUserDataContract.type.modelProperties, + ...MetaDataContract.type.modelProperties, largePersonGroupId: { required: true, serializedName: "largePersonGroupId", @@ -1462,6 +1488,243 @@ export const TrainingStatus: msRest.CompositeMapper = { } }; +export const ApplySnapshotRequest: msRest.CompositeMapper = { + serializedName: "ApplySnapshotRequest", + type: { + name: "Composite", + className: "ApplySnapshotRequest", + modelProperties: { + objectId: { + required: true, + serializedName: "objectId", + constraints: { + MaxLength: 64, + Pattern: /^[a-z0-9-_]+$/ + }, + type: { + name: "String" + } + }, + mode: { + nullable: false, + serializedName: "mode", + defaultValue: 'CreateNew', + type: { + name: "Enum", + allowedValues: [ + "CreateNew" + ] + } + } + } + } +}; + +export const Snapshot: msRest.CompositeMapper = { + serializedName: "Snapshot", + type: { + name: "Composite", + className: "Snapshot", + modelProperties: { + id: { + required: true, + serializedName: "id", + type: { + name: "Uuid" + } + }, + account: { + required: true, + serializedName: "account", + type: { + name: "String" + } + }, + type: { + required: true, + serializedName: "type", + type: { + name: "Enum", + allowedValues: [ + "FaceList", + "LargeFaceList", + "LargePersonGroup", + "PersonGroup" + ] + } + }, + applyScope: { + required: true, + serializedName: "applyScope", + type: { + name: "Sequence", + element: { + type: { + name: "Uuid" + } + } + } + }, + userData: { + serializedName: "userData", + constraints: { + MaxLength: 16384 + }, + type: { + name: "String" + } + }, + createdTime: { + required: true, + serializedName: "createdTime", + type: { + name: "DateTime" + } + }, + lastUpdateTime: { + required: true, + serializedName: "lastUpdateTime", + type: { + name: "DateTime" + } + } + } + } +}; + +export const TakeSnapshotRequest: msRest.CompositeMapper = { + serializedName: "TakeSnapshotRequest", + type: { + name: "Composite", + className: "TakeSnapshotRequest", + modelProperties: { + type: { + required: true, + serializedName: "type", + type: { + name: "Enum", + allowedValues: [ + "FaceList", + "LargeFaceList", + "LargePersonGroup", + "PersonGroup" + ] + } + }, + objectId: { + required: true, + serializedName: "objectId", + constraints: { + MaxLength: 64, + Pattern: /^[a-z0-9-_]+$/ + }, + type: { + name: "String" + } + }, + applyScope: { + required: true, + serializedName: "applyScope", + type: { + name: "Sequence", + element: { + type: { + name: "Uuid" + } + } + } + }, + userData: { + serializedName: "userData", + constraints: { + MaxLength: 16384 + }, + type: { + name: "String" + } + } + } + } +}; + +export const UpdateSnapshotRequest: msRest.CompositeMapper = { + serializedName: "UpdateSnapshotRequest", + type: { + name: "Composite", + className: "UpdateSnapshotRequest", + modelProperties: { + applyScope: { + serializedName: "applyScope", + type: { + name: "Sequence", + element: { + type: { + name: "Uuid" + } + } + } + }, + userData: { + serializedName: "userData", + constraints: { + MaxLength: 16384 + }, + type: { + name: "String" + } + } + } + } +}; + +export const OperationStatus: msRest.CompositeMapper = { + serializedName: "OperationStatus", + type: { + name: "Composite", + className: "OperationStatus", + modelProperties: { + status: { + required: true, + serializedName: "status", + type: { + name: "Enum", + allowedValues: [ + "notstarted", + "running", + "succeeded", + "failed" + ] + } + }, + createdTime: { + required: true, + serializedName: "createdTime", + type: { + name: "DateTime" + } + }, + lastActionTime: { + serializedName: "lastActionTime", + type: { + name: "DateTime" + } + }, + resourceLocation: { + serializedName: "resourceLocation", + type: { + name: "String" + } + }, + message: { + serializedName: "message", + type: { + name: "String" + } + } + } + } +}; + export const ImageUrl: msRest.CompositeMapper = { serializedName: "ImageUrl", type: { @@ -1478,3 +1741,35 @@ export const ImageUrl: msRest.CompositeMapper = { } } }; + +export const SnapshotTakeHeaders: msRest.CompositeMapper = { + serializedName: "snapshot-take-headers", + type: { + name: "Composite", + className: "SnapshotTakeHeaders", + modelProperties: { + operationLocation: { + serializedName: "operation-location", + type: { + name: "String" + } + } + } + } +}; + +export const SnapshotApplyHeaders: msRest.CompositeMapper = { + serializedName: "snapshot-apply-headers", + type: { + name: "Composite", + className: "SnapshotApplyHeaders", + modelProperties: { + operationLocation: { + serializedName: "operation-location", + type: { + name: "String" + } + } + } + } +}; diff --git a/packages/@azure/cognitiveservices-face/lib/models/parameters.ts b/packages/@azure/cognitiveservices-face/lib/models/parameters.ts index 64e028ad1b77..61b2aea41366 100644 --- a/packages/@azure/cognitiveservices-face/lib/models/parameters.ts +++ b/packages/@azure/cognitiveservices-face/lib/models/parameters.ts @@ -10,6 +10,24 @@ import * as msRest from "@azure/ms-rest-js"; +export const applyScope: msRest.OperationQueryParameter = { + parameterPath: [ + "options", + "applyScope" + ], + mapper: { + serializedName: "applyScope", + type: { + name: "Sequence", + element: { + type: { + name: "Uuid" + } + } + } + }, + collectionFormat: msRest.QueryCollectionFormat.Csv +}; export const endpoint: msRest.OperationURLParameter = { parameterPath: "endpoint", mapper: { @@ -64,6 +82,16 @@ export const largePersonGroupId: msRest.OperationURLParameter = { } } }; +export const operationId: msRest.OperationURLParameter = { + parameterPath: "operationId", + mapper: { + required: true, + serializedName: "operationId", + type: { + name: "Uuid" + } + } +}; export const persistedFaceId: msRest.OperationURLParameter = { parameterPath: "persistedFaceId", mapper: { @@ -98,6 +126,20 @@ export const personId: msRest.OperationURLParameter = { } } }; +export const recognitionModel: msRest.OperationQueryParameter = { + parameterPath: [ + "options", + "recognitionModel" + ], + mapper: { + nullable: false, + serializedName: "recognitionModel", + defaultValue: 'recognition_01', + type: { + name: "String" + } + } +}; export const returnFaceAttributes: msRest.OperationQueryParameter = { parameterPath: [ "options", @@ -158,6 +200,29 @@ export const returnFaceLandmarks: msRest.OperationQueryParameter = { } } }; +export const returnRecognitionModel: msRest.OperationQueryParameter = { + parameterPath: [ + "options", + "returnRecognitionModel" + ], + mapper: { + serializedName: "returnRecognitionModel", + defaultValue: false, + type: { + name: "Boolean" + } + } +}; +export const snapshotId: msRest.OperationURLParameter = { + parameterPath: "snapshotId", + mapper: { + required: true, + serializedName: "snapshotId", + type: { + name: "Uuid" + } + } +}; export const start0: msRest.OperationQueryParameter = { parameterPath: [ "options", @@ -236,6 +301,24 @@ export const top1: msRest.OperationQueryParameter = { } } }; +export const type: msRest.OperationQueryParameter = { + parameterPath: [ + "options", + "type" + ], + mapper: { + serializedName: "type", + type: { + name: "Enum", + allowedValues: [ + "FaceList", + "LargeFaceList", + "LargePersonGroup", + "PersonGroup" + ] + } + } +}; export const userData: msRest.OperationQueryParameter = { parameterPath: [ "options", diff --git a/packages/@azure/cognitiveservices-face/lib/models/personGroupOperationsMappers.ts b/packages/@azure/cognitiveservices-face/lib/models/personGroupOperationsMappers.ts index 56dfb55d9382..9b0f1466efdd 100644 --- a/packages/@azure/cognitiveservices-face/lib/models/personGroupOperationsMappers.ts +++ b/packages/@azure/cognitiveservices-face/lib/models/personGroupOperationsMappers.ts @@ -9,6 +9,7 @@ */ export { + MetaDataContract, NameAndUserDataContract, APIError, ErrorModel, diff --git a/packages/@azure/cognitiveservices-face/lib/models/personGroupPersonMappers.ts b/packages/@azure/cognitiveservices-face/lib/models/personGroupPersonMappers.ts index ad24b4b06ba7..6e4d194810cc 100644 --- a/packages/@azure/cognitiveservices-face/lib/models/personGroupPersonMappers.ts +++ b/packages/@azure/cognitiveservices-face/lib/models/personGroupPersonMappers.ts @@ -16,6 +16,7 @@ export { PersistedFace, UpdateFaceRequest, ImageUrl, + MetaDataContract, FaceList, PersonGroup, LargeFaceList, diff --git a/packages/@azure/cognitiveservices-face/lib/models/snapshotOperationsMappers.ts b/packages/@azure/cognitiveservices-face/lib/models/snapshotOperationsMappers.ts new file mode 100644 index 000000000000..7b6eabb1de82 --- /dev/null +++ b/packages/@azure/cognitiveservices-face/lib/models/snapshotOperationsMappers.ts @@ -0,0 +1,22 @@ +/* + * 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. + */ + +export { + TakeSnapshotRequest, + SnapshotTakeHeaders, + APIError, + ErrorModel, + Snapshot, + UpdateSnapshotRequest, + ApplySnapshotRequest, + SnapshotApplyHeaders, + OperationStatus +} from "../models/mappers"; + diff --git a/packages/@azure/cognitiveservices-face/lib/operations/face.ts b/packages/@azure/cognitiveservices-face/lib/operations/face.ts index ae38fa7c5305..dec44526182f 100644 --- a/packages/@azure/cognitiveservices-face/lib/operations/face.ts +++ b/packages/@azure/cognitiveservices-face/lib/operations/face.ts @@ -27,8 +27,23 @@ export class Face { } /** - * Given query face's faceId, find the similar-looking faces from a faceId array, a face list or a - * large face list. + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list + * or a large face list. faceId array contains the faces created by [Face - + * Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will + * expire 24 hours after creation. A "faceListId" is created by [FaceList - + * Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing + * persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - + * Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing + * persistedFaceIds that will also not expire. Depending on the input the returned similar faces + * list contains faceIds or persistedFaceIds ranked by similarity. + *
Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the + * default mode that it tries to find faces of the same person as possible by using internal + * same-person thresholds. It is useful to find a known person's other photos. Note that an empty + * list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores + * same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It + * can be used in the cases like searching celebrity-looking faces. + *
The 'recognitionModel' associated with the query face's faceId should be the same as the + * 'recognitionModel' used by the target faceId array, face list or large face list. * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid * faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call * @param [options] The optional parameters @@ -59,7 +74,18 @@ export class Face { } /** - * Divide candidate faces into groups based on face similarity. + * Divide candidate faces into groups based on face similarity.
+ * * The output is one or more disjointed face groups and a messyGroup. A face group contains faces + * that have similar looking, often of the same person. Face groups are ranked by group size, i.e. + * number of faces. Notice that faces belonging to a same person might be split into several groups + * in the result. + * * MessyGroup is a special face group containing faces that cannot find any similar counterpart + * face from original faces. The messyGroup will not appear in the result if all faces found their + * counterparts. + * * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - + * Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you + * only have 2 candidate faces. + * * The 'recognitionModel' associated with the query faces' faceIds should be the same. * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces * @param [options] The optional parameters * @returns Promise @@ -89,6 +115,31 @@ export class Face { /** * 1-to-many identification to find the closest matches of the specific query person face from a * person group or large person group. + *
For each face in the faceIds array, Face Identify will compute similarities between the + * query face and all the faces in the person group (given by personGroupId) or large person group + * (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity + * confidence. The person group/large person group should be trained to make it ready for + * identification. See more in [PersonGroup - + * Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and + * [LargePersonGroup - + * Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + *
+ * + * Remarks:
+ * * The algorithm allows more than one face to be identified independently at the same request, + * but no more than 10 faces. + * * Each person in the person group/large person group could have more than one face, but no more + * than 248 faces. + * * Higher face image quality means better identification precision. Please consider high-quality + * faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * * Number of candidates returned is restricted by maxNumOfCandidatesReturned and + * confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * * Try [Face - Find + * Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you + * need to find similar faces from a face list/large face list instead of a person group/large + * person group. + * * The 'recognitionModel' associated with the query faces' faceIds should be the same as the + * 'recognitionModel' used by the target person group or large person group. * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are * identified independently. The valid number of faceIds is between [1, 10]. * @param [options] The optional parameters @@ -120,6 +171,13 @@ export class Face { /** * Verify whether two faces belong to a same person or whether one face belongs to a person. + *
+ * Remarks:
+ * * Higher face image quality means better identification precision. Please consider high-quality + * faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * * For the scenarios that are sensitive to accuracy please make your own judgment. + * * The 'recognitionModel' associated with the query faces' faceIds should be the same as the + * 'recognitionModel' used by the target face, person group or large person group. * @param faceId1 FaceId of the first face, comes from Face - Detect * @param faceId2 FaceId of the second face, comes from Face - Detect * @param [options] The optional parameters @@ -151,8 +209,39 @@ export class Face { } /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, - * landmarks, and attributes. + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, + * and attributes.
+ * * Optional parameters including faceId, landmarks, and attributes. Attributes include age, + * gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, + * blur, exposure and noise. + * * The extracted face feature, instead of the actual image, will be stored on server. The faceId + * is an identifier of the face feature and will be used in [Face - + * Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - + * Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face + * - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It + * will expire 24 hours after the detection call. + * * Higher face image quality means better detection and recognition precision. Please consider + * high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or + * bigger. + * * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is + * from 1KB to 6MB. + * * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small + * but clear faces, please try to enlarge the input image. + * * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from + * large to small. + * * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be + * detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image + * orientation. + * * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, + * occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. HeadPose's + * pitch value is a reserved field and will always return 0. + * * Different 'recognitionModel' values are provided. If follow-up operations like Verify, + * Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' + * parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, + * please explicitly specify the model you need in this parameter. Once specified, the detected + * faceIds will be associated with the specified recognition model. More details, please refer to + * [How to specify a recognition + * model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model) * @param url Publicly reachable URL of an image * @param [options] The optional parameters * @returns Promise @@ -418,7 +507,9 @@ const detectWithUrlOperationSpec: msRest.OperationSpec = { queryParameters: [ Parameters.returnFaceId, Parameters.returnFaceLandmarks, - Parameters.returnFaceAttributes + Parameters.returnFaceAttributes, + Parameters.recognitionModel, + Parameters.returnRecognitionModel ], requestBody: { parameterPath: { @@ -495,7 +586,9 @@ const detectWithStreamOperationSpec: msRest.OperationSpec = { queryParameters: [ Parameters.returnFaceId, Parameters.returnFaceLandmarks, - Parameters.returnFaceAttributes + Parameters.returnFaceAttributes, + Parameters.recognitionModel, + Parameters.returnRecognitionModel ], requestBody: { parameterPath: "image", diff --git a/packages/@azure/cognitiveservices-face/lib/operations/faceListOperations.ts b/packages/@azure/cognitiveservices-face/lib/operations/faceListOperations.ts index bda8061fe344..b7e010c9b2b9 100644 --- a/packages/@azure/cognitiveservices-face/lib/operations/faceListOperations.ts +++ b/packages/@azure/cognitiveservices-face/lib/operations/faceListOperations.ts @@ -27,7 +27,29 @@ export class FaceListOperations { } /** - * Create an empty face list. Up to 64 face lists are allowed to exist in one subscription. + * Create an empty face list with user-specified faceListId, name, an optional userData and + * recognitionModel. Up to 64 face lists are allowed in one subscription. + *
Face list is a list of faces, up to 1,000 faces, and used by [Face - Find + * Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + *
After creation, user should use [FaceList - Add + * Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the + * faces. Faces are stored on server until [FaceList - + * Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + *
Find Similar is used for scenario like finding celebrity-like faces, similar face + * filtering, or as a light way face identification. But if the actual use is to identify person, + * please use + * [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / + * [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) + * and [Face - + * Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + *
Please consider + * [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) + * when the face number is large. It can support up to 1,000,000 faces. 'recognitionModel' should + * be specified to associate with this face list. The default value for 'recognitionModel' is + * 'recognition_01', if the latest model needed, please explicitly specify the model you need in + * this parameter. New faces that are added to an existing face list will use the recognition model + * that's already associated with the collection. Existing face features in a face list can't be + * updated to features extracted by another version of recognition model. * @param faceListId Id referencing a particular face list. * @param [options] The optional parameters * @returns Promise @@ -55,12 +77,12 @@ export class FaceListOperations { } /** - * Retrieve a face list's information. + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. * @param faceListId Id referencing a particular face list. * @param [options] The optional parameters * @returns Promise */ - get(faceListId: string, options?: msRest.RequestOptionsBase): Promise; + get(faceListId: string, options?: Models.FaceListGetOptionalParams): Promise; /** * @param faceListId Id referencing a particular face list. * @param callback The callback @@ -71,8 +93,8 @@ export class FaceListOperations { * @param options The optional parameters * @param callback The callback */ - get(faceListId: string, options: msRest.RequestOptionsBase, callback: msRest.ServiceCallback): void; - get(faceListId: string, options?: msRest.RequestOptionsBase | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + get(faceListId: string, options: Models.FaceListGetOptionalParams, callback: msRest.ServiceCallback): void; + get(faceListId: string, options?: Models.FaceListGetOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { return this.client.sendOperationRequest( { faceListId, @@ -140,12 +162,13 @@ export class FaceListOperations { } /** - * Retrieve information about all existing face lists. Only faceListId, name and userData will be - * returned. + * List face lists’ faceListId, name, userData and recognitionModel.
+ * To get face information inside faceList use [FaceList - + * Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c) * @param [options] The optional parameters * @returns Promise */ - list(options?: msRest.RequestOptionsBase): Promise; + list(options?: Models.FaceListListOptionalParams): Promise; /** * @param callback The callback */ @@ -154,8 +177,8 @@ export class FaceListOperations { * @param options The optional parameters * @param callback The callback */ - list(options: msRest.RequestOptionsBase, callback: msRest.ServiceCallback): void; - list(options?: msRest.RequestOptionsBase | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + list(options: Models.FaceListListOptionalParams, callback: msRest.ServiceCallback): void; + list(options?: Models.FaceListListOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { return this.client.sendOperationRequest( { options @@ -165,7 +188,7 @@ export class FaceListOperations { } /** - * Delete an existing face from a face list (given by a persisitedFaceId and a faceListId). + * Delete an existing face from a face list (given by a persistedFaceId and a faceListId). * Persisted image related to the face will also be deleted. * @param faceListId Id referencing a particular face list. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. @@ -282,10 +305,14 @@ const createOperationSpec: msRest.OperationSpec = { userData: [ "options", "userData" + ], + recognitionModel: [ + "options", + "recognitionModel" ] }, mapper: { - ...Mappers.NameAndUserDataContract, + ...Mappers.MetaDataContract, required: true } }, @@ -305,6 +332,9 @@ const getOperationSpec: msRest.OperationSpec = { Parameters.endpoint, Parameters.faceListId ], + queryParameters: [ + Parameters.returnRecognitionModel + ], responses: { 200: { bodyMapper: Mappers.FaceList @@ -370,6 +400,9 @@ const listOperationSpec: msRest.OperationSpec = { urlParameters: [ Parameters.endpoint ], + queryParameters: [ + Parameters.returnRecognitionModel + ], responses: { 200: { bodyMapper: { diff --git a/packages/@azure/cognitiveservices-face/lib/operations/index.ts b/packages/@azure/cognitiveservices-face/lib/operations/index.ts index 4f9969dd7949..3a6f9ae466be 100644 --- a/packages/@azure/cognitiveservices-face/lib/operations/index.ts +++ b/packages/@azure/cognitiveservices-face/lib/operations/index.ts @@ -15,3 +15,4 @@ export * from "./faceListOperations"; export * from "./largePersonGroupPerson"; export * from "./largePersonGroupOperations"; export * from "./largeFaceListOperations"; +export * from "./snapshotOperations"; diff --git a/packages/@azure/cognitiveservices-face/lib/operations/largeFaceListOperations.ts b/packages/@azure/cognitiveservices-face/lib/operations/largeFaceListOperations.ts index 51a8c7752845..e5b8a4d00f38 100644 --- a/packages/@azure/cognitiveservices-face/lib/operations/largeFaceListOperations.ts +++ b/packages/@azure/cognitiveservices-face/lib/operations/largeFaceListOperations.ts @@ -27,8 +27,35 @@ export class LargeFaceListOperations { } /** - * Create an empty large face list. Up to 64 large face lists are allowed to exist in one - * subscription. + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData + * and recognitionModel. + *
Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find + * Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + *
After creation, user should use [LargeFaceList Face - + * Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the + * faces and [LargeFaceList - + * Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it + * ready for [Face - + * FindSimilar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). Faces + * are stored on server until [LargeFaceList - + * Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + *
Find Similar is used for scenario like finding celebrity-like faces, similar face + * filtering, or as a light way face identification. But if the actual use is to identify person, + * please use + * [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / + * [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) + * and [Face - + * Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + *
+ * * Free-tier subscription quota: 64 large face lists. + * * S0-tier subscription quota: 1,000,000 large face lists. + *
+ * 'recognitionModel' should be specified to associate with this large face list. The default value + * for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly + * specify the model you need in this parameter. New faces that are added to an existing large face + * list will use the recognition model that's already associated with the collection. Existing face + * features in a large face list can't be updated to features extracted by another version of + * recognition model. * @param largeFaceListId Id referencing a particular large face list. * @param [options] The optional parameters * @returns Promise @@ -56,12 +83,12 @@ export class LargeFaceListOperations { } /** - * Retrieve a large face list's information. + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. * @param largeFaceListId Id referencing a particular large face list. * @param [options] The optional parameters * @returns Promise */ - get(largeFaceListId: string, options?: msRest.RequestOptionsBase): Promise; + get(largeFaceListId: string, options?: Models.LargeFaceListGetOptionalParams): Promise; /** * @param largeFaceListId Id referencing a particular large face list. * @param callback The callback @@ -72,8 +99,8 @@ export class LargeFaceListOperations { * @param options The optional parameters * @param callback The callback */ - get(largeFaceListId: string, options: msRest.RequestOptionsBase, callback: msRest.ServiceCallback): void; - get(largeFaceListId: string, options?: msRest.RequestOptionsBase | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + get(largeFaceListId: string, options: Models.LargeFaceListGetOptionalParams, callback: msRest.ServiceCallback): void; + get(largeFaceListId: string, options?: Models.LargeFaceListGetOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { return this.client.sendOperationRequest( { largeFaceListId, @@ -169,12 +196,26 @@ export class LargeFaceListOperations { } /** - * Retrieve information about all existing large face lists. Only largeFaceListId, name and - * userData will be returned. + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel.
+ * To get face information inside largeFaceList use [LargeFaceList Face - + * Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)
+ * * Large face lists are stored in alphabetical order of largeFaceListId. + * * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned + * entries have larger ids by string comparison. "start" set to empty to indicate return from the + * first item. + * * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 + * entries can be returned in one call. To fetch more, you can specify "start" with the last + * returned entry’s Id of the current call. + *
+ * For example, total 5 large person lists: "list1", ..., "list5". + *
"start=&top=" will return all 5 lists. + *
"start=&top=2" will return "list1", "list2". + *
"start=list2&top=3" will return "list3", "list4", "list5". * @param [options] The optional parameters * @returns Promise */ - list(options?: msRest.RequestOptionsBase): Promise; + list(options?: Models.LargeFaceListListOptionalParams): Promise; /** * @param callback The callback */ @@ -183,8 +224,8 @@ export class LargeFaceListOperations { * @param options The optional parameters * @param callback The callback */ - list(options: msRest.RequestOptionsBase, callback: msRest.ServiceCallback): void; - list(options?: msRest.RequestOptionsBase | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + list(options: Models.LargeFaceListListOptionalParams, callback: msRest.ServiceCallback): void; + list(options?: Models.LargeFaceListListOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { return this.client.sendOperationRequest( { options @@ -222,7 +263,7 @@ export class LargeFaceListOperations { } /** - * Delete an existing face from a large face list (given by a persisitedFaceId and a + * Delete an existing face from a large face list (given by a persistedFaceId and a * largeFaceListId). Persisted image related to the face will also be deleted. * @param largeFaceListId Id referencing a particular large face list. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. @@ -435,10 +476,14 @@ const createOperationSpec: msRest.OperationSpec = { userData: [ "options", "userData" + ], + recognitionModel: [ + "options", + "recognitionModel" ] }, mapper: { - ...Mappers.NameAndUserDataContract, + ...Mappers.MetaDataContract, required: true } }, @@ -458,6 +503,9 @@ const getOperationSpec: msRest.OperationSpec = { Parameters.endpoint, Parameters.largeFaceListId ], + queryParameters: [ + Parameters.returnRecognitionModel + ], responses: { 200: { bodyMapper: Mappers.LargeFaceList @@ -541,6 +589,9 @@ const listOperationSpec: msRest.OperationSpec = { urlParameters: [ Parameters.endpoint ], + queryParameters: [ + Parameters.returnRecognitionModel + ], responses: { 200: { bodyMapper: { diff --git a/packages/@azure/cognitiveservices-face/lib/operations/largePersonGroupOperations.ts b/packages/@azure/cognitiveservices-face/lib/operations/largePersonGroupOperations.ts index 32d1d5222b01..695c31ac48fb 100644 --- a/packages/@azure/cognitiveservices-face/lib/operations/largePersonGroupOperations.ts +++ b/packages/@azure/cognitiveservices-face/lib/operations/largePersonGroupOperations.ts @@ -27,8 +27,30 @@ export class LargePersonGroupOperations { } /** - * Create a new large person group with specified largePersonGroupId, name and user-provided - * userData. + * Create a new large person group with user-specified largePersonGroupId, name, an optional + * userData and recognitionModel. + *
A large person group is the container of the uploaded person data, including face images + * and face recognition feature, and up to 1,000,000 people. + *
After creation, use [LargePersonGroup Person - + * Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add + * person into the group, and call [LargePersonGroup - + * Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this + * group ready for [Face - + * Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + *
The person face, image, and userData will be stored on server until [LargePersonGroup + * Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or + * [LargePersonGroup - + * Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + *
+ * * Free-tier subscription quota: 1,000 large person groups. + * * S0-tier subscription quota: 1,000,000 large person groups. + *
+ * 'recognitionModel' should be specified to associate with this large person group. The default + * value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly + * specify the model you need in this parameter. New faces that are added to an existing large + * person group will use the recognition model that's already associated with the collection. + * Existing face features in a large person group can't be updated to features extracted by another + * version of recognition model. * @param largePersonGroupId Id referencing a particular large person group. * @param [options] The optional parameters * @returns Promise @@ -85,12 +107,15 @@ export class LargePersonGroupOperations { } /** - * Retrieve the information of a large person group, including its name and userData. + * Retrieve the information of a large person group, including its name, userData and + * recognitionModel. This API returns large person group information only, use [LargePersonGroup + * Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) + * instead to retrieve person information under the large person group. * @param largePersonGroupId Id referencing a particular large person group. * @param [options] The optional parameters * @returns Promise */ - get(largePersonGroupId: string, options?: msRest.RequestOptionsBase): Promise; + get(largePersonGroupId: string, options?: Models.LargePersonGroupGetOptionalParams): Promise; /** * @param largePersonGroupId Id referencing a particular large person group. * @param callback The callback @@ -101,8 +126,8 @@ export class LargePersonGroupOperations { * @param options The optional parameters * @param callback The callback */ - get(largePersonGroupId: string, options: msRest.RequestOptionsBase, callback: msRest.ServiceCallback): void; - get(largePersonGroupId: string, options?: msRest.RequestOptionsBase | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + get(largePersonGroupId: string, options: Models.LargePersonGroupGetOptionalParams, callback: msRest.ServiceCallback): void; + get(largePersonGroupId: string, options?: Models.LargePersonGroupGetOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { return this.client.sendOperationRequest( { largePersonGroupId, @@ -170,7 +195,20 @@ export class LargePersonGroupOperations { } /** - * List large person groups and their information. + * List all existing large person groups’ largePersonGroupId, name, userData and + * recognitionModel.
+ * * Large person groups are stored in alphabetical order of largePersonGroupId. + * * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned + * entries have larger ids by string comparison. "start" set to empty to indicate return from the + * first item. + * * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 + * entries can be returned in one call. To fetch more, you can specify "start" with the last + * returned entry’s Id of the current call. + *
+ * For example, total 5 large person groups: "group1", ..., "group5". + *
"start=&top=" will return all 5 groups. + *
"start=&top=2" will return "group1", "group2". + *
"start=group2&top=3" will return "group3", "group4", "group5". * @param [options] The optional parameters * @returns Promise */ @@ -240,10 +278,14 @@ const createOperationSpec: msRest.OperationSpec = { userData: [ "options", "userData" + ], + recognitionModel: [ + "options", + "recognitionModel" ] }, mapper: { - ...Mappers.NameAndUserDataContract, + ...Mappers.MetaDataContract, required: true } }, @@ -279,6 +321,9 @@ const getOperationSpec: msRest.OperationSpec = { Parameters.endpoint, Parameters.largePersonGroupId ], + queryParameters: [ + Parameters.returnRecognitionModel + ], responses: { 200: { bodyMapper: Mappers.LargePersonGroup @@ -348,7 +393,8 @@ const listOperationSpec: msRest.OperationSpec = { ], queryParameters: [ Parameters.start1, - Parameters.top1 + Parameters.top1, + Parameters.returnRecognitionModel ], responses: { 200: { diff --git a/packages/@azure/cognitiveservices-face/lib/operations/personGroupOperations.ts b/packages/@azure/cognitiveservices-face/lib/operations/personGroupOperations.ts index 09a65a2a55c3..55f3f0ee776e 100644 --- a/packages/@azure/cognitiveservices-face/lib/operations/personGroupOperations.ts +++ b/packages/@azure/cognitiveservices-face/lib/operations/personGroupOperations.ts @@ -27,7 +27,32 @@ export class PersonGroupOperations { } /** - * Create a new person group with specified personGroupId, name and user-provided userData. + * Create a new person group with specified personGroupId, name, user-provided userData and + * recognitionModel. + *
A person group is the container of the uploaded person data, including face images and + * face recognition features. + *
After creation, use [PersonGroup Person - + * Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add + * persons into the group, and then call [PersonGroup - + * Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this + * group ready for [Face - + * Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + *
The person's face, image, and userData will be stored on server until [PersonGroup Person + * - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or + * [PersonGroup - + * Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + *
+ * * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * * to handle larger scale face identification problem, please consider using + * [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). + *
+ * 'recognitionModel' should be specified to associate with this person group. The default value + * for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly + * specify the model you need in this parameter. New faces that are added to an existing person + * group will use the recognition model that's already associated with the collection. Existing + * face features in a person group can't be updated to features extracted by another version of + * recognition model. * @param personGroupId Id referencing a particular person group. * @param [options] The optional parameters * @returns Promise @@ -84,12 +109,14 @@ export class PersonGroupOperations { } /** - * Retrieve the information of a person group, including its name and userData. + * Retrieve person group name, userData and recognitionModel. To get person information under this + * personGroup, use [PersonGroup Person - + * List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * @param personGroupId Id referencing a particular person group. * @param [options] The optional parameters * @returns Promise */ - get(personGroupId: string, options?: msRest.RequestOptionsBase): Promise; + get(personGroupId: string, options?: Models.PersonGroupGetOptionalParams): Promise; /** * @param personGroupId Id referencing a particular person group. * @param callback The callback @@ -100,8 +127,8 @@ export class PersonGroupOperations { * @param options The optional parameters * @param callback The callback */ - get(personGroupId: string, options: msRest.RequestOptionsBase, callback: msRest.ServiceCallback): void; - get(personGroupId: string, options?: msRest.RequestOptionsBase | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + get(personGroupId: string, options: Models.PersonGroupGetOptionalParams, callback: msRest.ServiceCallback): void; + get(personGroupId: string, options?: Models.PersonGroupGetOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { return this.client.sendOperationRequest( { personGroupId, @@ -169,7 +196,19 @@ export class PersonGroupOperations { } /** - * List person groups and their information. + * List person groups’ personGroupId, name, userData and recognitionModel.
+ * * Person groups are stored in alphabetical order of personGroupId. + * * "start" parameter (string, optional) is a user-provided personGroupId value that returned + * entries have larger ids by string comparison. "start" set to empty to indicate return from the + * first item. + * * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 + * entries can be returned in one call. To fetch more, you can specify "start" with the last + * returned entry’s Id of the current call. + *
+ * For example, total 5 person groups: "group1", ..., "group5". + *
"start=&top=" will return all 5 groups. + *
"start=&top=2" will return "group1", "group2". + *
"start=group2&top=3" will return "group3", "group4", "group5". * @param [options] The optional parameters * @returns Promise */ @@ -239,10 +278,14 @@ const createOperationSpec: msRest.OperationSpec = { userData: [ "options", "userData" + ], + recognitionModel: [ + "options", + "recognitionModel" ] }, mapper: { - ...Mappers.NameAndUserDataContract, + ...Mappers.MetaDataContract, required: true } }, @@ -278,6 +321,9 @@ const getOperationSpec: msRest.OperationSpec = { Parameters.endpoint, Parameters.personGroupId ], + queryParameters: [ + Parameters.returnRecognitionModel + ], responses: { 200: { bodyMapper: Mappers.PersonGroup @@ -347,7 +393,8 @@ const listOperationSpec: msRest.OperationSpec = { ], queryParameters: [ Parameters.start1, - Parameters.top1 + Parameters.top1, + Parameters.returnRecognitionModel ], responses: { 200: { diff --git a/packages/@azure/cognitiveservices-face/lib/operations/snapshotOperations.ts b/packages/@azure/cognitiveservices-face/lib/operations/snapshotOperations.ts new file mode 100644 index 000000000000..3d68784865ed --- /dev/null +++ b/packages/@azure/cognitiveservices-face/lib/operations/snapshotOperations.ts @@ -0,0 +1,486 @@ +/* + * 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 * as msRest from "@azure/ms-rest-js"; +import * as Models from "../models"; +import * as Mappers from "../models/snapshotOperationsMappers"; +import * as Parameters from "../models/parameters"; +import { FaceClientContext } from "../faceClientContext"; + +/** Class representing a SnapshotOperations. */ +export class SnapshotOperations { + private readonly client: FaceClientContext; + + /** + * Create a SnapshotOperations. + * @param {FaceClientContext} client Reference to the service client. + */ + constructor(client: FaceClientContext) { + this.client = client; + } + + /** + * 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. + * @param type User specified type for the source object to take snapshot from. Currently FaceList, + * PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: + * 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope 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. + * @param [options] The optional parameters + * @returns Promise + */ + take(type: Models.SnapshotObjectType, objectId: string, applyScope: string[], options?: Models.SnapshotTakeOptionalParams): Promise; + /** + * @param type User specified type for the source object to take snapshot from. Currently FaceList, + * PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: + * 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope 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. + * @param callback The callback + */ + take(type: Models.SnapshotObjectType, objectId: string, applyScope: string[], callback: msRest.ServiceCallback): void; + /** + * @param type User specified type for the source object to take snapshot from. Currently FaceList, + * PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: + * 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope 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. + * @param options The optional parameters + * @param callback The callback + */ + take(type: Models.SnapshotObjectType, objectId: string, applyScope: string[], options: Models.SnapshotTakeOptionalParams, callback: msRest.ServiceCallback): void; + take(type: Models.SnapshotObjectType, objectId: string, applyScope: string[], options?: Models.SnapshotTakeOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + return this.client.sendOperationRequest( + { + type, + objectId, + applyScope, + options + }, + takeOperationSpec, + callback) as Promise; + } + + /** + * 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). + * @param [options] The optional parameters + * @returns Promise + */ + list(options?: Models.SnapshotListOptionalParams): Promise; + /** + * @param callback The callback + */ + list(callback: msRest.ServiceCallback): void; + /** + * @param options The optional parameters + * @param callback The callback + */ + list(options: Models.SnapshotListOptionalParams, callback: msRest.ServiceCallback): void; + list(options?: Models.SnapshotListOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + return this.client.sendOperationRequest( + { + options + }, + listOperationSpec, + callback) as Promise; + } + + /** + * 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. + * @param snapshotId Id referencing a particular snapshot. + * @param [options] The optional parameters + * @returns Promise + */ + get(snapshotId: string, options?: msRest.RequestOptionsBase): Promise; + /** + * @param snapshotId Id referencing a particular snapshot. + * @param callback The callback + */ + get(snapshotId: string, callback: msRest.ServiceCallback): void; + /** + * @param snapshotId Id referencing a particular snapshot. + * @param options The optional parameters + * @param callback The callback + */ + get(snapshotId: string, options: msRest.RequestOptionsBase, callback: msRest.ServiceCallback): void; + get(snapshotId: string, options?: msRest.RequestOptionsBase | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + return this.client.sendOperationRequest( + { + snapshotId, + options + }, + getOperationSpec, + callback) as Promise; + } + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can + * update the snapshot. + * @param snapshotId Id referencing a particular snapshot. + * @param [options] The optional parameters + * @returns Promise + */ + update(snapshotId: string, options?: Models.SnapshotUpdateOptionalParams): Promise; + /** + * @param snapshotId Id referencing a particular snapshot. + * @param callback The callback + */ + update(snapshotId: string, callback: msRest.ServiceCallback): void; + /** + * @param snapshotId Id referencing a particular snapshot. + * @param options The optional parameters + * @param callback The callback + */ + update(snapshotId: string, options: Models.SnapshotUpdateOptionalParams, callback: msRest.ServiceCallback): void; + update(snapshotId: string, options?: Models.SnapshotUpdateOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + return this.client.sendOperationRequest( + { + snapshotId, + options + }, + updateOperationSpec, + callback); + } + + /** + * 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. + * @param snapshotId Id referencing a particular snapshot. + * @param [options] The optional parameters + * @returns Promise + */ + deleteMethod(snapshotId: string, options?: msRest.RequestOptionsBase): Promise; + /** + * @param snapshotId Id referencing a particular snapshot. + * @param callback The callback + */ + deleteMethod(snapshotId: string, callback: msRest.ServiceCallback): void; + /** + * @param snapshotId Id referencing a particular snapshot. + * @param options The optional parameters + * @param callback The callback + */ + deleteMethod(snapshotId: string, options: msRest.RequestOptionsBase, callback: msRest.ServiceCallback): void; + deleteMethod(snapshotId: string, options?: msRest.RequestOptionsBase | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + return this.client.sendOperationRequest( + { + snapshotId, + options + }, + deleteMethodOperationSpec, + callback); + } + + /** + * 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. + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param [options] The optional parameters + * @returns Promise + */ + apply(snapshotId: string, objectId: string, options?: Models.SnapshotApplyOptionalParams): Promise; + /** + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param callback The callback + */ + apply(snapshotId: string, objectId: string, callback: msRest.ServiceCallback): void; + /** + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param options The optional parameters + * @param callback The callback + */ + apply(snapshotId: string, objectId: string, options: Models.SnapshotApplyOptionalParams, callback: msRest.ServiceCallback): void; + apply(snapshotId: string, objectId: string, options?: Models.SnapshotApplyOptionalParams | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + return this.client.sendOperationRequest( + { + snapshotId, + objectId, + options + }, + applyOperationSpec, + callback) as Promise; + } + + /** + * Retrieve the status of a take/apply snapshot operation. + * @param operationId Id referencing a particular take/apply snapshot operation. + * @param [options] The optional parameters + * @returns Promise + */ + getOperationStatus(operationId: string, options?: msRest.RequestOptionsBase): Promise; + /** + * @param operationId Id referencing a particular take/apply snapshot operation. + * @param callback The callback + */ + getOperationStatus(operationId: string, callback: msRest.ServiceCallback): void; + /** + * @param operationId Id referencing a particular take/apply snapshot operation. + * @param options The optional parameters + * @param callback The callback + */ + getOperationStatus(operationId: string, options: msRest.RequestOptionsBase, callback: msRest.ServiceCallback): void; + getOperationStatus(operationId: string, options?: msRest.RequestOptionsBase | msRest.ServiceCallback, callback?: msRest.ServiceCallback): Promise { + return this.client.sendOperationRequest( + { + operationId, + options + }, + getOperationStatusOperationSpec, + callback) as Promise; + } +} + +// Operation Specifications +const serializer = new msRest.Serializer(Mappers); +const takeOperationSpec: msRest.OperationSpec = { + httpMethod: "POST", + path: "snapshots", + urlParameters: [ + Parameters.endpoint + ], + requestBody: { + parameterPath: { + type: "type", + objectId: "objectId", + applyScope: "applyScope", + userData: [ + "options", + "userData" + ] + }, + mapper: { + ...Mappers.TakeSnapshotRequest, + required: true + } + }, + responses: { + 202: { + headersMapper: Mappers.SnapshotTakeHeaders + }, + default: { + bodyMapper: Mappers.APIError + } + }, + serializer +}; + +const listOperationSpec: msRest.OperationSpec = { + httpMethod: "GET", + path: "snapshots", + urlParameters: [ + Parameters.endpoint + ], + queryParameters: [ + Parameters.type, + Parameters.applyScope + ], + responses: { + 200: { + bodyMapper: { + serializedName: "parsedResponse", + type: { + name: "Sequence", + element: { + type: { + name: "Composite", + className: "Snapshot" + } + } + } + } + }, + default: { + bodyMapper: Mappers.APIError + } + }, + serializer +}; + +const getOperationSpec: msRest.OperationSpec = { + httpMethod: "GET", + path: "snapshots/{snapshotId}", + urlParameters: [ + Parameters.endpoint, + Parameters.snapshotId + ], + responses: { + 200: { + bodyMapper: Mappers.Snapshot + }, + default: { + bodyMapper: Mappers.APIError + } + }, + serializer +}; + +const updateOperationSpec: msRest.OperationSpec = { + httpMethod: "PATCH", + path: "snapshots/{snapshotId}", + urlParameters: [ + Parameters.endpoint, + Parameters.snapshotId + ], + requestBody: { + parameterPath: { + applyScope: [ + "options", + "applyScope" + ], + userData: [ + "options", + "userData" + ] + }, + mapper: { + ...Mappers.UpdateSnapshotRequest, + required: true + } + }, + responses: { + 200: {}, + default: { + bodyMapper: Mappers.APIError + } + }, + serializer +}; + +const deleteMethodOperationSpec: msRest.OperationSpec = { + httpMethod: "DELETE", + path: "snapshots/{snapshotId}", + urlParameters: [ + Parameters.endpoint, + Parameters.snapshotId + ], + responses: { + 200: {}, + default: { + bodyMapper: Mappers.APIError + } + }, + serializer +}; + +const applyOperationSpec: msRest.OperationSpec = { + httpMethod: "POST", + path: "snapshots/{snapshotId}/apply", + urlParameters: [ + Parameters.endpoint, + Parameters.snapshotId + ], + requestBody: { + parameterPath: { + objectId: "objectId", + mode: [ + "options", + "mode" + ] + }, + mapper: { + ...Mappers.ApplySnapshotRequest, + required: true + } + }, + responses: { + 202: { + headersMapper: Mappers.SnapshotApplyHeaders + }, + default: { + bodyMapper: Mappers.APIError + } + }, + serializer +}; + +const getOperationStatusOperationSpec: msRest.OperationSpec = { + httpMethod: "GET", + path: "operations/{operationId}", + urlParameters: [ + Parameters.endpoint, + Parameters.operationId + ], + responses: { + 200: { + bodyMapper: Mappers.OperationStatus + }, + default: { + bodyMapper: Mappers.APIError + } + }, + serializer +}; diff --git a/packages/@azure/cognitiveservices-face/package.json b/packages/@azure/cognitiveservices-face/package.json index 550954d5edfa..2c4e5219339c 100644 --- a/packages/@azure/cognitiveservices-face/package.json +++ b/packages/@azure/cognitiveservices-face/package.json @@ -4,7 +4,7 @@ "description": "FaceClient Library with typescript type definitions for node.js and browser.", "version": "2.2.0", "dependencies": { - "@azure/ms-rest-js": "^1.1.0", + "@azure/ms-rest-js": "^1.2.0", "tslib": "^1.9.3" }, "keywords": [ @@ -22,6 +22,7 @@ "typescript": "^3.1.1", "rollup": "^0.66.2", "rollup-plugin-node-resolve": "^3.4.0", + "rollup-plugin-sourcemaps": "^0.4.2", "uglify-js": "^3.4.9" }, "homepage": "https://github.com/azure/azure-sdk-for-js/tree/master/packages/@azure/cognitiveservices-face", @@ -50,6 +51,5 @@ "minify": "uglifyjs -c -m --comments --source-map \"content='./dist/cognitiveservices-face.js.map'\" -o ./dist/cognitiveservices-face.min.js ./dist/cognitiveservices-face.js", "prepack": "npm install && npm run build" }, - "sideEffects": false, - "authPublish": true + "sideEffects": false } diff --git a/packages/@azure/cognitiveservices-face/rollup.config.js b/packages/@azure/cognitiveservices-face/rollup.config.js index f24139915698..0a02eb764a23 100644 --- a/packages/@azure/cognitiveservices-face/rollup.config.js +++ b/packages/@azure/cognitiveservices-face/rollup.config.js @@ -1,10 +1,16 @@ +import rollup from "rollup"; import nodeResolve from "rollup-plugin-node-resolve"; +import sourcemaps from "rollup-plugin-sourcemaps"; + /** - * @type {import('rollup').RollupFileOptions} + * @type {rollup.RollupFileOptions} */ const config = { - input: './esm/faceClient.js', - external: ["@azure/ms-rest-js", "@azure/ms-rest-azure-js"], + input: "./esm/faceClient.js", + external: [ + "@azure/ms-rest-js", + "@azure/ms-rest-azure-js" + ], output: { file: "./dist/cognitiveservices-face.js", format: "umd", @@ -16,16 +22,16 @@ const config = { }, banner: `/* * Copyright (c) Microsoft Corporation. All rights reserved. - * Licensed under the MIT License. See License.txt in the project root for - * license information. + * 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. + * Changes may cause incorrect behavior and will be lost if the code is regenerated. */` }, plugins: [ - nodeResolve({ module: true }) + nodeResolve({ module: true }), + sourcemaps() ] }; + export default config;