災害復原

此內容適用於： 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 和訂用帳戶識別碼。 您可以在 Azure 入口網站中經由資源的 [概觀] 索引標籤找到這些值。

複製 API 概觀

複製自訂模型的流程包含下列步驟：

1. 首先，您要向接收複製模型的目標資源發出複製授權要求。 您會收到新建目標模型 (接收複製的模型) 的 URL。
2. 接著，您會將複製要求傳送至來源資源 — 此資源包含要複製的模型以及先前的呼叫所傳回的承載 (複製授權)。 您會收到可查詢以追蹤作業進度的 URL。
3. 您可使用自己的來源資源認證來查詢進度 URL，直到作業成功為止。 您也可以在目標資源中查詢新的模型識別碼，以取得新模型的狀態。

產生複製授權要求

下列 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 包含您想要複製之來源模型的模型識別碼。

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

您收到包含 Operation-Location 標頭的 202\Accepted 回應。 此值是您用來追蹤作業進度的 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}

追蹤目標模型識別碼

您也可以使用 GET model API，透過查詢目標模型來追蹤作業的狀態。 使用您從Generate Copy authorization要求回應中複製的目標模型識別碼來呼叫 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 呼叫。 您也需要填入您資源專屬的模型識別碼和訂閱資訊。

產生複製授權

要求

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 小時。 以下是可傳回的作業 (operationsId) 清單：

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

追蹤目標模型識別碼

如果作業成功，即可使用 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 標頭。
「無法擷取識別碼為 ... 的認知資源相關資訊」。	指出 targetResourceId 指出的 Azure 資源不是有效的認知資源或不存在。 若要解決此問題，請驗證並重新發出複製要求。 請確定資源有效且存在於指定的區域中，例如 westus2

下一步

在本指南中，您已了解如何使用複製 API 將自訂模型備份至次要文件智慧服務資源。 接下來，請探索 API 參考文件，以了解您還可以使用文件智慧服務執行哪些功能。

• REST API 參考文件