Disaster recovery

This content applies to: v3.1 (GA) | Latest version: v4.0 (preview) | Previous versions: v3.0 v2.1

When you create a Document Intelligence resource in the Azure portal, you specify a region. From then on, your resource and all of its operations stay associated with that particular Azure server region. It's rare, but not impossible, to encounter a network issue that hits an entire region. If your solution needs to always be available, then you should design it to either fail-over into another region or split the workload between two or more regions. Both approaches require at least two Document Intelligence resources in different regions and the ability to sync custom models and classifiers across regions.

The Copy API enables this scenario by allowing you to copy custom models and classifiers from one Document Intelligence account or into others, which can exist in any supported geographical region. This guide shows you how to use the Copy REST API with cURL for custom models. You can also use an HTTP request service to issue the requests.

Note

Starting with the 2024-07-31-preview API, custom clasification models also support the Copy API. This guide specifically uses custom models to copy models. For classifier model copy, follow this guide.

Business scenarios

If your app or business depends on the use of a Document Intelligence custom model, we recommend you copy your model to another Document Intelligence account in another region. If a regional outage occurs, you can then access your model in the region where it was copied.

Prerequisites

1. Two Document Intelligence Azure resources in different Azure regions. If you don't have them, go to the Azure portal and create a new Document Intelligence resource.
2. The key, endpoint URL, and subscription ID for your Document Intelligence resource. You can find these values on the resource's Overview tab in the Azure portal.

Copy API overview

The process for copying a custom model consists of the following steps:

1. First you issue a copy authorization request to the target resource—that is, the resource that receives the copied model. You receive back the URL of the newly created target model that receives the copied model.
2. Next you send the copy request to the source resource—the resource that contains the model to be copied with the payload (copy authorization) returned from the previous call. You receive back a URL that you can query to track the progress of the operation.
3. You use your source resource credentials to query the progress URL until the operation is a success. You can also query the new model ID in the target resource to get the status of the new model.

Generate Copy authorization request

The following HTTP request gets copy authorization from your target resource. You need to enter the endpoint and key of your target resource as headers.

POST https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/documentModels:authorizeCopy?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}

Request body

{
  "modelId": "target-model-name",
  "description": "Copied from SCUS"
}

You receive a 200 response code with response body that contains the JSON payload required to initiate the copy.

{
  "targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
  "targetResourceRegion": "region",
  "targetModelId": "target-model-name",
  "targetModelLocation": "model path",
  "accessToken": "access token",
  "expirationDateTime": "timestamp"
}

Start Copy operation

The following HTTP request starts the copy operation on the source resource. You need to enter the endpoint and key of your source resource as the url and header. Notice that the request URL contains the model ID of the source model you want to copy.

POST {{source-endpoint}}formrecognizer/documentModels/{model-to-be-copied}:copyTo?api-version=2023-07-31
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}

The body of your request is the response from the previous step.

{
  "targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
  "targetResourceRegion": "region",
  "targetModelId": "target-model-name",
  "targetModelLocation": "model path",
  "accessToken": "access token",
  "expirationDateTime": "timestamp"
}

You receive a 202\Accepted response with an Operation-Location header. This value is the URL that you use to track the progress of the operation. Copy it to a temporary location for the next step.

HTTP/1.1 202 Accepted
Operation-Location: https://{source-resource}.cognitiveservices.azure.com/formrecognizer/operations/{operation-id}?api-version=2023-07-31

Note

The Copy API transparently supports the AEK/CMK feature. This doesn't require any special treatment, but note that if you're copying between an unencrypted resource to an encrypted resource, you need to include the request header x-ms-forms-copy-degrade: true. If this header is not included, the copy operation will fail and return a DataProtectionTransformServiceError.

Track Copy progress

GET https://{source-resource}.cognitiveservices.azure.com/formrecognizer/operations/{operation-id}?api-version=2023-07-31
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}

Track the target model ID

You can also use the GET model API to track the status of the operation by querying the target model. Call the API using the target model ID that you copied down from the Generate Copy authorization request response.

GET https://{YOUR-ENDPOINT}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31" -H "Ocp-Apim-Subscription-Key: <YOUR-KEY>

In the response body, you see information about the model. Check the "status" field for the status of the model.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"modelInfo":{"modelId":"33f4d42c-cd2f-4e74-b990-a1aeafab5a5d","status":"ready","createdDateTime":"2020-02-26T16:59:28Z","lastUpdatedDateTime":"2020-02-26T16:59:34Z"},"trainResult":{"trainingDocuments":[{"documentName":"0.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"1.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"2.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"3.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"4.pdf","pages":1,"errors":[],"status":"succeeded"}],"errors":[]}}

cURL sample code

The following code snippets use cURL to make API calls. You also need to fill in the model IDs and subscription information specific to your own resources.

Generate Copy authorization

Request

curl -i -X POST "{YOUR-ENDPOINT}formrecognizer/documentModels:authorizeCopy?api-version=2023-07-31"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
--data-ascii "{
  'modelId': '{modelId}',
  'description': '{description}'
}"

Successful response

{
  "targetResourceId": "string",
  "targetResourceRegion": "string",
  "targetModelId": "string",
  "targetModelLocation": "string",
  "accessToken": "string",
  "expirationDateTime": "string"
}

Begin Copy operation

Request

curl -i -X POST "{YOUR-ENDPOINT}/formrecognizer/documentModels/{modelId}:copyTo?api-version=2023-07-31"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
--data-ascii "{
  'targetResourceId': '{targetResourceId}',
  'targetResourceRegion': {targetResourceRegion}',
  'targetModelId': '{targetModelId}',
  'targetModelLocation': '{targetModelLocation}',
  'accessToken': '{accessToken}',
  'expirationDateTime': '{expirationDateTime}'
}"

Successful response

HTTP/1.1 202 Accepted
Operation-Location: https://{source-resource}.cognitiveservices.azure.com/formrecognizer/operations/{operation-id}?api-version=2023-07-31

Track copy operation progress

You can use the GET operation API to list all document model operations (succeeded, in-progress, or failed) associated with your Document Intelligence resource. Operation information only persists for 24 hours. Here's a list of the operations (operationId) that can be returned:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Track the target model ID

If the operation was successful, the document model can be accessed using the getModel (get a single model), or GetModels (get a list of models) APIs.

Common error code messages

Error	Resolution
400 / Bad Request with "code:" "1002"	Indicates validation error or badly formed copy request. Common issues include: a) Invalid or modified copyAuthorization payload. b) Expired value for expirationDateTimeTicks token (copyAuthorization payload is valid for 24 hours). c) Invalid or unsupported targetResourceRegion. d) Invalid or malformed targetResourceId string.
Authorization failure due to missing or invalid authorization claims.	Occurs when the copyAuthorization payload or content is modified from the copyAuthorization API. Ensure that the payload is the same exact content that was returned from the earlier copyAuthorization call.
Couldn't retrieve authorization metadata.	Indicates that the copyAuthorization payload is being reused with a copy request. A copy request that succeeds doesn't allow any further requests that use the same copyAuthorization payload. If you raise a separate error and you later retry the copy with the same authorization payload, this error gets raised. The resolution is to generate a new copyAuthorization payload and then reissue the copy request.
Data transfer request isn't allowed as it downgrades to a less secure data protection scheme.	Occurs when copying between an AEK enabled resource to a non AEK enabled resource. To allow copying encrypted model to the target as unencrypted, specify x-ms-forms-copy-degrade: true header with the copy request.
"Couldn't fetch information for Cognitive resource with ID...".	Indicates that the Azure resource indicated by the targetResourceId isn't a valid Cognitive resource or doesn't exist. To resolve this issue, verify and reissue the copy request. Ensure the resource is valid and exists in the specified region, such as, westus2

Next steps

In this guide, you learned how to use the Copy API to back up your custom models to a secondary Document Intelligence resource. Next, explore the API reference docs to see what else you can do with Document Intelligence.

• REST API reference documentation