- 入门指南
- Document Understanding™ Cloud API v1 使用示例
- 许可
- 故障排除
创建用于提取验证的工件
使用工件 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。要获取这些值,请按照使用数字化 API指南将文档数字化并获取documentId,然后按照使用提取服务指南运行提取并获取extractionResult。 - 可从您的租户访问的存储桶和目录路径。
- 用于托管验证任务的应用程序。您可以使用 Apps API
deployUnifiedPackage端点以编程方式部署应用程序。
所需的 OAuth 作用域
您的外部应用程序必须包含以下作用域。有关设置外部应用程序的说明,请参阅身份验证与授权。
| API call | 所需作用域 |
|---|---|
| 检索项目分类 | 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"
}'
响应 — 提供接下来两次调用的 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"
}
轮询工件就绪情况
向开始创建工件时返回的 artifactsUrl 发送 GET 请求,直到状态为 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>'
响应将返回以下四种状态之一:
| 状态 | 意义 |
|---|---|
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
}
]
}
}
}
}
结果
包含 200 的 validatedExtractionResults 响应确认提取验证已完成。每个字段上的 operatorConfirmed: true 标志表示结果已经过验证。