你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

灾难恢复

此内容适用于： v3.1 (GA) | 最新版本： v4.0（预览版） | 早期版本： v3.0 v2.1

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

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

注意

从 2024-07-31-preview API 开始，自定义分类模型还支持复制 API。 本指南专门使用自定义模型来复制模型。 对于分类器模型复制，请遵循此指南。

业务场景

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

先决条件

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

复制 API 概述

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

1. 首先，向目标资源（即接收所复制的模型的资源）发出复制授权请求。 收到新建目标模型（将接收复制的模型）的 URL。
2. 接下来，将复制请求发送到源资源，即包含要复制的模型以及从先前调用返回的有效负载（复制授权）的资源。 收到一个 URL，查询该 URL 可跟踪操作的进度。
3. 使用源资源凭据来查询进度 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.com/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.com/formrecognizer/operations/{operation-id}?api-version=2023-07-31
Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}

跟踪目标模型 ID

还可以使用 GET model API，通过查询目标模型来跟踪操作的状态。 使用从 Generate Copy authorization 请求响应中复制的目标模型 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.com/formrecognizer/operations/{operation-id}?api-version=2023-07-31

跟踪复制操作的进度

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

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

跟踪目标模型 ID

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

常见错误代码消息

错误	解决方法
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 资源不是有效的认知资源，或者不存在。 若要解决此问题，请验证并重新发出复制请求。 请确保该资源有效且位于指定的区域，例如 westus2

后续步骤

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

• REST API 参考文档