Document Intelligence バッチ分析

バッチ分析 API を使用すると、1 つの要求を使用して最大 10,000 個のドキュメントを一括処理できます。ドキュメントを 1 つずつ分析し、それぞれの要求 ID を追跡する代わりに、請求書、ローンの書類、カスタムドキュメントなどのドキュメントのコレクションを同時に分析できます。入力ドキュメントは、Azure BLOB ストレージコンテナーに格納する必要があります。ドキュメントが処理されると、API は指定されたストレージコンテナーに結果を書き込みます。

バッチ分析の制限

1 つのバッチ要求に含めることができるドキュメントファイルの最大数は 10,000 です。
バッチ操作の結果は、完了後 24 時間保持されます。バッチ処理が完了してから 24 時間後に、バッチ操作の状態は使用できなくなります。入力ドキュメントとそれぞれの結果ファイルは、指定されたストレージコンテナーに残ります。

前提条件

有効な Azure サブスクリプション Azure サブスクリプションがない場合は、無料で作成することができます。
ドキュメントインテリジェンス Azure リソース: Azure サブスクリプションを取得したら、Azure portal でドキュメントインテリジェンスリソースを作成します。無料価格レベル (F0) を使用して、サービスを試すことができます。リソースがデプロイされたら、[ リソースに移動 ] を選択してキーとエンドポイントを取得 します。アプリケーションをドキュメントインテリジェンスサービスに接続するには、リソースキーとエンドポイントが必要です。これらの値は、Azure portal の [キーとエンドポイント] ページでも確認できます。
Azure Blob Storage アカウント。ソースファイルと結果ファイル用の 2 つのコンテナーを Azure Blob Storage アカウントに作成します。
- ソースコンテナー: このコンテナーは、分析のためにドキュメントファイルをアップロードする場所です。
- 結果コンテナー: このコンテナーは、バッチ分析 API からの結果が格納される場所です。

ストレージコンテナーの承認

API が Azure ストレージコンテナーでドキュメントを処理し、結果を書き込むのを許可するには、次の 2 つのオプションのいずれかを使用して承認する必要があります。

✔️マネージド ID。マネージド ID は、Microsoft Entra ID と、Azure 管理対象リソースの固有アクセス許可を作成するサービスプリンシパルです。マネージド ID を使用すると、コードに資格情報を埋め込む必要なくドキュメントインテリジェンスアプリケーションを実行できます。これにより、コードにアクセス署名トークン (SAS) を含めずにストレージデータへのアクセスを許可するより安全な方法になります。

ドキュメントインテリジェンスのマネージド ID を確認して、リソースのマネージド ID を有効にし、ストレージコンテナーへのアクセス権を付与する方法を確認します。

重要

マネージド ID を使用する場合は、HTTP 要求に SAS トークン URL を含めないでください。マネージド ID を使用すると、Shared Access Signature トークン (SAS) を含める必要がなくなります。

✔️ Shared Access Signature (SAS)。 Shared Access Signature は、ストレージコンテナーへの制限付きアクセスを許可する URL です。このメソッドを使用するには、ソースコンテナーと結果コンテナーの Shared Access Signature (SAS) トークンを作成します。 Azure portal でストレージコンテナーに移動し、[ 共有アクセストークン ] を選択して SAS トークンと URL を生成します。

ソース コンテナーまたは BLOB は、読み取り、書き込み、一覧表示、および削除のアクセス許可を指定する必要があります。
結果コンテナーまたは BLOB は、書き込み、一覧表示、削除のアクセス許可を指定する必要があります。

Azure portal の SAS アクセス許可フィールドを示すスクリーンショット。

SAS トークンの生成とそのしくみについて詳しくは、「SAS トークンの作成」をご覧ください。

バッチ分析 API を呼び出す

1. 入力ファイルを指定する

バッチ API では、処理するファイルを指定するための 2 つのオプションがサポートされています。

コンテナーまたはフォルダー内のすべてのファイルを処理し、ファイルの数が 1,0000 未満の場合は、要求で azureBlobSource オブジェクトを使用します。

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken"

},
{
   "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
   "resultPrefix": "trainingDocsResult/"
}

コンテナーまたはフォルダー内のすべてのファイルではなく、そのコンテナーまたはフォルダー内の特定のファイルを処理する場合は、 azureBlobFileListSource オブジェクトを使用します。この操作には、処理するファイルを一覧表示するファイルリスト JSONL ファイルが必要です。 JSONL ファイルをコンテナーのルートフォルダーに格納します。 2 つのファイルが一覧表示された JSONL ファイルの例を次に示します。
```
{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}
```

次の条件でファイル JSONL ファイルの一覧を使用します。

コンテナー内のすべてのファイルではなく、特定のファイルを処理する必要がある場合。
入力コンテナーまたはフォルダー内のファイルの合計数が 10,000 個のファイルバッチ処理の制限を超えた場合。
各バッチ要求で処理されるファイルをより詳細に制御する場合。

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobFileListSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "fileList": "myFileList.jsonl"
    ...
  },
  ...
}

両方のオプションで、コンテナー URL またはコンテナー SAS URL が必要です。マネージド ID を使用してストレージコンテナーにアクセスする場合は、コンテナー URL を使用します。 Shared Access Signature (SAS) を使用している場合は、SAS URL を使用します。

2. 結果の場所を指定する

resultContainerURL パラメーターを使用して結果を格納する Azure Blob Storage コンテナー URL (またはコンテナー SAS URL) を指定します。誤って上書きされないように、ソースと結果に個別のコンテナーを使用することをお勧めします。
overwriteExisting Boolean プロパティをFalseに設定し、同じドキュメントの既存の結果が上書きされないようにします。既存の結果を上書きする場合は、ブール値を True に設定します。既存の結果が上書きされない場合でも、ドキュメントの処理に対して課金されます。
resultPrefixを使用して、結果をグループ化し、特定のコンテナーフォルダーに格納します。

3. POST 要求をビルドして実行する

次のサンプルコンテナーの URL 値は、Azure Blob Storage コンテナーの実際の値に置き換えてください。

この例では、入力を含む POST 要求 azureBlobSource 示します

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "inputDocs/"
  },
  {
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "batchResults/",
  "overwriteExisting": true
}

この例では、 azureBlobFileListSource とファイルリストの入力を含む POST 要求を示します

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
{
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "batchResults/",
  "overwriteExisting": true
}

成功した応答の例を次に示します。

202 Accepted
Operation-Location: /documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30

4. API の結果を取得する

post 操作の実行後にバッチ分析結果を取得するには、 GET 操作を使用します。 GET 操作では、状態情報、バッチ完了率、および操作の作成と更新の日付/時刻がフェッチされます。この情報は、バッチ分析が完了してから 24 時間だけ保持されます 。

GET {endpoint}/documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

5. ステータスメッセージを解釈する

処理されるドキュメントごとに、 succeeded、 failed、 running、 notStarted、または skippedのいずれかの状態が割り当てられます。入力ドキュメントのソース BLOB ストレージコンテナーであるソース URL が提供されます。

状態 notStarted または running。バッチ分析操作が開始されていないか、完了していません。すべてのドキュメントに対する操作が完了するまで待ちます。
状態 completed。バッチ分析操作が完了しました。

状態 succeeded。バッチ操作が成功し、入力ドキュメントが処理されました。結果は、resultUrl、resultContainerUrl、resultPrefix、およびinput filename拡張機能を組み合わせて作成された.ocr.jsonで使用できます。 プロパティがresultUrlされるのは、成功したファイルだけです。

succeeded 状態の応答の例:

{
    "resultId": "myresultId-",
    "status": "succeeded",
    "percentCompleted": 100,
    "createdDateTime": "2025-01-01T00:00:000",
    "lastUpdatedDateTime": "2025-01-01T00:00:000",
    "result": {
        "succeededCount": 10,000,
        "failedCount": 0,
        "skippedCount": 0,
        "details": [
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document1.pdf.ocr.json",
                "status": "succeeded"
            },
          ...
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document10000.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document10000.pdf.ocr.json",
                "status": "succeeded"
            }
       ]

     }
}

状態 failed。このエラーは、バッチ要求全体においてエラーがある場合にのみ返されます。バッチ分析操作が開始されると、すべてのファイルに状態が failedされている場合でも、個々のドキュメント操作の状態はバッチジョブ全体の状態には影響しません。

failed 状態の応答の例:

[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 0,
    "details": [
        "sourceUrl": "https://{your-source-container}/inputFolder/document1.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

状態 skipped: 通常、この状態は、ドキュメントの出力が指定された出力フォルダーに既に存在し、 overwriteExisting Boolean プロパティが falseに設定されている場合に発生します。

skipped 状態の応答の例:
```
[
     "result": {
     "succeededCount": 3,
     "failedCount": 0,
     "skippedCount": 2,
     "details": [
         ...
         "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
         "status": "skipped",
         "error": {
             "code": "OutputExists",
             "message": "Analysis skipped because result file https://{your-result-container}/resultsFolder/document1.pdf.ocr.json already exists."
              }
         ]
     }
]
...
```
Note

バッチ全体の分析が完了するまで、個々のファイルの分析結果は返されません。 percentCompleted以外の詳細な進行状況を追跡するには、*.ocr.jsonに書き込まれるresultContainerUrlファイルを監視できます。

次のステップ

GitHub でコードサンプルを見る。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-18