Gestione delle operazioni a lunga esecuzione (LRO)
Le operazioni a lunga esecuzione vengono restituite dalle chiamate ai metodi di elaborazione batch perché richiedono più tempo per essere completate rispetto a quanto appropriato per una risposta API. In questo modo, il thread di chiamata non rimane aperto durante l'elaborazione di molti documenti. L'API Document AI crea un'operazione di lunga durata ogni volta che chiami projects.locations.processors.batchProcess
tramite l'API o le librerie client. L'operazione di lunga durata monitora lo stato del job di elaborazione.
Puoi utilizzare i metodi delle operazioni
forniti dall'API Document AI per controllare lo
stato delle operazioni LRO. Puoi anche elencare, sondare o annullare le operazioni di lunga durata. Le librerie client chiamano
il polling del metodo asincrono internamente, consentendo il callback. (Per Python, await
è attivato.) Includono anche
un parametro di timeout. All'interno dell'LRO principale restituito da .batchProcess, viene creato un LRO per ogni documento (perché i limiti del conteggio delle pagine batch sono molto più elevati della chiamata di sincronizzazione process
e l'elaborazione può richiedere molto tempo). Al termine dell'LRO principale, viene fornito lo stato dettagliato di ogni LRO del documento.
Gli LRO vengono gestiti a livello di Google Cloud progetto e località. Quando effettui una richiesta all'API, includi il progetto Google Cloud e la località in cui è in esecuzione l'operazione LRO.
Il record di un LRO viene conservato per circa 30 giorni dopo il termine dell'LRO, il che significa che non puoi visualizzare o elencare un LRO dopo questo periodo.
Visualizzare i dettagli di un'operazione a lunga esecuzione
Gli esempi riportati di seguito mostrano come recuperare i dettagli di un'operazione di lunga durata.
REST
Per ottenere lo stato e visualizzare i dettagli di un'operazione di lunga durata, chiama il metodo projects.locations.operations.get
.
Supponiamo che tu riceva la seguente risposta dopo aver chiamato
projects.locations.processors.batchProcess
:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID" }
Il valore name
nella risposta mostra che l'API Document AI
ha creato un'operazione di lunga durata denominata projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID
.
Puoi anche recuperare il nome dell'LRO elencando le operazioni a lunga esecuzione.
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto Google Cloud .
- LOCATION: la posizione in cui viene eseguita l'operazione LRO, ad esempio:
us
- Stati Unitieu
- Unione Europea
- OPERATION_ID: l'ID dell'operazione. L'ID è l'ultimo elemento del nome
dell'operazione. Ad esempio:
- Nome operazione:
projects/PROJECT_ID/locations/LOCATION/operations/bc4e1d412863e626
- ID operazione:
bc4e1d412863e626
- Nome operazione:
Metodo HTTP e URL:
GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
Per inviare la richiesta, scegli una di queste opzioni:
curl
Esegui questo 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
Esegui questo 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
Dovresti ricevere una risposta JSON simile alla seguente:
{ "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
Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Go.
Per autenticarti in Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Python.
Per autenticarti in Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Elenco delle operazioni a lunga esecuzione
Gli esempi riportati di seguito mostrano come elencare le operazioni di lunga durata in un progetto e in una località. Google Cloud
REST
Per elencare le operazioni LRO in un progetto e una località Google Cloud , chiama il metodo projects.locations.operations.list
.
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto Google Cloud .
- LOCATION: la posizione in cui sono in esecuzione una o più operazioni di lunga durata, ad esempio:
us
- Stati Unitieu
- Unione Europea
- FILTER: (Obbligatorio) Query per le operazioni LRO da restituire. Opzioni:
- TYPE: (Obbligatorio) Il tipo di LRO da elencare. Opzioni:
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
Metodo HTTP e URL:
GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations?filter=TYPE=TYPE
Per inviare la richiesta, scegli una di queste opzioni:
curl
Esegui questo 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
Esegui questo 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
Dovresti ricevere una risposta JSON simile alla seguente:
{ "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
Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Go.
Per autenticarti in Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Python.
Per autenticarti in Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Eseguire il polling di un'operazione a lunga esecuzione
Gli esempi riportati di seguito mostrano come eseguire il polling dello stato di un'operazione di lunga durata.
REST
Per eseguire il polling di un'operazione LRO, chiama ripetutamente il metodo projects.locations.operations.get
finché l'operazione non viene completata. Utilizza un backoff tra ogni richiesta di polling,
ad esempio 10 secondi.
Prima di utilizzare i dati della richiesta riportati di seguito, effettua le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto Google Cloud
- LOCATION: la posizione in cui è in esecuzione l'operazione LRO
- OPERATION_ID: l'identificatore dell'operazione di lunga durata
Metodo HTTP e URL:
GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
Per inviare la richiesta, scegli una di queste opzioni:
curl
Esegui questo comando per eseguire il polling dello stato di un'operazione LRO ogni 10 secondi:
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
Dovresti ricevere una risposta JSON ogni 10 secondi.
Mentre l'operazione è in esecuzione, la risposta conterrà "state": "RUNNING"
.
Al termine dell'operazione, la risposta conterrà "state": "SUCCEEDED"
e "done": true
.
PowerShell
Esegui questo comando per eseguire il polling dello stato di un'operazione a lunga esecuzione ogni 10 secondi:
$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)
Dovresti ricevere una risposta JSON ogni 10 secondi.
Mentre l'operazione è in esecuzione, la risposta conterrà "state": "RUNNING"
.
Al termine dell'operazione, la risposta conterrà "state": "SUCCEEDED"
e "done": true
.
Python
Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Python.
Per autenticarti in Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Annullamento di un'operazione a lunga esecuzione
Gli esempi riportati di seguito mostrano come annullare un'operazione a lunga esecuzione durante l'esecuzione.
REST
Per annullare un'operazione a lunga esecuzione, chiama il metodo projects.locations.operations.cancel
.
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: il tuo ID progetto Google Cloud .
- LOCATION: la posizione in cui viene eseguita l'operazione LRO, ad esempio:
us
- Stati Unitieu
- Unione Europea
- OPERATION_ID: l'ID dell'operazione. L'ID è l'ultimo elemento del nome
dell'operazione. Ad esempio:
- Nome operazione:
projects/PROJECT_ID/locations/LOCATION/operations/bc4e1d412863e626
- ID operazione:
bc4e1d412863e626
- Nome operazione:
Metodo HTTP e URL:
POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel
Per inviare la richiesta, scegli una di queste opzioni:
curl
Esegui questo 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
Esegui questo 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
Dovresti ricevere una risposta JSON simile alla seguente:
{}
"error": { "code": 400, "message": "Operation has completed and cannot be cancelled: 'PROJECT_ID/locations/LOCATION/operations/OPERATION_ID'.", "status": "FAILED_PRECONDITION" }
Go
Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Go.
Per autenticarti in Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Document AI Python.
Per autenticarti in Document AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.