Gerenciar operações de longa duração (LROs)
As operações de longa duração são retornadas por chamadas de método de processamento
em lote porque levam mais tempo para serem concluídas do que o adequado
para uma resposta da API. Isso evita que a linha de execução de chamada fique aberta enquanto muitos
documentos são processados. A API Document AI cria uma LRO sempre que você
chama projects.locations.processors.batchProcess
pela API ou pelas bibliotecas de cliente. A LRO acompanha o status do job de processamento.
É possível usar os métodos de operações que a API Document AI fornece para verificar o status das LROs. Também é possível listar, pesquisar ou cancelar LROs. As bibliotecas de cliente que chamam
o método assíncrono fazem pesquisas internamente, ativando o callback. No Python, await
está ativado. Eles também têm um parâmetro de tempo limite. Na LRO principal retornada por .batchProcess, uma LRO
é criada para cada documento, porque os limites de contagem de páginas em lote são muito maiores do que
a chamada síncrona process
e podem levar um tempo significativo para serem processados. Quando a LRO principal termina, o status detalhado de cada LRO de documento é fornecido.
As LROs são gerenciadas no nível do projeto e do local Google Cloud . Ao fazer uma solicitação à API, inclua o projeto Google Cloud e o local em que a LRO está sendo executada.
O registro de uma LRO é mantido por, aproximadamente, 30 dias após a conclusão da LRO. Isso significa que não é possível visualizar ou listar uma LRO após esse período.
Como acessar os detalhes sobre uma operação de longa duração
Os exemplos a seguir mostram como acessar os detalhes de uma LRO.
REST
Para acessar o status e visualizar os detalhes de uma LRO, chame o método projects.locations.operations.get
.
Suponhamos que você receba a seguinte resposta após chamar projects.locations.processors.batchProcess
:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID" }
O valor name
na resposta mostra que a API Document AI
criou uma LRO chamada projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID
.
Também é possível recuperar o nome da LRO listando operações de longa duração.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: o local em que a LRO está sendo executada. Por exemplo:
us
: Estados Unidoseu
: União Europeia
- OPERATION_ID: o ID da operação. Ele é o último elemento do nome
da operação. Por exemplo:
- Nome da operação:
projects/PROJECT_ID/locations/LOCATION/operations/bc4e1d412863e626
- ID da operação:
bc4e1d412863e626
- Nome da operação:
Método HTTP e URL:
GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
Para enviar a solicitação, escolha uma destas opções:
curl
execute o seguinte comando:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
PowerShell
execute o seguinte comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a esta:
{ "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata", "state": "SUCCEEDED", "stateMessage": "Processed 1 document(s) successfully", "createTime": "TIMESTAMP", "updateTime": "TIMESTAMP", "individualProcessStatuses": [ { "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext", "status": {}, "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0", "humanReviewStatus": { "state": "ERROR", "stateMessage": "Sharded document protos are not supported for human review." } } ] }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse" } }
Go
Para mais informações, consulte a documentação de referência da API Go da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Como listar operações de longa duração
Os exemplos a seguir mostram como listar as LROs em um Google Cloud projeto e local.
REST
Para listar as LROs em um projeto e local do Google Cloud , chame o método projects.locations.operations.list
.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: o local onde uma ou mais LROs estão sendo executadas. Por exemplo:
us
: Estados Unidoseu
: União Europeia
- FILTER: (obrigatório) consulta para LROs a serem retornadas. Opções:
- TYPE: (obrigatório) tipo de LRO a ser listado. Opções:
BATCH_PROCESS_DOCUMENTS
CREATE_PROCESSOR_VERSION
DELETE_PROCESSOR
ENABLE_PROCESSOR
DISABLE_PROCESSOR
UPDATE_HUMAN_REVIEW_CONFIG
HUMAN_REVIEW_EVENT
CREATE_LABELER_POOL
UPDATE_LABELER_POOL
DELETE_LABELER_POOL
DEPLOY_PROCESSOR_VERSION
UNDEPLOY_PROCESSOR_VERSION
DELETE_PROCESSOR_VERSION
SET_DEFAULT_PROCESSOR_VERSION
EVALUATE_PROCESSOR_VERSION
EXPORT_PROCESSOR_VERSION
UPDATE_DATASET
IMPORT_DOCUMENTS
ANALYZE_HITL_DATA
BATCH_MOVE_DOCUMENTS
RESYNC_DATASET
BATCH_DELETE_DOCUMENTS
DELETE_DATA_LABELING_JOB
EXPORT_DOCUMENTS
Método HTTP e URL:
GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations?filter=TYPE=TYPE
Para enviar a solicitação, escolha uma destas opções:
curl
execute o seguinte comando:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations?filter=TYPE=TYPE"
PowerShell
execute o seguinte comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations?filter=TYPE=TYPE" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a esta:
{ "operations": [ { "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata", "state": "SUCCEEDED", "stateMessage": "Processed 1 document(s) successfully", "createTime": "TIMESTAMP", "updateTime": "TIMESTAMP", "individualProcessStatuses": [ { "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext", "status": {}, "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0", "humanReviewStatus": { "state": "ERROR", "stateMessage": "Sharded document protos are not supported for human review." } } ] }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse" } }, ... ] }
Go
Para mais informações, consulte a documentação de referência da API Go da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Como pesquisar uma operação de longa duração
Os exemplos a seguir mostram como consultar o status de uma LRO.
REST
Para pesquisar uma LRO, chame repetidamente o método projects.locations.operations.get
até que a operação seja concluída. Use um recuo entre cada solicitação de pesquisa. Por exemplo, pesquise a cada 10 segundos.
Antes de usar algum dos dados de solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do Google Cloud projeto
- LOCATION: o local onde a LRO está sendo executada
- OPERATION_ID: o identificador da LRO
Método HTTP e URL:
GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
Para enviar a solicitação, escolha uma destas opções:
curl
Execute o seguinte comando para pesquisar o status de uma LRO a cada 10 segundos:
while true; \ do curl -X GET \ -H "Authorization: Bearer "$(gcloud auth print-access-token) \ "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"; \ sleep 10; \ done
Você vai receber uma resposta JSON a cada 10 segundos.
Enquanto a operação estiver em execução, a resposta vai conter "state": "RUNNING"
.
Quando a operação for concluída, a resposta vai conter "state": "SUCCEEDED"
e "done": true
.
PowerShell
Execute o seguinte comando para pesquisar o status de uma LRO a cada 10 segundos:
$cred = gcloud auth print-access-token $headers = @{ Authorization = "Bearer $cred" } Do { Invoke-WebRequest ` -Method Get ` -Headers $headers ` -Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content sleep 10 } while ($true)
Você vai receber uma resposta JSON a cada 10 segundos.
Enquanto a operação estiver em execução, a resposta vai conter "state": "RUNNING"
.
Quando a operação for concluída, a resposta vai conter "state": "SUCCEEDED"
e "done": true
.
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Como cancelar uma operação de longa duração
As amostras a seguir mostram como cancelar uma LRO enquanto ela está em execução.
REST
Para cancelar uma LRO, chame o método projects.locations.operations.cancel
.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud .
- LOCATION: o local em que a LRO está sendo executada. Por exemplo:
us
: Estados Unidoseu
: União Europeia
- OPERATION_ID: o ID da operação. Ele é o último elemento do nome
da operação. Por exemplo:
- Nome da operação:
projects/PROJECT_ID/locations/LOCATION/operations/bc4e1d412863e626
- ID da operação:
bc4e1d412863e626
- Nome da operação:
Método HTTP e URL:
POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel
Para enviar a solicitação, escolha uma destas opções:
curl
execute o seguinte comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel"
PowerShell
execute o seguinte comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a esta:
{}
"error": { "code": 400, "message": "Operation has completed and cannot be cancelled: 'PROJECT_ID/locations/LOCATION/operations/OPERATION_ID'.", "status": "FAILED_PRECONDITION" }
Go
Para mais informações, consulte a documentação de referência da API Go da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para mais informações, consulte a documentação de referência da API Python da Document AI.
Para autenticar na Document AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.