Skip to content

Commit

Permalink
Cognitive Services Form Recognizer v2.0-preview: Copy APIs (#8349)
Browse files Browse the repository at this point in the history
* Update FormRecognizer v2.0-preview spec with new operations 'CopyCustomModel' and 'GetCustomModelCopyResult'. Added new sample files for the operation - 'CopyModel.json' and 'CopyOperationResult.json'.

* Add claimResourceRegion. Remove move option from Copy data contract based on review. Fixed required property issue in AuthorizationClaim contract

* Address PR comments

* Remove authorizationClaim from CopyRequest contract. Updated reference for targetResourceRegion. Added pattern for targetResourceId

* Fixed typo in CopyRequest required attribute

* Add AuthorizationClaim contract and include it with CopyRequest

* AuthorizationClaim - typo in required attrib

* Rename AuthorizationClaim to Authorization

* Rename modelResourceId to modelId in the 'Authorization' contract. Fixed copy sample

* Adding source query string parameter to the POST copy request

* Set 'application/json' consumes option for POST copy

* Introduce models/copyAuthorization route. Added sample for the new route. Updated existing samples for correctness.

* Change expirationDateTime to expirationDateTimeTicks in the CopyAuthorizationResult contract. Follows the 'expires_on' convention in the AAD token.

* Remove enum reference for targetResourceRegion. Update to a loose pattern and length specification

* Address ModelValidation and Sample validation errors

* Fix copy samples JSON validation issues

* Run prettier on FormRecognizer.json swagger and example files

* Add sample for COpy operation result with errors. Fix description for copy operations

* Prettier fix for CopyOperationResultWithErrors.json

* Add LRO annotation to copy API
  • Loading branch information
krishnand authored Apr 27, 2020
1 parent b31774e commit de43e7f
Show file tree
Hide file tree
Showing 5 changed files with 344 additions and 0 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,149 @@
}
}
},
"/custom/models/{modelId}/copy": {
"post": {
"summary": "Copy Custom Model",
"description": "Copy custom model stored in this resource (the source) to user specified target Form Recognizer resource.",
"operationId": "CopyCustomModel",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "modelId",
"in": "path",
"description": "Model identifier.",
"required": true,
"type": "string",
"format": "uuid"
},
{
"name": "copyRequest",
"in": "body",
"description": "Copy request parameters.",
"required": true,
"schema": {
"$ref": "#/definitions/CopyRequest"
}
}
],
"responses": {
"202": {
"description": "Copy request is queued successfully.",
"headers": {
"Operation-Location": {
"type": "string",
"description": "URL containing the resultId used to track the progress and obtain the result of the copy operation."
}
}
},
"default": {
"description": "Response entity accompanying non-successful responses containing additional details about the error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"Copy custom model": {
"$ref": "./examples/CopyModel.json"
}
},
"x-ms-long-running-operation": true
}
},
"/custom/models/{modelId}/copyResults/{resultId}": {
"get": {
"summary": "Get Custom Model Copy Result",
"description": "Obtain current status and the result of a custom model copy operation.",
"operationId": "GetCustomModelCopyResult",
"consumes": [],
"produces": [
"application/json"
],
"parameters": [
{
"name": "modelId",
"in": "path",
"description": "Model identifier.",
"required": true,
"type": "string",
"format": "uuid"
},
{
"name": "resultId",
"in": "path",
"description": "Copy operation result identifier.",
"required": true,
"type": "string",
"format": "uuid"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/CopyOperationResult"
}
},
"default": {
"description": "Response entity accompanying non-successful responses containing additional details about the error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"Get copy custom model result": {
"$ref": "./examples/CopyOperationResult.json"
},
"Get copy custom model result with failures": {
"$ref": "./examples/CopyOperationResultWithErrors.json"
}
}
}
},
"/custom/models/copyAuthorization": {
"post": {
"summary": "Generate Copy Authorization",
"description": "Generate authorization to copy a model into the target Form Recognizer resource.",
"operationId": "GenerateModelCopyAuthorization",
"consumes": [],
"produces": [
"application/json"
],
"parameters": [],
"responses": {
"201": {
"description": "Copy request is authorized successfully.",
"headers": {
"Location": {
"type": "string",
"description": "Location and ID of the model being copied. The status of model copy is specified in the status property at the model location."
}
},
"schema": {
"$ref": "#/definitions/CopyAuthorizationResult"
}
},
"default": {
"description": "Response entity accompanying non-successful responses containing additional details about the error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"Copy custom model": {
"$ref": "./examples/CopyModelAuthorization.json"
}
}
}
},
"/prebuilt/receipt/analyze": {
"post": {
"summary": "Analyze Receipt",
Expand Down Expand Up @@ -559,6 +702,111 @@
},
"x-nullable": false
},
"CopyAuthorizationResult": {
"description": "Request parameter that contains authorization claims for copy operation.",
"required": [
"modelId",
"accessToken",
"expirationDateTimeTicks"
],
"type": "object",
"properties": {
"modelId": {
"description": "Model identifier.",
"type": "string"
},
"accessToken": {
"description": "Token claim used to authorize the request.",
"type": "string"
},
"expirationDateTimeTicks": {
"description": "The time when the access token expires. The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time.",
"type": "integer",
"format": "int64"
}
}
},
"CopyRequest": {
"description": "Request parameter to copy an existing custom model from the source resource to a target resource referenced by the resource ID.",
"required": [
"targetResourceId",
"targetResourceRegion",
"copyAuthorization"
],
"type": "object",
"properties": {
"targetResourceId": {
"description": "Azure Resource Id of the target Form Recognizer resource where the model is copied to.",
"maxLength": 1024,
"type": "string",
"pattern": "^/subscriptions/[^/]*/resourceGroups/[^/]*/providers/Microsoft.CognitiveServices/accounts/[^/]*$",
"x-ms-azure-resource": true
},
"targetResourceRegion": {
"description": "Location of the target Azure resource. A valid Azure region name supported by Cognitive Services.",
"type": "string",
"pattern": "^[a-z0-9]+$",
"minLength": 1,
"maxLength": 24
},
"copyAuthorization": {
"description": "Entity that encodes claims to authorize the copy request.",
"$ref": "#/definitions/CopyAuthorizationResult"
}
}
},
"CopyOperationResult": {
"description": "Status and result of the queued copy operation.",
"type": "object",
"required": [
"status",
"createdDateTime",
"lastUpdatedDateTime"
],
"properties": {
"status": {
"description": "Operation status.",
"$ref": "#/definitions/OperationStatus"
},
"createdDateTime": {
"format": "date-time",
"description": "Date and time (UTC) when the copy operation was submitted.",
"type": "string",
"x-nullable": false
},
"lastUpdatedDateTime": {
"format": "date-time",
"description": "Date and time (UTC) when the status was last updated.",
"type": "string",
"x-nullable": false
},
"copyResult": {
"description": "Results of the copy operation.",
"$ref": "#/definitions/CopyResult"
}
}
},
"CopyResult": {
"description": "Custom model copy result.",
"type": "object",
"required": [
"modelId"
],
"properties": {
"modelId": {
"description": "Identifier of the target model.",
"type": "string",
"format": "uuid"
},
"errors": {
"description": "Errors returned during the copy operation.",
"type": "array",
"items": {
"$ref": "#/definitions/ErrorInformation"
}
}
}
},
"AnalyzeOperationResult": {
"description": "Status and result of the queued analyze operation.",
"type": "object",
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"parameters": {
"endpoint": "{endpoint}",
"Content-Type": "application/json",
"Ocp-Apim-Subscription-Key": "{API key}",
"modelId": "{modelId}",
"body": {},
"copyRequest": {
"targetResourceId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{resourceName}",
"targetResourceRegion": "westus2",
"copyAuthorization": {
"modelId": "{modelId}",
"accessToken": "{accessToken}",
"expirationDateTimeTicks": 637190189980000000
}
}
},
"responses": {
"202": {
"headers": {
"Operation-Location": "{endpoint}/formrecognizer/v2.0-preview/custom/models/{modelId}/copyResults/{resultId}"
}
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{
"parameters": {
"endpoint": "{endpoint}",
"Content-Type": "application/json",
"Ocp-Apim-Subscription-Key": "{API key}",
"body": {}
},
"responses": {
"201": {
"headers": {
"Location": "{endpoint}/formrecognizer/v2.0-preview/custom/models/{modelId}"
},
"body": {
"modelId": "{modelId}",
"accessToken": "{accessToken}",
"expirationDateTimeTicks": 637190189980000000
}
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"parameters": {
"endpoint": "{endpoint}",
"Content-Type": "application/json",
"Ocp-Apim-Subscription-Key": "{API key}",
"modelId": "{modelId}",
"resultId": "{resultId}",
"body": {}
},
"responses": {
"200": {
"body": {
"status": "succeeded",
"createdDateTime": "2020-01-01T00:00:00Z",
"lastUpdatedDateTime": "2020-01-01T00:01:00Z",
"copyResult": {
"modelId": "{modelId}",
"errors": []
}
}
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"parameters": {
"endpoint": "{endpoint}",
"Content-Type": "application/json",
"Ocp-Apim-Subscription-Key": "{API key}",
"modelId": "{modelId}",
"resultId": "{resultId}",
"body": {}
},
"responses": {
"200": {
"body": {
"status": "failed",
"createdDateTime": "2020-01-01T00:00:00Z",
"lastUpdatedDateTime": "2020-01-01T00:01:00Z",
"copyResult": {
"modelId": "{modelId}",
"errors": [
{
"code": "ResourceResolverError",
"message": "{ErrorMessage}"
}
]
}
}
}
}
}

0 comments on commit de43e7f

Please sign in to comment.