- 基本情報
- Document Understanding™ Cloud API v1 の使用例
- ライセンス
- トラブルシューティング
抽出データの検証用の成果物を作成する
artifacts API を使用して Document Understanding で抽出検証成果物を作成し、アプリケーションに人間による検証用のアプリ タスクを作成させます。
この機能はプレビュー版です。
Use the artifacts APIs to prepare extraction validation artifacts stored in Orchestrator Storage Buckets. The artifacts are then used by your application to create an App Task for human validation — decoupling artifact creation from task management and giving you control over when, where, and with what user interface the task is created.
この機能は、Automation Cloud (公共部門向け) ではアプリの作成がサポートされていないため、利用できません。
ワークフローの概要
- ドキュメントをデジタル化します。
- ドキュメントからデータを抽出します。
- プロジェクトのタクソノミーを取得します。
- 成果物の作成を開始します。
- コンテンツ検証データの準備ができるまでポーリングを行います。
- コンテンツ検証データを使用して、Action Center でアプリ タスクを作成します。
- 検証 ステーションで検証を完了します。
- 検証済みの抽出結果を取得します。
コード化されたアプリまたは別のカスタム React アプリケーションに検証ステーションを埋め込むには、GitHub の 検証ステーション ウィジェットのドキュメント をご覧ください。
前提条件
- 抽出モデルが設定された 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>'
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
}
}
{
"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"
}'
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"
}
{
"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>'
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": {
"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"
}
{
"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>'
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": {}
}
検証完了時の応答:
{
"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
}
]
}
}
}
}
{
"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 フラグは、結果が検証されたことを示します。