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, 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 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 usare per visualizzarne lo stato.

Gli LRO vengono gestiti a livello del set di dati. Se stai chiamando 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 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 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 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 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

I seguenti esempi mostrano come ottenere dettagli su un LRO.

La versione dell'API Cloud Healthcare mostrata nella risposta quando si ottengono dettagli su un LRO è la stessa 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 poi su Visualizza i 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 operazione a lunga esecuzione. 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 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 di comando riportati 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 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 degli LRO elencando gli LRO.

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

arricciatura

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 consente di accedere automaticamente all'interfaccia a riga di comando 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 seguente comando 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 . 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. Il riquadro Explorer API si apre sul lato destro della pagina. 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

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

Viene visualizzato 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 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 di comando riportati di seguito, effettua le seguenti sostituzioni:

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

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

arricciatura

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

I seguenti esempi 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 Arresta 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:

arricciatura

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:

arricciatura

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 per 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 ogni codice e un suggerimento su come gestire il codice. Per molti errori, l'azione consigliata è provare a ripetere 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, 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 di indirizzi appartiene a uno spazio di errore non noto in questo spazio degli indirizzi. Se l'errore di un'API non restituisce informazioni sufficienti, l'errore potrebbe essere convertito in questo errore.	Riprova con 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, come un nome di file non corretto.	Non riprovare senza aver risolto 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 ritardata abbastanza a lungo da far scadere la scadenza.	Riprova con backoff esponenziale.
5	`NOT_FOUND`	Impossibile trovare alcune entità richieste, ad esempio una risorsa FHIR.	Non riprovare senza aver risolto il problema.
6	`ALREADY_EXISTS`	L'entità che un client ha tentato di creare, ad esempio un'istanza DICOM, esiste già.	Non riprovare senza aver risolto il problema.
7	`PERMISSION_DENIED`	Il chiamante non è autorizzato a 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 aver risolto 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 backoff esponenziale. La quota potrebbe diventare disponibile nel tempo.
9	`FAILED_PRECONDITION`	L'operazione è stata rifiutata perché il sistema non è nello stato necessario per l'esecuzione. Ad esempio, la directory da eliminare non è vuota o viene applicata un'operazione `rmdir` a una non directory.	Non riprovare senza aver risolto il problema.
10	`ABORTED`	L'operazione è stata interrotta, generalmente a causa di un problema di contemporaneità, come un errore del controllo del sequenziatore o l'interruzione della transazione.	Riprova con backoff esponenziale.
11	`OUT_OF_RANGE`	È stato effettuato un tentativo di oltre l'intervallo valido, ad esempio è stato eseguito un tentativo di ricerca o di 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 aver risolto 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 backoff esponenziale.
14	`UNAVAILABLE`	L'API Cloud Healthcare al momento non è disponibile. Molto probabilmente si tratta di una condizione transitoria, che può essere corretta riprovando con un backoff. Tieni presente che non è sempre sicuro ritentare le operazioni non idempotenti.	Riprova con backoff esponenziale.
15	`DATA_LOSS`	Perdita o danneggiamento dei 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 aver risolto il problema.