From 0c27a3ec34938f1bbc94db6a2d1532f616422cbf Mon Sep 17 00:00:00 2001 From: Yang Chen Date: Wed, 26 May 2021 11:07:50 -0700 Subject: [PATCH 1/3] Fixes for FaceAPI Added header definitions on PersonDirectory related 202 responses and fixed async operation status names. Fixed required name parameter being optional issue on FaceList/PersonGroup creation. --- .../Face/preview/v1.0-preview/Face.json | 151 +++++++++++------- ...ddPersonDirectoryPersonFaceFromStream.json | 3 + .../AddPersonDirectoryPersonFaceFromUrl.json | 3 + .../examples/CreateNewDynamicPersonGroup.json | 6 +- .../CreateNewPersonDirectoryPerson.json | 3 + .../examples/DeleteDynamicPersonGroup.json | 6 +- .../examples/DeletePersonDirectoryPerson.json | 6 +- .../DeletePersonDirectoryPersonFace.json | 6 +- .../examples/UpdateDynamicPersonGroup.json | 6 +- .../data-plane/Face/stable/v1.0/Face.json | 20 ++- 10 files changed, 148 insertions(+), 62 deletions(-) diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json index e7cef17c8c3f..a4e54aba915a 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json @@ -2492,7 +2492,7 @@ "200": { "description": "A successful call returns the operation's status.", "schema": { - "$ref": "#/definitions/AsyncStatus" + "$ref": "#/definitions/OperationStatus" } }, "default": { @@ -2582,6 +2582,12 @@ "responses": { "202": { "description": "Success", + "headers": { + "Operation-Location": { + "description": "Operation location with an operation id used to track the progress of person creation.", + "type": "string" + } + }, "schema": { "$ref": "#/definitions/PersonCreationResponse" } @@ -2665,7 +2671,13 @@ ], "responses": { "202": { - "description": "Success" + "description": "Success", + "headers": { + "Operation-Location": { + "description": "Operation location with an operation id used to track the progress of person creation.", + "type": "string" + } + } }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", @@ -2766,6 +2778,12 @@ "responses": { "202": { "description": "Success", + "headers": { + "Operation-Location": { + "description": "Operation location with an operation id used to track the progress of person creation.", + "type": "string" + } + }, "schema": { "$ref": "#/definitions/EnrollmentPrintResponse" } @@ -2864,7 +2882,13 @@ ], "responses": { "202": { - "description": "Success" + "description": "Success", + "headers": { + "Operation-Location": { + "description": "Operation location with an operation id used to track the progress of person creation.", + "type": "string" + } + } }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", @@ -3029,7 +3053,13 @@ "description": "Success" }, "202": { - "description": "Success" + "description": "Success", + "headers": { + "Operation-Location": { + "description": "Operation location with an operation id used to track the progress of person creation.", + "type": "string" + } + } }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", @@ -3076,7 +3106,13 @@ ], "responses": { "202": { - "description": "Success" + "description": "Success", + "headers": { + "Operation-Location": { + "description": "Operation location with an operation id used to track the progress of person creation.", + "type": "string" + } + } }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", @@ -3149,7 +3185,13 @@ ], "responses": { "202": { - "description": "Success" + "description": "Success", + "headers": { + "Operation-Location": { + "description": "Operation location with an operation id used to track the progress of person creation.", + "type": "string" + } + } }, "default": { "description": "Response entity accompanying non-successful responses containing additional details about the error.", @@ -3670,6 +3712,12 @@ "responses": { "202": { "description": "Success", + "headers": { + "Operation-Location": { + "description": "Operation location with an operation id used to track the progress of person creation.", + "type": "string" + } + }, "schema": { "$ref": "#/definitions/EnrollmentPrintResponse" } @@ -4813,6 +4861,24 @@ "minimum": 0, "maximum": 1 }, + "NonNullableNameAndNullableUserDataContract": { + "type": "object", + "description": "A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.", + "required": ["name"], + "properties": { + "name": { + "type": "string", + "description": "User defined name, maximum length is 128.", + "maxLength": 128, + "minLength": 1 + }, + "userData": { + "type": "string", + "description": "User specified data. Length should not exceed 16KB.", + "maxLength": 16384 + } + } + }, "NameAndUserDataContract": { "type": "object", "description": "A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.", @@ -4839,7 +4905,7 @@ }, "allOf": [ { - "$ref": "#/definitions/NameAndUserDataContract" + "$ref": "#/definitions/NonNullableNameAndNullableUserDataContract" } ] }, @@ -5014,48 +5080,6 @@ } } }, - "OperationStatus": { - "type": "object", - "required": [ - "status", - "createdTime" - ], - "description": "Operation status object. Operation refers to the asynchronous backend task including taking a snapshot and applying a snapshot.", - "properties": { - "status": { - "type": "string", - "description": "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.", - "x-ms-enum": { - "name": "OperationStatusType", - "modelAsString": false - }, - "enum": [ - "notstarted", - "running", - "succeeded", - "failed" - ] - }, - "createdTime": { - "type": "string", - "format": "date-time", - "description": "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." - }, - "lastActionTime": { - "type": "string", - "format": "date-time", - "description": "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." - }, - "resourceLocation": { - "type": "string", - "description": "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." - }, - "message": { - "type": "string", - "description": "Show failure message when operation fails (omitted when operation succeeds)." - } - } - }, "PersistedFaceResponse": { "type": "object", "properties": { @@ -5075,31 +5099,46 @@ "succeeded", "failed" ], - "type": "string" + "type": "string", + "description": "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.", + "x-ms-enum": { + "name": "OperationStatusType", + "modelAsString": false + } }, - "AsyncStatus": { + "OperationStatus": { "type": "object", + "required": [ + "status", + "createdTime" + ], + "description": "Operation status object. Operation refers to an asynchronous backend task.", "properties": { "status": { "$ref": "#/definitions/AsyncOperationStatus" }, "createdTime": { "format": "date-time", - "type": "string" + "type": "string", + "description": "A combined UTC date and time string that describes the time when the operation is requested. E.g. 2018-12-25T11:41:02.2331413Z." }, "lastActionTime": { "format": "date-time", - "type": "string" + "type": "string", + "description": "A combined UTC date and time string that describes the last time the operation is actively running. The lastActionTime will keep increasing until the operation finishes. E.g. 2018-12-25T11:51:27.8705696Z." }, "finishedTime": { "format": "date-time", - "type": "string" + "type": "string", + "description": "A combined UTC date and time string that describes the time when the operation finished. E.g. 2018-12-25T11:41:02.2331413Z." }, "resourceLocation": { - "type": "string" + "type": "string", + "description": "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." }, "message": { - "type": "string" + "type": "string", + "description": "Show failure message when operation fails (omitted when operation succeeds)." } } }, diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/AddPersonDirectoryPersonFaceFromStream.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/AddPersonDirectoryPersonFaceFromStream.json index a0472d1b8c6c..1ad4270ba1b0 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/AddPersonDirectoryPersonFaceFromStream.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/AddPersonDirectoryPersonFaceFromStream.json @@ -12,6 +12,9 @@ }, "responses": { "202": { + "header": { + "Operation-Location": "/operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a" + }, "body": { "persistedFaceId": "6e04c175-219e-42a2-9d26-0e7b790e1ef4", "recognitionModel": null, diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/AddPersonDirectoryPersonFaceFromUrl.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/AddPersonDirectoryPersonFaceFromUrl.json index 67cfe0b4669b..6e8510fd9ac5 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/AddPersonDirectoryPersonFaceFromUrl.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/AddPersonDirectoryPersonFaceFromUrl.json @@ -14,6 +14,9 @@ }, "responses": { "202": { + "header": { + "Operation-Location": "/operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a" + }, "body": { "persistedFaceId": "6e04c175-219e-42a2-9d26-0e7b790e1ef4", "recognitionModel": null, diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/CreateNewDynamicPersonGroup.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/CreateNewDynamicPersonGroup.json index 6b55410a2911..aaa952d485de 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/CreateNewDynamicPersonGroup.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/CreateNewDynamicPersonGroup.json @@ -11,6 +11,10 @@ }, "responses": { "200": {}, - "202": {} + "202": { + "header": { + "Operation-Location": "/operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a" + } + } } } diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/CreateNewPersonDirectoryPerson.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/CreateNewPersonDirectoryPerson.json index 712996b5f693..a20321319d26 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/CreateNewPersonDirectoryPerson.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/CreateNewPersonDirectoryPerson.json @@ -10,6 +10,9 @@ }, "responses": { "202": { + "header": { + "Operation-Location": "/operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a" + }, "body": { "personId": "4caa25ee-3bc6-4e88-adf8-12455ce7aab0" } diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeleteDynamicPersonGroup.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeleteDynamicPersonGroup.json index bd318036ed6d..fcbdb738c691 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeleteDynamicPersonGroup.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeleteDynamicPersonGroup.json @@ -6,6 +6,10 @@ "dynamicPersonGroupId": "abc" }, "responses": { - "202": {} + "202": { + "header": { + "Operation-Location": "/operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a" + } + } } } diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeletePersonDirectoryPerson.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeletePersonDirectoryPerson.json index a2f224a8c305..bbb4bde7653b 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeletePersonDirectoryPerson.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeletePersonDirectoryPerson.json @@ -6,6 +6,10 @@ "personId": "25985303-c537-4467-b41d-bdb45cd95ca1" }, "responses": { - "202": {} + "202": { + "header": { + "Operation-Location": "/operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a" + } + } } } diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeletePersonDirectoryPersonFace.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeletePersonDirectoryPersonFace.json index 626c7b5e3503..687c94122726 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeletePersonDirectoryPersonFace.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/DeletePersonDirectoryPersonFace.json @@ -8,6 +8,10 @@ "persistedFaceId": "62004fa7-1ac0-478e-9d5a-b38f9e7fbc68" }, "responses": { - "202": {} + "202": { + "header": { + "Operation-Location": "/operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a" + } + } } } diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/UpdateDynamicPersonGroup.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/UpdateDynamicPersonGroup.json index c76dd3808c39..6fec5b4772bc 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/UpdateDynamicPersonGroup.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/examples/UpdateDynamicPersonGroup.json @@ -17,6 +17,10 @@ } }, "responses": { - "202": {} + "202": { + "header": { + "Operation-Location": "/operations/a63a3bdd-a1db-4d05-87b8-dbad6850062a" + } + } } } diff --git a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json index 33604243db34..070ae728a417 100644 --- a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json @@ -3922,6 +3922,24 @@ "minimum": 0, "maximum": 1 }, + "NonNullableNameAndNullableUserDataContract": { + "type": "object", + "description": "A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.", + "required": ["name"], + "properties": { + "name": { + "type": "string", + "description": "User defined name, maximum length is 128.", + "maxLength": 128, + "minLength": 1 + }, + "userData": { + "type": "string", + "description": "User specified data. Length should not exceed 16KB.", + "maxLength": 16384 + } + } + }, "NameAndUserDataContract": { "type": "object", "description": "A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.", @@ -3948,7 +3966,7 @@ }, "allOf": [ { - "$ref": "#/definitions/NameAndUserDataContract" + "$ref": "#/definitions/NonNullableNameAndNullableUserDataContract" } ] }, From d959ec564aed3ac9de3ba11bdf986decac6649a0 Mon Sep 17 00:00:00 2001 From: Yang Chen Date: Wed, 26 May 2021 17:18:39 -0700 Subject: [PATCH 2/3] Prettier fixes --- .../data-plane/Face/preview/v1.0-preview/Face.json | 4 +++- .../cognitiveservices/data-plane/Face/stable/v1.0/Face.json | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json index a4e54aba915a..05534592f410 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json @@ -4864,7 +4864,9 @@ "NonNullableNameAndNullableUserDataContract": { "type": "object", "description": "A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.", - "required": ["name"], + "required": [ + "name" + ], "properties": { "name": { "type": "string", diff --git a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json index 070ae728a417..a0d5e7d06a50 100644 --- a/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json +++ b/specification/cognitiveservices/data-plane/Face/stable/v1.0/Face.json @@ -3925,7 +3925,9 @@ "NonNullableNameAndNullableUserDataContract": { "type": "object", "description": "A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.", - "required": ["name"], + "required": [ + "name" + ], "properties": { "name": { "type": "string", From cecfc48088aff871bbc49788a08f76b2001399e6 Mon Sep 17 00:00:00 2001 From: Yang Chen Date: Tue, 1 Jun 2021 18:23:50 -0700 Subject: [PATCH 3/3] Rename contract --- .../data-plane/Face/preview/v1.0-preview/Face.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json index 05534592f410..d38d30cd08d9 100644 --- a/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json +++ b/specification/cognitiveservices/data-plane/Face/preview/v1.0-preview/Face.json @@ -4861,7 +4861,7 @@ "minimum": 0, "maximum": 1 }, - "NonNullableNameAndNullableUserDataContract": { + "NameAndUserDataContractForCreation": { "type": "object", "description": "A combination of user defined name and user specified data for the person, largePersonGroup/personGroup, and largeFaceList/faceList.", "required": [ @@ -4907,7 +4907,7 @@ }, "allOf": [ { - "$ref": "#/definitions/NonNullableNameAndNullableUserDataContract" + "$ref": "#/definitions/NameAndUserDataContractForCreation" } ] },