灾难恢复

项目
04/09/2024

此内容适用于：v3.1 (GA) | 先前版本：v3.0v2.1

此内容适用于：v3.0 (GA) | 最新版本：v3.1 | 以前的版本：v2.1

此内容适用于：v2.1

在 Azure 门户中创建文档智能资源时，需指定一个区域。然后，资源及其所有操作都将与该特定的 Azure 服务器区域保持关联。有时我们会遇到影响整个区域的网络问题，这种情况比较罕见，但也不是没有可能。如果解决方案需要始终保持可用，则应将其设计为可故障转移到另一区域，或者将工作负荷分散到两个或更多个区域。这两种方法都要求不同的区域中至少有两个文档智能资源，并且能够跨区域同步自定义模型。

复制 API 能够实现这种场景，因为它能让你在不同的文档智能帐户（可位于任何受支持的地理区域中）之间复制自定义模型。本指南介绍如何将复制 REST API 与 cURL 配合使用。还可以使用 HTTP 请求服务来发出请求。

业务场景

如果你的应用或业务依赖于使用某个文档智能自定义模型，我们建议将该模型复制到另一区域中的另一文档智能帐户。如果发生区域服务中断，你仍可以在该模型所复制到的区域中访问该模型。

先决条件

不同 Azure 区域中的两个文档智能 Azure 资源。如果你没有这些资源，请转到 Azure 门户并创建一个新的“文档智能”资源。
文档智能资源的密钥、终结点 URL 和订阅 ID。可以在 Azure 门户中资源的“概览”选项卡上找到这些值。

复制 API 概述

复制自定义模型的过程包括以下步骤：

首先，向目标资源（即接收所复制的模型的资源）发出复制授权请求。收到新建目标模型（将接收复制的模型）的 URL。
接下来，将复制请求发送到源资源，即包含要复制的模型以及从先前调用返回的有效负载（复制授权）的资源。收到一个 URL，查询该 URL 可跟踪操作的进度。
使用源资源凭据来查询进度 URL，直到操作成功。还可以在目标资源中查询新模型 ID 以获取新模型的状态。

生成复制授权请求

以下 HTTP 请求从目标资源获取复制授权。需要输入目标资源的终结点和密钥作为头。

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}

请求正文

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

收到带有响应正文的 200 响应代码，其中包含启动复制所需的 JSON 有效负载。

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

启动复制操作

以下 HTTP 请求对源资源启动复制操作。需要输入源资源的终结点和密钥作为 URL 和标头。请注意，请求 URL 包含所要复制的源模型的模型 ID。

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

请求的正文是上一步的响应。

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

你将收到 202\Accepted 响应，其中包含“Operation-Location”标头。此值是用于跟踪操作进度的 URL。请将其复制到某个临时位置，以便在下一步骤中使用。

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

注意

复制 API 以透明方式支持 AEK/CMK 功能。这不需要进行任何特殊处理，但请注意，如果在未加密的资源与已加密的资源之间进行复制，则需要包含请求头 x-ms-forms-copy-degrade: true。如果不包含此头，复制操作将会失败并返回 DataProtectionTransformServiceError。

跟踪复制进度

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

跟踪目标模型 ID

还可以使用获取模型 API，通过查询目标模型来跟踪操作的状态。使用从生成复制授权请求响应中复制的目标模型 ID 调用该 API。

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

在响应正文中，会看到有关模型的信息。检查 "status" 字段即可了解模型的状态。

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 示例代码

以下代码片段使用 cURL 发出 API 调用。你仍需填写特定于自己资源的模型 ID 和订阅信息。

生成复制授权

请求

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}'
}"

成功的响应

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

开始执行复制操作

请求

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}'
}"

成功的响应

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

跟踪复制操作的进度

可以使用获取操作 API 列出与文档智能资源关联的所有文档模型操作（成功、正在进行或失败）。操作信息只会保存 24 小时。下面是可返回的操作 (operationId) 的列表：

documentModelBuild
documentModelCompose
documentModelCopyTo

跟踪目标模型 ID

如果操作成功，则可以使用 getModel（获取单个模型）或 GetModels（获取模型列表）API 访问文档模型。

复制模型概述

复制自定义模型的过程包括以下步骤：

首先，向目标资源（即接收所复制的模型的资源）发出复制授权请求。收到新建目标模型（将接收复制的模型）的 URL。
接下来，将复制请求发送到源资源，即包含要复制的模型以及从先前调用返回的有效负载（复制授权）的资源。收到一个 URL，查询该 URL 可跟踪操作的进度。
使用源资源凭据来查询进度 URL，直到操作成功。

生成授权请求

以下 HTTP 请求从目标资源生成复制授权。需要输入目标资源的终结点和密钥作为头。

POST https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/copyAuthorization
Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}

收到一个 201\Created 响应，其正文中包含 modelId 值。此字符串是新建（空白）模型的 ID。需要提供 accessToken 才能让 API 将数据复制到此资源，expirationDateTimeTicks 值是令牌的过期时间。将这所有三个值保存到安全位置。

HTTP/1.1 201 Created
Location: https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/33f4d42c-cd2f-4e74-b990-a1aeafab5a5d
{"modelId":"<your model ID>","accessToken":"<your access token>","expirationDateTimeTicks":637233481531659440}

启动复制操作

以下 HTTP 请求对源资源启动复制操作。需要输入源资源的终结点和密钥作为头。请注意，请求 URL 包含所要复制的源模型的模型 ID。

POST https://{SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/<your model ID>/copy HTTP/1.1
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}

请求正文需采用以下格式。需要输入目标资源的资源 ID 和区域名称。可以在 Azure 门户中资源的“属性”选项卡上找到资源 ID，并且可以在“密钥和终结点”选项卡上找到区域名称。还需要提供在上一步骤中复制的模型 ID、访问令牌和过期时间值。

{
   "targetResourceId": "{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_ID}",  
   "targetResourceRegion": "{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_REGION_NAME}",
   "copyAuthorization": {"modelId":"<your model ID>","accessToken":"<your access token>","expirationDateTimeTicks":637233481531659440}
}

你将收到 202\Accepted 响应，其中包含“Operation-Location”标头。此值是用于跟踪操作进度的 URL。请将其复制到某个临时位置，以便在下一步骤中使用。

HTTP/1.1 202 Accepted
Operation-Location: https://{SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/eccc3f13-8289-4020-ba16-9f1d1374e96f/copyresults/02989ba8-1296-499f-aaf4-55cfff41b8f1

注意

复制 API 以透明方式支持 AEK/CMK 功能。此操作不需要进行任何特殊处理，但请注意，如果在未加密的资源与已加密的资源之间进行复制，则需要包含请求头 x-ms-forms-copy-degrade: true。如果不包含此头，复制操作将会失败并返回 DataProtectionTransformServiceError。

跟踪操作进度

通过针对源资源终结点查询“获取复制模型结果”API 来跟踪进度。

GET https://{SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/eccc3f13-8289-4020-ba16-9f1d1374e96f/copyresults/02989ba8-1296-499f-aaf4-55cfff41b8f1 HTTP/1.1
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}

响应将根据操作状态而异。查找 JSON 正文中的 "status" 字段。如果你要在脚本中自动执行此 API 调用，我们建议每秒查询操作一次。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"succeeded","createdDateTime":"2020-04-23T18:18:01.0275043Z","lastUpdatedDateTime":"2020-04-23T18:18:01.0275048Z","copyResult":{}}

使用 modelID 跟踪操作状态

还可以使用“获取自定义模型”API，通过查询目标模型来跟踪操作的状态。使用在第一步骤中复制的目标模型 ID 调用此 API。

GET https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/33f4d42c-cd2f-4e74-b990-a1aeafab5a5d HTTP/1.1
Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}

在响应正文中，会收到看到有关模型的信息。检查 "status" 字段即可了解模型的状态。

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 代码示例

以下代码片段使用 cURL 发出 API 调用。你仍需填写特定于自己资源的模型 ID 和订阅信息。

生成复制授权

curl -i -X POST "https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/copyAuthorization" -H "Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}"

启动复制操作

curl -i -X POST "https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/v2.1/custom/models/copyAuthorization" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}" --data-ascii "{ \"targetResourceId\": \"{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_ID}\",   \"targetResourceRegion\": \"{TARGET_AZURE_FORM_RECOGNIZER_RESOURCE_REGION_NAME}\", \"copyAuthorization\": "{\"modelId\":\"33f4d42c-cd2f-4e74-b990-a1aeafab5a5d\",\"accessToken\":\"1855fe23-5ffc-427b-aab2-e5196641502f\",\"expirationDateTimeTicks\":637233481531659440}"}"

跟踪复制进度

curl -i GET "https://<SOURCE_FORM_RECOGNIZER_RESOURCE_ENDPOINT>/formrecognizer/v2.1/custom/models/{SOURCE_MODELID}/copyResults/{RESULT_ID}" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}"

常见错误代码消息

错误	解决方法
400/错误的请求，`"code:" "1002"`	表示发生验证错误，或复制请求的格式不正确。常见问题包括：a) `copyAuthorization` 有效负载无效或已被修改。 b) 令牌的 `expirationDateTimeTicks` 值已过期（`copyAuthorization` 有效负载的有效期为 24 小时）。 c) `targetResourceRegion` 无效或不受支持。 d) `targetResourceId` 字符串无效或格式不正确。
由于授权声明缺失或无效，授权失败。	当 `copyAuthorization` API 中的 `copyAuthorization` 有效负载或内容遭到修改时，将会发生此错误。确保有效负载与先前 `copyAuthorization` 调用返回的内容完全相同。
无法检索授权元数据。	表示 `copyAuthorization` 有效负载正重复用于某个复制请求。成功的复制请求不会允许存在任何使用相同 `copyAuthorization` 有效负载的其他请求。如果引发了其他错误，然后又使用同一个授权有效负载重试复制，则会引发此错误。解决方法是生成新的 `copyAuthorization` 有效负载，然后重新发出复制请求。
不允许数据传输请求，因为它会降级为较不安全的数据保护方案。	在支持 `AEK` 的资源与不支持 `AEK` 的资源之间进行复制时会发生此错误。若要允许将已加密的模型以未加密的形式复制到目标，请在复制请求中指定 `x-ms-forms-copy-degrade: true` 头。
“无法提取 ID 为 ... 的认知资源的信息”。	表示 `targetResourceId` 所指示的 Azure 资源不是有效的认知资源，或者不存在。若要解决此问题，请验证并重新发出复制请求。请确保该资源有效且位于指定的区域，例如 `chinanorth2`

后续步骤

在本指南中，你已学习如何使用复制 API 将自定义模型备份到次要文档智能资源。接下来请浏览 API 参考文档，以了解表文档智能的其他作用。

REST API 参考文档

在本指南中，你已学习如何使用复制 API 将自定义模型备份到次要文档智能资源。接下来请浏览 API 参考文档，以了解表文档智能的其他作用。

REST API 参考文档

灾难恢复

业务场景

先决条件

复制 API 概述

生成复制授权请求

启动复制操作

跟踪复制进度

跟踪目标模型 ID

cURL 示例代码

生成复制授权

开始执行复制操作

跟踪复制操作的进度

跟踪目标模型 ID

复制模型概述

生成授权请求

启动复制操作

跟踪操作进度

使用 modelID 跟踪操作状态

cURL 代码示例

生成复制授权

启动复制操作

跟踪复制进度

常见错误代码消息

后续步骤

其他资源