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 lungo termine (LRO) dell'API Cloud Healthcare.

Quando un metodo API può richiedere molto tempo per essere completato, può restituire un Operation al cliente. Il client può utilizzare l'interfaccia Operation per recuperare il stato del metodo API in modo asincrono eseguendo il polling dell'operazione. LRO nel L'API Cloud Healthcare aderisce 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, il parametro 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 che restituisce un LRO, come projects.locations.datasets.fhirStores.import, puoi visualizzare lo stato dell'LRO inviando una richiesta contenente ID LRO al set di dati padre del datastore FHIR in cui è in corso l'importazione.

Oltre all'API REST, le seguenti origini generano dati operazioni 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 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:

projects.locations.datasets.consentStores.queryAccessibleData

Metodi del set di dati:

Metodi DICOM:

Metodi FHIR:

Metodi HL7v2:

Visualizzare i dettagli di un'operazione 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 cosa 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 relativi dettagli 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 relativi all'operazione in Cloud Logging, fai clic su Azioni e poi 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 operazione a lunga esecuzione. La pagina mostra le seguenti informazioni:
- I progressi dell'LRO
- I dettagli dell'LRO, ad esempio 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'operazione LRO con un ID operazione. Puoi anche recuperare l'ID operazione elenca le operazioni di database a lunga esecuzione. L'esecuzione del comando continua fino al termine, dopodiché il codice 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 sull'LRO, esegui 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 del set di dati
LOCATION: la posizione del set di dati
OPERATION_ID: l'ID restituito dall'operazione a lunga esecuzione

Esegui la persone che seguo :

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 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'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 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 a l'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 di Google. 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

Explorer API

Apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Esplora 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.

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: ...,
        ...
      }
    ]
  }
}

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 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 che vuoi visualizzare.
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, vedi Visualizzazione dei log degli errori in Cloud Logging.

gcloud

Per elencare gli LRO in un set di dati, esegui 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 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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI 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" | Select-Object -Expand Content

Explorer API

Apri l'app 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.

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: ...,
            ...
          }
        ]
      }
    },
    ...
  ]
}

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:

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

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

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 l'app pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Esplora API. Puoi interagire con questo strumento per inviare richieste. Compila tutti i campi obbligatori e fai clic su Esegui.

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 operations.list per ottenere i nomi delle operazioni in un set di dati.
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 richieste 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 consiglio per come gestire il codice. 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 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 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 non di 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 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. 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 ritentare 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. In caso di perdita o danneggiamento dei dati, l'amministratore di sistema potrebbe voler contattare un rappresentante dell'assistenza.
16	`UNAUTHENTICATED`	La richiesta non ha credenziali di autenticazione valide per l'operazione.	Non riprovare senza risolvere il problema.