Gestione di operazioni a lunga esecuzione

Questa pagina descrive come gestire il ciclo di vita di un'operazione a lunga esecuzione (LRO) dell'API Cloud Healthcare.

Quando il completamento di un metodo dell'API potrebbe richiedere molto tempo, può restituire un valore Operation al client. Il client può utilizzare l'interfaccia Operation per recuperare lo stato del metodo dell'API in modo asincrono eseguendo il polling dell'operazione. Le richieste LRO nell'API Cloud Healthcare rispettano il pattern di progettazione LRO di Google Cloud.

L'API Cloud Healthcare crea LRO per diversi metodi, ad esempio projects.locations.datasets.fhirStores.import. Quando viene chiamato projects.locations.datasets.fhirStores.import, l'API Cloud Healthcare crea un LRO per monitorare lo stato dell'importazione. L'LRO ha un identificatore univoco che puoi utilizzare per visualizzare lo stato dell'LRO.

Le richieste di accesso a livello di organizzazione vengono gestite a livello di set di dati. Se chiami un metodo che restituisce un LRO, ad esempio projects.locations.datasets.fhirStores.import, puoi visualizzare lo stato dell'LRO inviando una richiesta contenente l'ID LRO al set di dati padre dell'archivio FHIR in cui avviene l'importazione.

Oltre all'API REST, le seguenti origini generano operazioni a lunga esecuzione quando chiami i metodi elencati in Metodi che restituiscono un'LRO:

Puoi gestire le richieste di accesso protette dell'API Cloud Healthcare utilizzando la console Google Cloud, la CLI Google Cloud o l'API REST.

Il record di un'LRO viene conservato per circa 30 giorni dal termine dell'LRO, il che significa che non puoi visualizzare o elencare un'LRO dopo questo periodo.

Metodi che restituiscono un LRO

I seguenti metodi restituiscono un LRO.

Metodi di gestione del consenso:

Metodi per i set di dati:

Metodi DICOM:

Metodi FHIR:

Metodi HL7v2:

Visualizzare i dettagli di un'operazione di recupero locale

Gli esempi riportati di seguito mostrano come recuperare i dettagli di un LRO.

La versione dell'API Cloud Healthcare mostrata nella risposta quando vengono visualizzati i dettagli di un LRO è la stessa della versione dell'API del metodo che ha avviato l'LRO.

Console

Dopo aver chiamato un metodo utilizzando l'interfaccia a riga di comando gcloud o l'API che restituisce un LRO, puoi visualizzare i dettagli dell'LRO nella console Google Cloud.

  1. Nella console Google Cloud, vai alla pagina Set di dati.

    Vai a Set di dati

  2. Fai clic sul nome del set di dati contenente l'ODM che vuoi visualizzare.

  3. Fai clic su Operazioni.

  4. Per visualizzare i log degli errori relativi all'operazione in Cloud Logging, fai clic su Azioni e poi su Visualizza dettagli in Cloud Logging. Per ulteriori informazioni, consulta Visualizzazione dei log degli errori in Cloud Logging.

  5. Per visualizzare ulteriori dettagli sull'operazione, fai clic su un ID operazione in esecuzione. Viene visualizzata la pagina Dettagli operazione a lunga esecuzione. La pagina mostra le seguenti informazioni:

    • L'avanzamento dell'LRO
    • I dettagli dell'operazione a lunga esecuzione, ad esempio l'ID operazione e il metodo che ha richiamato l'operazione a lunga esecuzione
    • Un sottoinsieme di voci di log

gcloud

Supponiamo che tu riceva la seguente risposta dopo aver chiamato gcloud healthcare dicom-stores deidentify:

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...

La risposta mostra che l'API Cloud Healthcare ha creato un'operazione LRO con un ID operazione. Puoi anche recuperare l'ID operazione elencando le operazioni di database a lunga esecuzione. Il comando continua a essere eseguito fino al termine, dopodiché visualizza quanto segue:

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...done
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID

Per visualizzare i dettagli dell'LRO, esegui il comando gcloud healthcare operations describe.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • DATASET_ID: l'ID set di dati
  • LOCATION: la posizione del set di dati
  • OPERATION_ID: l'ID restituito dall'operazione a lunga esecuzione

Esegui il seguente comando:

Linux, macOS o Cloud Shell

gcloud healthcare operations describe OPERATION_ID \
    --project=PROJECT_ID \
    --dataset=DATASET_ID \
    --location=LOCATION

Windows (PowerShell)

gcloud healthcare operations describe OPERATION_ID `
    --project=PROJECT_ID `
    --dataset=DATASET_ID `
    --location=LOCATION

Windows (cmd.exe)

gcloud healthcare operations describe OPERATION_ID ^
    --project=PROJECT_ID ^
    --dataset=DATASET_ID ^
    --location=LOCATION

Dovresti ricevere una risposta simile alla seguente:

Risposta

done: true
// If there were any errors, an `error` field displays instead of a `response` field.
// See Troubleshooting long-running operations for a list of response codes.
error: ERROR
  code: ERROR_CODE
  message: DESCRIPTION
metadata:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata'
  apiMethodName: 'google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore'
  counter:
    success: 'SUCCESS_COUNT'
    // If there were any failures, they display in the `failure` field.
    failure: 'FAILURE_COUNT'
  createTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  endTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  logsUrl: https://console.cloud.google.com/CLOUD_LOGGING_URL
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID
// The `response` field only displays if there were no errors.
response:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary'

REST

Supponiamo che tu riceva la seguente risposta dopo aver chiamato projects.locations.datasets.dicomStores.deidentify:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

Il valore name nella risposta indica che l'API Cloud Healthcare ha creato un'operazione a lunga esecuzione denominata projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID. Puoi anche recuperare il nome dell'LRO elencando gli LRO.

Per ottenere lo stato dell'LRO, utilizza il metodo projects.locations.datasets.operations.get. Per eseguire il polling di un'operazione LRO, chiama ripetutamente il metodo projects.locations.datasets.operations.get fino al termine dell'operazione. Utilizza un backoff tra ogni richiesta di polling, ad esempio 10 secondi.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • DATASET_ID: l'ID set di dati
  • LOCATION: la posizione del set di dati
  • OPERATION_ID: l'ID restituito dall'operazione a lunga esecuzione

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Esegui questo comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/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://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

Explorer API

Apri la pagina di riferimento del metodo. Il riquadro Esplora API si apre sul lato destro della pagina. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

L'output è il seguente. Quando la risposta contiene "done": true, l'operazione a lunga esecuzione è terminata.

LRO delle schede

Gli esempi riportati di seguito mostrano come elencare gli oggetti LRO in un set di dati.

Console

Per visualizzare un elenco di tutte le entità LRO in un set di dati nella console Google Cloud, completa i seguenti passaggi:

  1. Nella console Google Cloud, vai alla pagina Set di dati.

    Vai a Set di dati

  2. Fai clic sul nome del set di dati contenente l'ODM che vuoi visualizzare.

  3. Fai clic su Operazioni.

Viene visualizzato un elenco di oggetti LRO nel set di dati e il relativo stato. Per visualizzare i log degli errori in Cloud Logging, fai clic sull'icona per visualizzare ulteriori informazioni nell'ultima colonna, quindi fai clic su Visualizza dettagli in Cloud Logging. Per ulteriori informazioni, consulta Visualizzazione dei log degli errori in Cloud Logging.

gcloud

Per elencare le entità LRO in un set di dati, esegui il comando gcloud healthcare operations list.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • DATASET_ID: l'ID set di dati
  • LOCATION: la posizione del set di dati

Esegui il seguente comando:

Linux, macOS o Cloud Shell

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows (PowerShell)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows (cmd.exe)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Dovresti ricevere una risposta simile alla seguente:

Risposta

ID             LOCATION     DONE
OPERATION_ID   LOCATION {TRUE|FALSE}
...

REST

Per elencare gli oggetti LRO in un set di dati, utilizza il metodo projects.locations.datasets.operations.get.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • DATASET_ID: l'ID set di dati
  • LOCATION: la posizione del set di dati

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Esegui questo comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations"

PowerShell

Esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations" | Select-Object -Expand Content

Explorer API

Apri la pagina di riferimento del metodo. Il riquadro Esplora API si apre sul lato destro della pagina. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

Dovresti ricevere una risposta JSON simile alla seguente:

Annullamento di un LRO

Gli esempi riportati di seguito mostrano come annullare un LRO in un set di dati.

Console

Per annullare un LRO nella console Google Cloud, completa i seguenti passaggi:

  1. Nella console Google Cloud, vai alla pagina Set di dati.

    Vai a Set di dati

  2. Fai clic sul nome del set di dati contenente l'ODM che vuoi visualizzare.

  3. Fai clic su Operazioni.

  4. Nella stessa riga dell'operazione LRO che vuoi annullare, apri l'elenco Azioni e fai clic su Interrompi operazione.

REST

Per annullare un'LRO, utilizza il metodo projects.locations.datasets.operations.cancel.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • DATASET_ID: l'ID set di dati
  • LOCATION: la posizione del set di dati
  • OPERATION_ID: l'ID restituito dall'operazione a lunga esecuzione

Per inviare la richiesta, scegli una delle seguenti 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://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/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://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID:cancel" | Select-Object -Expand Content

Explorer API

Apri la pagina di riferimento del metodo. Il riquadro Esplora API si apre sul lato destro della pagina. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

Dovresti ricevere una risposta JSON simile alla seguente:

Per visualizzare lo stato della richiesta di annullamento, utilizza il metodo projects.locations.datasets.operations.get.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • DATASET_ID: l'ID set di dati
  • LOCATION: la posizione del set di dati
  • OPERATION_ID: l'ID restituito dall'operazione a lunga esecuzione

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Esegui questo comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/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://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

Explorer API

Apri la pagina di riferimento del metodo. Il riquadro Esplora API si apre sul lato destro della pagina. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

Dovresti ricevere una risposta JSON simile alla seguente:

Annullamento di più LRO

Per annullare più richieste di eliminazione, completa i seguenti passaggi:

  1. Chiama il metodo operations.list per ottenere i nomi delle operazioni in un set di dati.
  2. Chiama il metodo operations.cancel su ogni operazione.

Google fornisce uno script Python che puoi utilizzare per annullare tutte le operazioni per un determinato set di dati.

Risoluzione dei problemi relativi alle LRO

Quando un LRO non va a buon fine, la sua risposta include un codice di errore canonico di Google Cloud. La tabella seguente fornisce una spiegazione della causa di ciascun codice e un consiglio su come gestirlo. Per molti errori, l'azione consigliata è riprovare a effettuare la richiesta utilizzando il backoff esponenziale. Per informazioni su come implementare il backoff esponenziale nell'API Cloud Healthcare, consulta Riprovare le richieste non riuscite.

Codice Enum Descrizione Azione consigliata
1 CANCELLED L'operazione è stata annullata, in genere dal chiamante. Se vuoi, esegui di nuovo l'operazione.
2 UNKNOWN Questo errore potrebbe essere restituito quando un valore Status ricevuto da un altro spazio indirizzi appartiene a uno spazio di errore non noto in questo spazio indirizzi. Se l'errore di un'API non restituisce informazioni sufficienti, l'errore potrebbe essere convertito in questo errore. Riprova con il backoff esponenziale.
3 INVALID_ARGUMENT Il client ha specificato un argomento non valido. Questo errore è diverso da FAILED_PRECONDITION. INVALID_ARGUMENT indica gli argomenti problematici indipendentemente dallo stato del sistema, ad esempio un nome file con formato non corretto. Non riprovare senza risolvere il problema.
4 DEADLINE_EXCEEDED La scadenza è scaduta prima del completamento dell'operazione. Per le operazioni che modificano lo stato del sistema, questo errore potrebbe essere restituito anche se l'operazione è stata completata correttamente. Ad esempio, una risposta positiva da un server potrebbe aver subito un ritardo sufficientemente lungo da far scadere la scadenza. Riprova con il backoff esponenziale.
5 NOT_FOUND Alcune entità richieste, ad esempio una risorsa FHIR, non sono state trovate. Non riprovare senza risolvere il problema.
6 ALREADY_EXISTS L'entità che un client ha tentato di creare, ad esempio un'istanza DICOM, esiste già. Non riprovare senza risolvere il problema.
7 PERMISSION_DENIED Il chiamante non dispone dell'autorizzazione per eseguire l'operazione specificata. Questo codice di errore non implica che la richiesta sia valida o che l'entità richiesta esista o soddisfi altri prerequisiti. Non riprovare senza risolvere il problema.
8 RESOURCE_EXHAUSTED Una risorsa è stata esaurita, ad esempio una quota per progetto. Per le azioni consigliate, consulta le best practice per la gestione delle quote. Riprova con il backoff esponenziale. La quota potrebbe diventare disponibile nel tempo.
9 FAILED_PRECONDITION L'operazione è stata rifiutata perché il sistema non è nello stato richiesto per l'esecuzione dell'operazione. Ad esempio, la directory da eliminare non è vuota o un'operazione rmdir viene applicata a un elemento diverso da una directory. Non riprovare senza risolvere il problema.
10 ABORTED L'operazione è stata interrotta, in genere a causa di un problema di concorrenza, ad esempio un errore di controllo del sequenziatore o l'interruzione della transazione. Riprova con il backoff esponenziale.
11 OUT_OF_RANGE È stato tentato di eseguire l'operazione oltre l'intervallo valido, ad esempio la ricerca o la lettura oltre il fine file. A differenza di INVALID_ARGUMENT, questo errore indica un problema che potrebbe essere risolto se lo stato del sistema cambia. Non riprovare senza risolvere il problema.
12 UNIMPLEMENTED L'operazione non è implementata o non è supportata/abilitata nell'API Cloud Healthcare. Non riprovare.
13 INTERNAL Errori interni. Indica che si è verificato un errore imprevisto durante l'elaborazione nel sistema sottostante. Riprova con il backoff esponenziale.
14 UNAVAILABLE L'API Cloud Healthcare non è al momento disponibile. Molto probabilmente si tratta di una condizione temporanea, che può essere corretta riprovando con un backoff. Tieni presente che non è sempre sicuro riprovare le operazioni non idempotenti. Riprova con il backoff esponenziale.
15 DATA_LOSS Perdita di dati non recuperabili o danneggiamento dei dati. Rivolgiti al tuo amministratore di sistema. L'amministratore di sistema potrebbe voler contattare un rappresentante dell'assistenza se si è verificata una perdita o una corruzione dei dati.
16 UNAUTHENTICATED La richiesta non ha credenziali di autenticazione valide per l'operazione. Non riprovare senza risolvere il problema.