抽出データの検証用の成果物を作成する

artifacts API を使用して Document Understanding で抽出検証成果物を作成し、アプリケーションに人間による検証用のアプリ タスクを作成させます。

注:

この機能はプレビュー版です。

成果物 API を使用して、 Orchestrator のストレージ バケットに格納されている抽出検証成果物を準備します。その後、アーティファクトはアプリケーションで使用されて、人間による検証用の アプリ タスク が作成されます。これにより、アーティファクトの作成とタスク管理が切り離され、タスクをいつ、どこで、どのユーザー インターフェイスで作成するかを制御できるようになります。

重要:

この機能は、Automation Cloud (公共部門向け) ではアプリの作成がサポートされていないため、利用できません。

ワークフローの概要

1. ドキュメントをデジタル化します。
2. ドキュメントからデータを抽出します。
3. プロジェクトのタクソノミーを取得します。
4. 成果物の作成を開始します。
5. コンテンツ検証データの準備ができるまでポーリングを行います。
6. コンテンツ検証データを使用して、Action Center でアプリ タスクを作成します。
7. 検証 ステーションで検証を完了します。
8. 検証済みの抽出結果を取得します。

前提条件

• 抽出モデルが設定された Document Understanding プロジェクト。
• 前の抽出呼び出しから得られた documentId と extractionResult です。これらを取得するには、「 Digitization API を使用するガイドに従ってドキュメントをデジタル化し、 documentIdを取得してから、「 Extraction サービスを使用する 」ガイドに従って抽出を実行し、 extractionResultを取得します。
• テナントからアクセスできるストレージ バケットとディレクトリ パス。
• 検証タスクをホストするアプリ。Apps API の deployUnifiedPackage エンドポイントを使用すると、プログラムでアプリをデプロイできます。

必要な OAuth スコープ

外部アプリケーションには、以下のスコープを含める必要があります。外部アプリケーションの設定手順については、「 認証と認可」をご覧ください。

API 呼び出し	必要なスコープ
プロジェクトのタクソノミーを取得する	Du.Digitization.Api、 Du.Extraction.Api、 Du.Classification.Api、または Du.Validation.Api
検証エンドポイント (成果物の作成、ポーリング、結果)	Du.Validation.Api

プロジェクトのタクソノミーを取得する

Document Understanding プロジェクトのタクソノミーを取得します。抽出データの検証成果物の作成を開始するときに、このタクソノミーを渡します。

curl -X 'GET' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/projects/<Project_ID>/taxonomy?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

応答:

{
  "documentTaxonomy": {
    "dataContractVersion": "1.2",
    "documentTypes": [
      {
        "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
        "group": "",
        "category": "",
        "name": "invoices",
        "optionalUniqueIdentifier": "",
        "typeField": {
          "fieldId": "invoices.DocumentType",
          "fieldName": "Document Type"
        },
        "fields": [
          {
            "fieldId": "invoices.invoice-no",
            "fieldName": "Invoice Number",
            "isMultiValue": false,
            "type": "Text",
            "components": [],
            "setValues": [],
            "metadata": [],
            "ruleSet": null,
            "defaultValue": null,
            "dataSource": null
          }
        ]
      }
    ],
    "groups": [],
    "supportedLanguages": ["en"],
    "reportAsExceptionSettings": null
  }
}

タクソノミーを取得する別の方法

既存の検出エンドポイントを使用してタクソノミーを取得することもできます。

• GET /projects/{projectId}/extractors/{extractorId} — 特定の抽出器のタクソノミーを返します。
• GET /projects/{projectId}/tags/{tag}/document-types/{documentTypeId} — 特定のドキュメントの種類のタクソノミーをタグで返します。タグベースのフィルター処理は、Document Understanding のクラシック プロジェクトではサポートされていません。

注:

特定の抽出器またはドキュメントの種類にスコープが設定されたタクソノミーを渡すと、オペレーターは検証ステーションでの検証中に [ ドキュメントの種類を変更] 機能を使用できません。

タクソノミーのメイン エンドポイントでは、 projectVersion クエリ パラメーターと tag クエリ パラメーターもサポートされています。使用に際しては、以下の点にご注意ください。

• モダン プロジェクト: tag フィルター処理を行わないと、異なるデプロイの複数の抽出器が同じドキュメントの種類に基づいていると、同じ documentTypeId が複数回表示されることがあります。tag パラメーターを使用すると、結果のスコープを特定のデプロイに絞り、重複を避けることができます。
• クラシック プロジェクト: タグのフィルター処理はサポートされていません。同じドキュメントの種類に対して複数の抽出器が存在する場合は、曖昧さを避けるため、代わりに抽出器固有のエンドポイント (/projects/{projectId}/extractors/{extractorId}) を使用します。

抽出データの検証成果物の作成を開始します

POST 要求を送信して、抽出検証成果物の作成を開始します。前の呼び出しで取得した documentTaxonomy オブジェクト全体を渡します。

documentTaxonomy が必要です。storageBucketName と folderName は任意です。folderName指定しない場合、既定で Shared フォルダーが使用されます。

重要:

個人用ワークスペース内のストレージ バケット フォルダーはサポートされていません。

curl -X 'POST' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/start?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
  "extractionResult": {
    "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
    "resultsVersion": 0,
    "resultsDocument": {
      "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
      "documentTypeName": "invoices",
      "fields": [
        {
          "fieldId": "invoices.invoice-no",
          "fieldName": "Invoice Number",
          "type": "Text",
          "isMissing": false,
          "dataSource": "Automatic",
          "values": [
            {
              "value": "181038",
              "confidence": 0.98,
              "operatorConfirmed": false
            }
          ]
        }
      ]
    }
  },
  "documentTaxonomy": {
    "dataContractVersion": "1.2",
    "documentTypes": [
      {
        "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
        "name": "invoices",
        "fields": [
          {
            "fieldId": "invoices.invoice-no",
            "fieldName": "Invoice Number",
            "type": "Text"
          }
        ]
      }
    ],
    "groups": [],
    "supportedLanguages": ["en"],
    "reportAsExceptionSettings": null
  },
  "storageBucketName": "du_storage_bucket",
  "storageBucketDirectoryPath": "du_storage_bucket"
}'

応答: 次の 2 つの呼び出しの operationId と URL を指定します。

{
  "operationId": "7c320dfc-a1b2-4c3d-8e9f-000d3a4964af",
  "artifactsUrl": "https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/content-validation-data/7c320dfc-a1b2-4c3d-8e9f-000d3a4964af?api-version=2",
  "resultUrl": "https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/validation-result/7c320dfc-a1b2-4c3d-8e9f-000d3a4964af?api-version=2"
}

成果物の準備状況をポーリングする

GET 要求を、アーティファクトの作成の開始時に返された artifactsUrl に送信し、ステータスが Succeeded または Failedになるまで送信します。

curl -X 'GET' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/content-validation-data/<operationId>?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

応答は、次の 4 つのステータスのいずれかを返します。

ステータス	意味
NotStarted	ジョブはキューに入っていますが、まだ処理されていません。
Running	アーティファクトの準備が進行中です。
Succeeded	成果物の準備ができました。アプリ タスクの作成に進みます (ステージ 6)。
Failed	成果物の準備に失敗しました。詳しくは error.code をご覧ください。

成果物の準備ができたときの応答:

{
  "contentValidationData": {
    "bucketName": "du_storage_bucket",
    "bucketId": 261151,
    "folderId": 810789,
    "folderKey": "4c6ff0e2-0a05-4ce1-9508-7102b977bd58",
    "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
    "encodedDocumentPath": "du_storage_bucket/7c320dfc-.../encoded.zip",
    "textPath": "du_storage_bucket/7c320dfc-.../text.zip",
    "documentObjectModelPath": "du_storage_bucket/7c320dfc-.../dom.zip",
    "taxonomyPath": "du_storage_bucket/7c320dfc-.../taxonomy.zip",
    "automaticExtractionResultsPath": "du_storage_bucket/7c320dfc-.../input_results.zip",
    "validatedExtractionResultsPath": "du_storage_bucket/7c320dfc-.../output_results.zip",
    "customizationInfoPath": "du_storage_bucket/7c320dfc-.../customization_info.zip"
  },
  "status": "Succeeded",
  "createdAt": "2026-04-28T10:00:00Z",
  "lastUpdatedAt": "2026-04-28T10:00:05Z"
}

注:

contentValidationData オブジェクトには、検証ステーションでドキュメントを開くために必要な Orchestrator ストレージ バケットのパスが含まれます。検証ステーションでは、アプリ タスクのフローにコンパクト モードが使用されます。このフローではクラシック モードは利用できません。

まだ処理中の場合の応答:

{
  "status": "Running",
  "createdAt": "2026-04-28T10:00:00Z",
  "lastUpdatedAt": "2026-04-28T10:00:02Z"
}

検証済みの抽出結果を取得します

人間のオペレーターが検証ステーションでの検証を完了した後 (ステージ 6 から 7) に、このエンドポイントを呼び出します。成果物の作成の開始時に返された resultUrl に GET 要求を送信します。

curl -X 'GET' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/validation-result/<operationId>?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

注:

Action Center のタスクがまだ完了していない (ステージ 6 から 7 がまだ完了していない場合)、エンドポイントは空の結果で 200 を返します。

{
  "result": {}
}

検証完了時の応答:

{
  "result": {
    "validatedExtractionResults": {
      "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
      "resultsVersion": 1,
      "resultsDocument": {
        "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
        "documentTypeName": "invoices",
        "fields": [
          {
            "fieldId": "invoices.invoice-no",
            "fieldName": "Invoice Number",
            "type": "Text",
            "isMissing": false,
            "dataSource": "Automatic",
            "values": [
              {
                "value": "181038",
                "confidence": 1,
                "operatorConfirmed": true
              }
            ],
            "operatorConfirmed": true
          }
        ]
      }
    }
  }
}

結果

抽出データの検証が完了したことを確認するvalidatedExtractionResultsを含む200応答。各フィールドの operatorConfirmed: true フラグは、結果が検証されたことを示します。