Criar artefatos para validação de extração

Crie artefatos de validação de extração no Document Understanding usando as APIs de artefatos e, em seguida, deixe seu aplicativo criar uma Tarefa de aplicativo para validação humana.

Observação:

Essa funcionalidade está em visualização.

Use as APIs de artefatos para preparar artefatos de validação de extração armazenados em Buckets de armazenamento do Orchestrator. Os artefatos são então usados por seu aplicativo para criar uma Tarefa de aplicativo para validação humana — dissociando a criação de artefatos do gerenciamento de tarefas e dando a você controle sobre quando, onde e com qual interface de usuário a tarefa é criada.

Importante:

Essa funcionalidade não está disponível na Automation Cloud Public Sector, porque a criação de aplicativos não é compatível lá.

Visão geral do fluxo de trabalho

1. Digitalizar o documento.
2. Extrair dados do documento.
3. Recuperar a taxonomia do projeto.
4. Inicie a criação do artefato.
5. Pesquise até que os dados de validação de conteúdo estejam prontos.
6. Crie uma tarefa de aplicativo no Action Center usando os dados de validação de conteúdo.
7. Conclua a validação na Estação de validação.
8. Recupere o resultado da extração validado.

Pré-requisitos

• Um projeto do Document Understanding com um modelo de extração configurado.
• O documentId e extractionResult de uma chamada de extração anterior. Para obtê-los, siga o guia Usar as APIs de digitalização para digitalizar o documento e obter um documentId, em seguida, siga o guia Usar o Serviço de Extração para executar a extração e obter o extractionResult.
• Um bucket de armazenamento e um caminho de diretório acessível a partir do seu tenant.
• Um aplicativo para hospedar a tarefa de validação. Você pode implantar o aplicativo programaticamente usando o ponto de extremidade deployUnifiedPackage da API do Apps.

Escopos do OAuth exigidos

Seu aplicativo externo deve incluir os seguintes escopos. Para obter instruções sobre como configurar um aplicativo externo, consulte Autenticação e autorização.

API call	Escopo obrigatório
Recuperar a taxonomia do projeto	Du.Digitization.Api, Du.Extraction.Api, Du.Classification.Api, ou Du.Validation.Api
Pontos de extremidade de validação (criação de artefatos, pesquisa, resultado)	Du.Validation.Api

Recuperar a taxonomia do projeto

Recupere a taxonomia do seu projeto do Document Understanding. Passe esta taxonomia quando você iniciar a criação dos artefatos de validação de extração.

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>'

Resposta:

{
  "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
  }
}

Maneiras alternativas de recuperar a taxonomia

Você também pode recuperar a taxonomia usando pontos de extremidade de descoberta existentes:

• GET /projects/{projectId}/extractors/{extractorId} — retorna a taxonomia para um extrator específico.
• GET /projects/{projectId}/tags/{tag}/document-types/{documentTypeId} — retorna a taxonomia para um tipo de documento específico por tag. A filtragem baseada em tags não é compatível com projetos clássicos do Document Understanding.

Observação:

Se você passar uma taxonomia com escopo para um extrator ou tipo de documento específico, a funcionalidade Alterar tipo de documento não estará disponível para o operador durante a validação na Estação de validação.

O ponto de extremidade principal da taxonomia também é compatível com projectVersion e tag parâmetros de consulta. Esteja ciente do seguinte ao usá-lo:

• Projetos modernos: sem a filtragem tag , o mesmo documentTypeId pode aparecer várias vezes se vários extratores de diferentes implantações forem baseados no mesmo tipo de documento. Use o parâmetro tag para delimitar resultados para uma implantação específica e evitar duplicatas.
• Projetos clássicos: a filtragem de tags não é compatível. Se existirem vários extratores para o mesmo tipo de documento, use o ponto de extremidade específico do extrator/projects/{projectId}/extractors/{extractorId} () para evitar ambiguidade.

Inicie a criação de artefatos de validação de extração

Envie uma solicitação POST para iniciar a criação de artefatos de validação de extração. Passe o objeto documentTaxonomy completo recuperado na chamada anterior.

documentTaxonomy é necessário. storageBucketName e folderName são opcionais. Se você não especificar folderName, o padrão será a pasta Shared.

Importante:

Pastas do bucket de armazenamento dentro do seu espaço de trabalho pessoal não são compatíveis.

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"
}'

Resposta — fornece as operationId e URLs para as próximas duas chamadas:

{
  "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"
}

Enquete da prontidão do artefato

Envie solicitações GET para os artifactsUrl retornados quando você iniciou a criação do artefato, até que o status seja Succeeded ou 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>'

A resposta retorna um dos quatro status:

Status	Significado
NotStarted	O trabalho está na fila, mas ainda não está em processamento.
Running	A preparação do artefato está em progresso.
Succeeded	Os artefatos estão prontos. Continue com a criação da tarefa de aplicativo (etapa 6).
Failed	Falha na preparação do artefato. Verifique error.code para obter detalhes.

Resposta quando os artefatos estiverem prontos:

{
  "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"
}

Observação:

O objeto contentValidationData contém os caminhos do Bucket de Armazenamento do Orchestrator necessários para abrir o documento na Estação de Validação. O Validation Station usa modo compacto para fluxos de Tarefas de aplicativo; o modo clássico não está disponível para este fluxo.

Resposta quando ainda está processando:

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

Recuperar o resultado da extração validado

Chame esse ponto de extremidade depois que o operador humano concluir a validação na Estação de validação (etapas 6 e 7). Envie uma solicitação GET para o resultUrl retornado quando você iniciou a criação do artefato.

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>'

Observação:

Se a tarefa do Action Center ainda não tiver sido concluída (etapas 6 e 7 ainda não concluídas), o ponto de extremidade retornará 200 com um resultado vazio:

{
  "result": {}
}

Resposta quando a validação for concluída:

{
  "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
          }
        ]
      }
    }
  }
}

Resultado

Uma resposta 200 contendo validatedExtractionResults confirma que a validação da extração está concluída. O sinalizador operatorConfirmed: true em cada campo indica que o resultado foi validado.