Cognitive Services Form Recognizer v2.0-preview: Copy APIs #8349
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -312,6 +312,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": { | ||
lmazuel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "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": { | ||
|
There was a problem hiding this comment. is the modelId generated by the service, or is it missing from this path?
Contributor
There was a problem hiding this comment. Yes modelId will be generated by Service and returned in response (and Location header)
Contributor
There was a problem hiding this comment. Does this mean that authorization allows users to copy all models in the resource? Would there be a use-case where users might want to allow copying some models but not others?
Member
There was a problem hiding this comment. @sayachao, please correct me if/when I'm wrong/not explaining things correctly, but this API "reserves" a slot that someone can copy another model into. You use the information in the response to initiate a copy. The API could be extended to take an optional source model id (if we wanted to restrict which model could be copied into this "slot"). The current version of the API allows for any user whom I give the generated token/target location (there should only be one) to copy one model they have "own"/have access to into the target location. And you cannot overwrite the target - once you have copied a model, the token is done.
Contributor
There was a problem hiding this comment. @schaabs, does this look like a reasonable pattern from an auth perspective? Will we need to add new auth patterns to Azure.Core to support it, or is it fine to handle it as a pattern specific to this service? |
||
| "post": { | ||
| "summary": "Generate Copy Authorization", | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "description": "Generate authorization to copy a model into the target Form Recognizer resource.", | ||
| "operationId": "GenerateModelCopyAuthorization", | ||
| "consumes": [], | ||
| "produces": [ | ||
| "application/json" | ||
| ], | ||
| "parameters": [], | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "responses": { | ||
| "201": { | ||
| "description": "Copy request is authorized successfully.", | ||
| "headers": { | ||
| "Location": { | ||
| "type": "string", | ||
johanste marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "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" | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| } | ||
| }, | ||
| "x-ms-examples": { | ||
| "Copy custom model": { | ||
| "$ref": "./examples/CopyModelAuthorization.json" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "/prebuilt/receipt/analyze": { | ||
| "post": { | ||
| "summary": "Analyze Receipt", | ||
|
|
@@ -506,6 +649,111 @@ | |
| }, | ||
| "x-nullable": false | ||
| }, | ||
| "CopyAuthorizationResult": { | ||
| "description": "Request parameter that contains authorization claims for copy operation.", | ||
| "required": [ | ||
| "modelId", | ||
| "accessToken", | ||
| "expirationDateTimeTicks" | ||
| ], | ||
| "type": "object", | ||
| "properties": { | ||
| "modelId": { | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "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.", | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "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.", | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "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.", | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "type": "string", | ||
| "format": "uuid" | ||
| }, | ||
| "errors": { | ||
| "description": "Errors returned during the copy operation.", | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/definitions/ErrorInformation" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "AnalyzeOperationResult": { | ||
| "description": "Status and result of the queued analyze operation.", | ||
| "type": "object", | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| { | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "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}", | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "targetResourceRegion": "westus2", | ||
| "copyAuthorization": { | ||
| "modelId": "{modelId}", | ||
| "accessToken": "{accessToken}", | ||
| "expirationDateTimeTicks": 637190189980000000 | ||
| } | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| }, | ||
| "responses": { | ||
| "202": { | ||
| "headers": { | ||
| "Operation-Location": "{endpoint}/formrecognizer/v2.0-preview/custom/models/{modelId}/copyResults/{resultId}" | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| } | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
| } | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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}", | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "errors": [] | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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": { | ||
krishnand marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "body": { | ||
| "status": "failed", | ||
| "createdDateTime": "2020-01-01T00:00:00Z", | ||
| "lastUpdatedDateTime": "2020-01-01T00:01:00Z", | ||
| "copyResult": { | ||
| "modelId": "{modelId}", | ||
| "errors": [ | ||
| { | ||
| "code": "ResourceResolverError", | ||
| "message": "{ErrorMessage}" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.