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 un metodo API può richiedere molto tempo per essere completato, può restituire un Operation al client. Il client può utilizzare l'interfaccia Operation per recuperare lo stato del metodo API in modo asincrono eseguendo il polling dell'operazione. Gli LRO nell'API Cloud Healthcare rispettano il pattern di progettazione degli 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 visualizzarne lo stato.

Gli LRO vengono gestiti a livello del set di dati. Se chiami un metodo che restituisce un LRO, come 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 viene eseguita 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:

Google Cloud CLI
La pagina dell'API Cloud Healthcare nella console Google Cloud

Puoi gestire gli LRO dell'API Cloud Healthcare utilizzando la console Google Cloud, Google Cloud CLI o l'API REST.

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

Metodi che restituiscono una LRO

I seguenti metodi restituiscono un LRO.

Metodi di gestione del consenso:

projects.locations.datasets.consentStores.queryAccessibleData

Metodi per set di dati:

Metodi DICOM:

Metodi FHIR:

Metodi HL7v2:

Ottenere dettagli su una LRO

Gli esempi riportati di seguito mostrano come ottenere i dettagli di una LRO.

La versione dell'API Cloud Healthcare mostrata nella risposta quando si ottengono dettagli su un LRO è la stessa del metodo che ha avviato l'LRO.

Console

Dopo aver chiamato un metodo utilizzando gcloud CLI o l'API che restituisce un LRO, puoi visualizzare i dettagli relativi all'LRO nella console Google Cloud.

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

Vai a Set di dati
Fai clic sul nome del set di dati contenente l'LRO da visualizzare.
Fai clic su Operazioni.
Per visualizzare i log degli errori per l'operazione in Cloud Logging, fai clic su Azioni, quindi fai clic su Visualizza dettagli in Cloud Logging. Per maggiori informazioni, consulta Visualizzazione dei log degli errori in Cloud Logging.
Per visualizzare ulteriori dettagli sull'operazione, fai clic su un ID operazione in esecuzione. Viene visualizzata la pagina Dettagli operazione di lunga durata. La pagina mostra le seguenti informazioni:
- I progressi dell'LRO
- I dettagli della LRO, come l'ID operazione e il metodo che ha richiamato la LRO
- Un sottoinsieme di voci di log

gcloud

Supponiamo di ricevere 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 LRO con un ID operazione. Puoi anche recuperare l'ID operazione elencare le operazioni di database a lunga esecuzione. Il comando continua a essere eseguito fino al termine, dopodiché restituisce 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 ottenere dettagli sull'LRO, esegui il comando gcloud healthcare operations describe.

Prima di utilizzare uno qualsiasi dei dati del comando riportati di seguito, apporta le seguenti sostituzioni:

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

Esegui questo comando seguente:

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 di ricevere 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 LRO denominato projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID. Puoi recuperare il nome dell'LRO anche elencando gli LRO.

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

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

PROJECT_ID: l'ID del tuo progetto Google Cloud
DATASET_ID: l'ID del 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:

arricciare

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando di gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti permette di accedere automaticamente all'interfaccia a riga di comando di gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

Esplora API

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

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

Risposta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
    "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"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
  },
  // 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": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

Elenco delle LRO

I seguenti esempi mostrano come elencare gli LRO in un set di dati.

Console

Per visualizzare un elenco di tutti gli LRO in un set di dati nella console Google Cloud, completa i seguenti passaggi:

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

Vai a Set di dati
Fai clic sul nome del set di dati contenente l'LRO da visualizzare.
Fai clic su Operazioni.

Un elenco di LRO nel set di dati con il relativo stato. Per visualizzare i log degli errori in Cloud Logging, fai clic sull'icona Ulteriori informazioni nell'ultima colonna, quindi fai clic su Visualizza dettagli in Cloud Logging. Per maggiori informazioni, consulta Visualizzazione dei log degli errori in Cloud Logging.

gcloud

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

Prima di utilizzare uno qualsiasi dei dati del comando riportati di seguito, apporta le seguenti sostituzioni:

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

Esegui questo comando seguente:

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 LRO in un set di dati, utilizza il metodo projects.locations.datasets.operations.get.

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

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

arricciare

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

Esplora API

Dovresti ricevere una risposta JSON simile alla seguente:

Risposta

{
  "operations": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
        "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
        "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"
        "counter": {
          "success": "SUCCESS_COUNT",
          // If there were any failures, they display in the `failure` field.
          "failure": "FAILURE_COUNT"
        }
      },
      "done": true,
      // The `response` field only displays if there were no errors.
      "response": {
        "@type": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
      },
      // 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": {
        "code": ERROR_CODE,
        "message": "DESCRIPTION",
        "details": [
          {
            "@type": "...",
            FIELD1: ...,
            ...
          }
        ]
      }
    },
    ...
  ]
}

Annullare una LRO

I seguenti esempi mostrano come annullare un LRO in un set di dati.

Console

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

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

Vai a Set di dati
Fai clic sul nome del set di dati contenente l'LRO da visualizzare.
Fai clic su Operazioni.
Nella stessa riga dell'LRO da annullare, apri l'elenco Azioni e fai clic su Interrompi operazione.

REST

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

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

PROJECT_ID: l'ID del tuo progetto Google Cloud
DATASET_ID: l'ID del 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:

arricciare

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

Esplora API

Dovresti ricevere una risposta JSON simile alla seguente:

Risposta

{}

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

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

PROJECT_ID: l'ID del tuo progetto Google Cloud
DATASET_ID: l'ID del 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:

arricciare

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

Esplora API

Dovresti ricevere una risposta JSON simile alla seguente:

Risposta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "cancelRequested": true,
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  "error": {
    "code": 1,
    "message": "Operation cancelled by user. Any progress already completed by the operation will not be reverted."
  }
}

Annullamento di più LRO

Per annullare più LRO, completa i seguenti passaggi:

Chiama il metodo operations.list per ottenere i nomi delle operazioni in un set di dati.
Chiama il metodo operations.cancel a 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 agli LRO

Quando un LRO non va a buon fine, la sua risposta include un codice di errore canonico di Google Cloud. La seguente tabella fornisce una spiegazione della causa di ciascun codice e un suggerimento su come gestire il codice. Per molti errori, l'azione consigliata è riprovare 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 degli indirizzi appartiene a uno spazio di errore non noto in questo spazio degli indirizzi. Se un errore dell'API non restituisce informazioni sufficienti, l'errore potrebbe essere convertito in questo errore.	Riprova con un 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 di file non corretto.	Non riprovare senza risolvere il problema.
4	`DEADLINE_EXCEEDED`	Il termine è scaduto prima del completamento dell'operazione. Per le operazioni che cambiano lo stato del sistema, questo errore potrebbe essere restituito anche se l'operazione è stata completata correttamente. Ad esempio, una risposta corretta da un server potrebbe essere stata ritardata abbastanza a lungo da far scadere la scadenza.	Riprova con un 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 altre precondizioni.	Non riprovare senza risolvere il problema.
8	`RESOURCE_EXHAUSTED`	Alcune risorse sono esaurite, ad esempio una quota per progetto. Per le azioni consigliate, consulta le best practice per la gestione della quota.	Riprova con un backoff esponenziale. La quota potrebbe diventare disponibile nel tempo.
9	`FAILED_PRECONDITION`	L'operazione è stata rifiutata perché il sistema non si trova nello stato richiesto per l'esecuzione. Ad esempio, la directory da eliminare non è vuota oppure viene applicata un'operazione `rmdir` a una directory non directory.	Non riprovare senza risolvere il problema.
10	`ABORTED`	L'operazione è stata interrotta, generalmente a causa di un problema di contemporaneità, come un errore del controllo della sequenziatore o l'interruzione della transazione.	Riprova con un backoff esponenziale.
11	`OUT_OF_RANGE`	È stato effettuato un tentativo di operazione oltre l'intervallo valido, ad esempio la ricerca o la lettura oltre la fine del file. A differenza del criterio `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. Questo indica che si è verificato un errore imprevisto durante l'elaborazione sul sistema sottostante.	Riprova con un backoff esponenziale.
14	`UNAVAILABLE`	L'API Cloud Healthcare al momento non è disponibile. Si tratta molto probabilmente di una condizione temporanea, che può essere corretta riprovando con un backoff. Tieni presente che non è sempre sicuro ritentare le operazioni non idempotenti.	Riprova con un backoff esponenziale.
15	`DATA_LOSS`	Perdita o danneggiamento di dati non recuperabili.	Rivolgiti al tuo amministratore di sistema. In caso di perdita o danneggiamento di dati, l'amministratore di sistema potrebbe voler contattare un rappresentante dell'assistenza.
16	`UNAUTHENTICATED`	La richiesta non dispone di credenziali di autenticazione valide per l'operazione.	Non riprovare senza risolvere il problema.