Questa pagina è stata tradotta dall'API Cloud Translation.

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 dell'API Cloud Healthcare aderiscono al 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.

Gli LRO vengono gestiti 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 del datastore 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 API Cloud Healthcare della 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 un LRO viene conservato per circa 30 giorni dopo il suo completamento, il che significa che non puoi visualizzare o elencare un LRO dopo questo punto.

Metodi che restituiscono un LRO

I seguenti metodi restituiscono un LRO.

Metodi di gestione del consenso:

projects.locations.datasets.consentStores.queryAccessibleData

Metodi del set di dati:

Metodi DICOM:

Metodi FHIR:

Metodi HL7v2:

Ottenere dettagli su un LRO

Gli esempi riportati di seguito mostrano come ottenere dettagli su un LRO.

La versione dell'API Cloud Healthcare mostrata nella risposta quando si ricevono dettagli su un LRO è la stessa della versione dell'API 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 dell'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 che vuoi visualizzare.
Fai clic su Operazioni.
Per visualizzare i log degli errori per l'operazione in Cloud Logging, fai clic su Azioni e quindi su Visualizza dettagli in Cloud Logging. Per saperne di più, 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 dell'operazione di lunga durata. La pagina mostra le seguenti informazioni:
- I progressi dell'LRO
- I dettagli dell'LRO, come l'ID operazione e il metodo che ha richiamato l'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 elenca 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 i dettagli dell'LRO, esegui il comando gcloud healthcare operations describe.

Prima di utilizzare qualsiasi dato di comando riportato di seguito, 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

Esegui questo 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 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 anche recuperare il nome LRO elencando gli LRO.

Per visualizzare lo stato dell'LRO, utilizza il metodo projects.locations.datasets.operations.get. Per eseguire il polling di un LRO, chiama ripetutamente il metodo projects.locations.datasets.operations.get fino al termine dell'operazione. Usa 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:

curl

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti fa 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

Nota: il comando seguente 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 . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Compila tutti 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 degli LRO

Gli esempi riportati di seguito 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 questi 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 che vuoi 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 su Visualizza dettagli in Cloud Logging. Per saperne di più, 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 qualsiasi dato di comando riportato di seguito, effettua le seguenti sostituzioni:

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

Esegui questo 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 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:

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

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

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 che vuoi 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 un 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:

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

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:

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

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 tabella seguente fornisce una spiegazione della causa per ogni codice e un suggerimento per la gestione del codice. In caso di molti errori, l'azione consigliata è di riprovare a eseguire la richiesta utilizzando il backoff esponenziale. Per informazioni su come implementare il backoff esponenziale nell'API Cloud Healthcare, consulta Ripetere le richieste non riuscite.

Codice	Enum	Descrizione	Azione consigliata
1	`CANCELLED`	L'operazione è stata annullata, generalmente 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 di indirizzi appartiene a uno spazio di errore che non è noto in questo spazio di 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 argomenti problematici indipendentemente dallo stato del sistema, come un nome di file non corretto.	Non riprovare senza risolvere il problema.
4	`DEADLINE_EXCEEDED`	La scadenza è scaduta 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 ritardata abbastanza a lungo prima della 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 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 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 oppure viene applicata un'operazione `rmdir` a una directory diversa.	Non riprovare senza risolvere il problema.
10	`ABORTED`	L'operazione è stata interrotta, in genere a causa di un problema di contemporaneità come un errore del controllo del sequencer o dell'interruzione di una transazione.	Riprova con il backoff esponenziale.
11	`OUT_OF_RANGE`	È stato tentato l'operazione una volta superato l'intervallo valido, ad esempio la ricerca o la lettura oltre la fine del file. A differenza di `INVALID_ARGUMENT`, questo errore indica un problema che può 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 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 a eseguire operazioni non idempotenti.	Riprova con il backoff esponenziale.
15	`DATA_LOSS`	Perdita o danneggiamento di dati non recuperabili.	Rivolgiti al tuo amministratore di sistema. In caso di perdita o danneggiamento dei 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.