障害復旧

このコンテンツの適用対象: v4.0 (プレビュー) | 以前のバージョン: v3.1 (GA) v3.0 (GA) v2.1 (GA)

Azure portal 内で Document Intelligence リソースを作成するときに、リージョンを指定します。 それ以降、ご使用のリソースとそのすべての操作はその特定の Azure サーバー リージョンに関連付けられたままになります。 リージョン全体に影響が及ぶネットワークの問題が発生することはまれですが、まったくないわけではありません。 ご自分のソリューションを常に使用できるようにする必要がある場合は、別のリージョンにフェールオーバーするか、複数のリージョン間でワークロードを分割するように設計する必要があります。 どちらの方法でも、リージョンごとに少なくとも 2 つの Document Intelligence リソースと、リージョン間でカスタム モデルと分類子を同期する機能が必要です。

コピー API によって、ある Document Intelligence アカウントからのカスタム モデルと分類子のコピー、またはサポートされている任意の地理的リージョンに存在できる別のアカウントへのコピーが可能になり、このシナリオが実現します。 このガイドでは、カスタム モデルの cURL と共にコピー REST API を使用する方法について説明します。 HTTP 要求サービスを使用して、要求を発行することもできます。

Note

2024-07-31-preview API 以降、カスタム分類モデルではコピー API もサポートされています。 このガイドでは、特にカスタム モデルを使用してモデルをコピーします。 分類子モデルのコピーの場合は、このガイドに従ってください。

ビジネス シナリオ

ご自分のアプリまたはビジネスが Document Intelligence カスタム モデルの使用に依存している場合は、別のリージョン内の別の Document Intelligence アカウントにご使用のモデルをコピーすることをお勧めします。 地域的な障害が発生した場合は、コピー先のリージョン内のご自分のモデルにアクセスできます。

前提条件

1. 異なる Azure リージョン内にある 2 つの Document Intelligence Azure リソース。 それらがない場合は、Azure portal に移動し、新しい Document Intelligence リソースを作成します。
2. ご使用の Document Intelligence リソースのキー、エンドポイント URL、およびサブスクリプション ID。 これらの値は Azure portal 上のリソースの [概要] タブにあります。

コピー API の概要

カスタム モデルをコピーするプロセスは、次の手順で構成されています。

1. まず、ターゲット リソース、つまりコピーされたモデルを受け取るリソースに対してコピー認可要求を発行します。 コピーされたモデルを受け取る新しく作成されたターゲット モデルの URL が返されます。
2. 次に、ソース リソース (前の呼び出しから返されたペイロード (コピー承認) を持つ、コピーするモデルが含まれているリソース) にコピー要求を送信します。 クエリを実行して操作の進行状況を追跡できる URL が返されます。
3. 操作が成功するまで、ご自分のソース リソースの資格情報を使用して、進行状況の URL に対してクエリを実行します。 また、ターゲット リソース内の新しいモデル ID に対してクエリを実行して、新しいモデルの状態を取得することもできます。

コピー承認要求を生成する

次の HTTP 要求では、ターゲット リソースからコピー承認を取得します。 ご自分のターゲット リソースのエンドポイントとキーをヘッダーとして入力する必要があります。

POST https://<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

要求本文

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

コピーを開始するために必要な JSON ペイロードを含む応答本文が追加された 200 応答コードを受信します。

{
  "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 とヘッダーとして入力する必要があります。 コピーするソース モデルのモデル ID が要求 URL に含まれていることに注目してください。

POST https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-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://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

Note

コピー API では、AEK/CMK 機能が透過的にサポートされます。 これには特別な処理は必要ありませんが、暗号化されていないリソースと暗号化されたリソースの間でコピーを行う場合は、要求ヘッダー x-ms-forms-copy-degrade: true を含める必要があることにご注意ください。 このヘッダーが含まれていない場合、コピー操作は失敗し、DataProtectionTransformServiceError が返されます。

コピーの進行状況を追跡する

GET https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{<operation-id>}?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

ターゲット モデル ID を追跡する

Get model API を使い、ターゲット モデルのクエリを実行することによって、操作の状態を追跡することもできます。 「Generate copy authorization 要求」の応答からコピーしたターゲット モデル ID を使って、API を呼び出します。

GET https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}?api-version=2024-02-29-preview" -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 とサブスクリプション情報を入力する必要もあります。

コピーの認可を生成する

Request

curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview"
-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"
}

コピー操作を開始する

Request

curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview"
-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://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

コピー操作の進行状況を追跡する

取得操作 API を使うと、Document Intelligence リソースに関連付けられているすべてのドキュメント モデル操作 (成功、進行中、または失敗) の一覧を表示できます。 操作情報は 24 時間だけ保持されます。 取得できる操作 (operationId) の一覧を次に示します。

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

ターゲット モデル ID を追跡する

操作が成功した場合は、getModel (1 つのモデルを取得) API または GetModels (モデルの一覧を取得) API を使って、ドキュメント モデルにアクセスできます。

一般的なエラー コード メッセージ

エラー	解決策
400 / "code:" "1002" が指定された無効な要求	検証エラーまたはコピー要求の形式が正しくないことを示します。 一般的な問題には次のようなものがあります。a) 無効または変更された copyAuthorization ペイロード。 b) expirationDateTimeTicks トークンの期限切れの値 (copyAuthorization ペイロードは 24 時間有効です)。 c) 無効またはサポートされていない targetResourceRegion。 d) 無効または形式が正しくない targetResourceId 文字列。
Authorization failure due to missing or invalid authorization claims (認可要求が見つからないか無効なため、認可エラーが発生しました)	copyAuthorization ペイロードまたはコンテンツが copyAuthorization API から変更されたときに発生します。 ペイロードが、前の copyAuthorization の呼び出しから返されたものと確実にまったく同じ内容であるようにします。
Couldn't retrieve authorization metadata (認可メタデータを取得できませんでした)	copyAuthorization ペイロードがコピー要求で再利用されていることを示します。 コピー要求が成功した場合、それ以上、同じ copyAuthorization ペイロードを使用する要求は許可されません。 別のエラーが発生した後に、同じ認可ペイロードでコピーを再試行すると、このエラーが発生します。 この解決策は、新しい copyAuthorization ペイロードを生成してから、コピー要求を再発行することです。
Data transfer request isn't allowed as it downgrades to a less secure data protection scheme (データ転送要求は、安全性の低いデータ保護スキームにダウングレードするため、許可されません)	AEK が有効なリソースと AEK が有効でないリソース間でコピーするときに発生します。 暗号化されたモデルを暗号化されていない状態でターゲットにコピーできるようにするには、コピー要求で x-ms-forms-copy-degrade: true ヘッダーを指定します。
"Couldn't fetch information for Cognitive resource with ID..." (ID を持つ Cognitive リソースの情報をフェッチできませんでした...)	targetResourceId によって示される Azure リソースが有効な Cognitive リソースではない、または、存在しないことを示します。 この問題を解決するには、コピー要求を確認して再発行します。 リソースが有効であり、指定したリージョン (westus2 など) に存在することを確認します

次のステップ

このガイドでは、コピー API を使用して、ご使用のカスタム モデルをセカンダリ Document Intelligence リソースにバックアップする方法について説明しました。 次は、API リファレンス ドキュメントを参照して、Document Intelligence を使用して他にできることを確認してください。

• REST API リファレンス ドキュメント