Umgang mit lang andauernden Vorgängen

Auf dieser Seite wird beschrieben, wie Sie den Lebenszyklus eines lang andauernden Vorgangs in der Cloud Healthcare API verwalten.

Wenn die Ausführung einer API-Methode sehr lange dauert, kann ein Operation an den Client zurückgegeben werden. Der Client kann die Schnittstelle Operation verwenden, um den Status der API-Methode asynchron durch Abfragen des Vorgangs abzurufen. LROs in der Cloud Healthcare API halten sich an das Google Cloud LRO-Designmuster.

Die Cloud Healthcare API erstellt LROs für mehrere Methoden wie projects.locations.datasets.fhirStores.import. Wenn projects.locations.datasets.fhirStores.import aufgerufen wird, erstellt die Cloud Healthcare API einen LRO, um den Importstatus zu verfolgen. Der LRO hat eine eindeutige Kennung, mit der Sie den Status des LRO ansehen können.

LROs werden auf Dataset-Ebene verwaltet. Wenn Sie eine Methode aufrufen, die einen LRO wie projects.locations.datasets.fhirStores.import zurückgibt, können Sie den Status des LRO ansehen. Dazu senden Sie eine Anfrage mit der LRO-ID an das übergeordnete Dataset des FHIR-Speichers, in dem der Import stattfindet.

Neben der REST API generieren die folgenden Quellen Vorgänge mit langer Ausführungszeit, wenn Sie die unter Methoden, die einen LRO zurückgeben aufgeführten Methoden aufrufen, aufrufen:

Sie können Ihre Cloud Healthcare API-LROs über die Google Cloud Console, die Google Cloud CLI oder die REST API verwalten.

Der Datensatz eines LRO wird für etwa 30 Tage gespeichert, nachdem der LRO abgeschlossen wurde. Dies bedeutet, dass Sie nach diesem Zeitpunkt den LRO nicht mehr aufrufen oder auflisten können.

Methoden, die einen LRO zurückgeben

Die folgenden Methoden geben einen LRO zurück.

Methoden zur Einwilligungsverwaltung:

Dataset-Methoden:

DICOM-Methoden:

FHIR-Methoden:

HL7v2-Methoden:

Details zu einem LRO abrufen

Die folgenden Beispiele zeigen, wie Sie Details zu einem LRO erhalten.

Die Version der Cloud Healthcare API, die beim Abrufen von Details zu einem LRO in der Antwort angezeigt wird, stimmt mit der API-Version der Methode überein, die den LRO initiiert hat.

Console

Nachdem Sie eine Methode mithilfe der gcloud CLI oder der API aufgerufen haben, die eine LRO zurückgibt, können Sie in der Google Cloud Console Details zur LRO anzeigen.

  1. Rufen Sie in der Google Cloud Console die Seite Datasets auf.

    Zu „Datasets“

  2. Klicken Sie auf den Namen des Datasets mit dem LRO, den Sie ansehen möchten.

  3. Klicken Sie auf Vorgänge.

  4. Zum Aufrufen von Fehlerlogs für den Vorgang in Cloud Logging klicken Sie auf Aktionen und dann auf Details in Cloud Logging anzeigen. Weitere Informationen finden Sie unter Fehlerlogs in Cloud Logging ansehen.

  5. Klicken Sie auf die ID eines Vorgangs, der gerade ausgeführt wird, um weitere Details dazu aufzurufen. Die Seite Details zu Vorgängen mit langer Ausführungszeit wird angezeigt. Auf der Seite werden die folgenden Informationen angezeigt:

    • Der Fortschritt des LRO
    • Die Details des LRO, z. B. die Vorgangs-ID und die Methode, mit der der LRO aufgerufen wurde
    • Eine Teilmenge von Logeinträgen

gcloud

Angenommen, Sie erhalten nach dem Aufruf von gcloud healthcare dicom-stores deidentify die folgende Antwort:

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

Die Antwort zeigt, dass die Cloud Healthcare API einen LRO mit einer Vorgangs-ID erstellt hat. Sie können die Vorgangs-ID auch abrufen, indem Sie lange laufende Datenbankvorgänge auflisten. Der Befehl wird weiter ausgeführt, bis er abgeschlossen ist. Danach wird Folgendes ausgegeben:

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

Führen Sie den Befehl gcloud healthcare operations describe aus, um Details zum LRO abzurufen.

Bevor Sie die folgenden Befehlsdaten verwenden, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: die ID Ihres Google Cloud-Projekts
  • DATASET_ID: die Dataset-ID
  • LOCATION: der Standort des Datasets
  • OPERATION_ID: die ID, die vom Vorgang mit langer Ausführungszeit zurückgegeben wurde

Führen Sie dazu folgenden Befehl aus:

Linux, macOS oder 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

Sie sollten eine Antwort ähnlich der folgenden erhalten:

Antwort

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

Angenommen, Sie erhalten nach dem Aufruf von projects.locations.datasets.dicomStores.deidentify die folgende Antwort:

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

Der Wert name in der Antwort zeigt, dass die Cloud Healthcare API eine LRO mit dem Namen projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID erstellt hat. Sie können den Namen des LRO auch abrufen, indem Sie LROs auflisten.

Verwenden Sie die Methode projects.locations.datasets.operations.get, um den Status des LRO abzurufen. Wenn Sie einen LRO abfragen möchten, rufen Sie die Methode projects.locations.datasets.operations.get wiederholt auf, bis der Vorgang abgeschlossen ist. Verwenden Sie einen Backoff zwischen den Abfrageanfragen, z. B. 10 Sekunden.

Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: die ID Ihres Google Cloud-Projekts
  • DATASET_ID: die Dataset-ID
  • LOCATION: der Standort des Datasets
  • OPERATION_ID: die ID, die vom Vorgang mit langer Ausführungszeit zurückgegeben wurde

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Führen Sie folgenden Befehl aus:

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

Führen Sie folgenden Befehl aus:

$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

APIs Explorer

Öffnen Sie die Methodenreferenzseite. Der API Explorer wird rechts auf der Seite geöffnet. Sie können mit diesem Tool interagieren, um Anfragen zu senden. Füllen Sie die Pflichtfelder aus und klicken Sie auf Ausführen.

Die Ausgabe sieht so aus. Wenn die Antwort "done": true enthält, ist der Vorgang mit langer Ausführungszeit abgeschlossen.

LROs auflisten

Die folgenden Beispiele zeigen, wie die LROs in einem Dataset aufgelistet werden.

Console

So rufen Sie eine Liste aller LROs in einem Dataset in der Google Cloud Console auf:

  1. Rufen Sie in der Google Cloud Console die Seite Datasets auf.

    Zu „Datasets“

  2. Klicken Sie auf den Namen des Datasets mit dem LRO, den Sie ansehen möchten.

  3. Klicken Sie auf Vorgänge.

Eine Liste der LROs im Dataset und deren Status wird angezeigt. Zur Anzeige der Fehlerlogs in Cloud Logging klicken Sie in der letzten Spalte auf das Symbol für weitere Informationen und dann auf Details in Cloud Logging ansehen. Weitere Informationen finden Sie unter Fehlerlogs in Cloud Logging ansehen.

gcloud

Zum Auflisten der LROs in einem Dataset führen Sie den Befehl gcloud healthcare operations list aus.

Bevor Sie die folgenden Befehlsdaten verwenden, ersetzen Sie die folgenden Werte:

  • DATASET_ID ist die Dataset-ID
  • LOCATION ist der Standort des Datasets

Führen Sie dazu folgenden Befehl aus:

Linux, macOS oder 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

Sie sollten eine Antwort ähnlich der folgenden erhalten:

Antwort

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

REST

Verwenden Sie die Methode projects.locations.datasets.operations.get, um die LROs in einem Dataset aufzulisten.

Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: die ID Ihres Google Cloud-Projekts
  • DATASET_ID: die Dataset-ID
  • LOCATION ist der Standort des Datasets

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Führen Sie folgenden Befehl aus:

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

Führen Sie folgenden Befehl aus:

$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

APIs Explorer

Öffnen Sie die Methodenreferenzseite. Der API Explorer wird rechts auf der Seite geöffnet. Sie können mit diesem Tool interagieren, um Anfragen zu senden. Füllen Sie die Pflichtfelder aus und klicken Sie auf Ausführen.

Sie sollten in etwa folgende JSON-Antwort erhalten:

LRO abbrechen

Die folgenden Beispiele zeigen, wie ein LRO in einem Dataset abgebrochen wird.

Console

Führen Sie die folgenden Schritte aus, um einen LRO in der Google Cloud Console abzubrechen:

  1. Rufen Sie in der Google Cloud Console die Seite Datasets auf.

    Zu „Datasets“

  2. Klicken Sie auf den Namen des Datasets mit dem LRO, den Sie ansehen möchten.

  3. Klicken Sie auf Vorgänge.

  4. Öffnen Sie in derselben Zeile wie den LRO, den Sie abbrechen möchten, die Liste Actions (Aktionen) und klicken Sie auf Stop Operation (Vorgang beenden).

REST

Mit der Methode projects.locations.datasets.operations.cancel können Sie einen LRO abbrechen.

Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: die ID Ihres Google Cloud-Projekts
  • DATASET_ID: die Dataset-ID
  • LOCATION: der Standort des Datasets
  • OPERATION_ID: die ID, die vom Vorgang mit langer Ausführungszeit zurückgegeben wurde

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Führen Sie folgenden Befehl aus:

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

Führen Sie folgenden Befehl aus:

$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

APIs Explorer

Öffnen Sie die Methodenreferenzseite. Der API Explorer wird rechts auf der Seite geöffnet. Sie können mit diesem Tool interagieren, um Anfragen zu senden. Füllen Sie die Pflichtfelder aus und klicken Sie auf Ausführen.

Sie sollten in etwa folgende JSON-Antwort erhalten:

Den Status der Abbruchanfrage können Sie mit der Methode projects.locations.datasets.operations.get aufrufen.

Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:

  • PROJECT_ID: die ID Ihres Google Cloud-Projekts
  • DATASET_ID: die Dataset-ID
  • LOCATION: der Standort des Datasets
  • OPERATION_ID: die ID, die vom Vorgang mit langer Ausführungszeit zurückgegeben wurde

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Führen Sie folgenden Befehl aus:

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

Führen Sie folgenden Befehl aus:

$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

APIs Explorer

Öffnen Sie die Methodenreferenzseite. Der API Explorer wird rechts auf der Seite geöffnet. Sie können mit diesem Tool interagieren, um Anfragen zu senden. Füllen Sie die Pflichtfelder aus und klicken Sie auf Ausführen.

Sie sollten in etwa folgende JSON-Antwort erhalten:

Mehrere LROs abbrechen

Führen Sie die folgenden Schritte aus, um mehrere LROs abzubrechen:

  1. Rufen Sie die Methode operations.list auf, um die Namen der Vorgänge in einem Dataset abzurufen.
  2. Rufen Sie bei jedem Vorgang die Methode operations.cancel auf.

Google stellt ein Python-Skript bereit, mit dem Sie alle Vorgänge für ein bestimmtes Dataset abbrechen können.

Fehlerbehebung bei LROs

Wenn ein LRO fehlschlägt, enthält die Antwort einen kanonischen Google Cloud-Fehlercode. Die folgende Tabelle enthält eine Erläuterung der Ursachen für jeden Code und eine Empfehlung zum Umgang mit dem Code. Bei vielen Fehlern empfiehlt es sich, die Anfrage noch einmal mit exponentiellem Backoff zu senden. Informationen zum Implementieren des exponentiellen Backoffs in der Cloud Healthcare API finden Sie unter Fehlgeschlagene Anfragen wiederholen.

Code Enum Beschreibung Empfohlene Maßnahmen
1 CANCELLED Der Vorgang wurde abgebrochen, üblicherweise vom Aufrufer. Führen Sie den Vorgang bei Bedarf noch einmal aus.
2 UNKNOWN Dieser Fehler wird möglicherweise zurückgegeben, wenn ein Status-Wert, der von einem anderen Adressbereich empfangen wurde, zu einem Fehlerbereich gehört, der in diesem Adressbereich nicht bekannt ist. Wenn ein API-Fehler nicht genügend Informationen zurückgibt, wird der Fehler möglicherweise in diesen Fehler konvertiert. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
3 INVALID_ARGUMENT Der Client hat ein ungültiges Argument angegeben. Dieser Fehler unterscheidet sich von FAILED_PRECONDITION. INVALID_ARGUMENT gibt Argumente an, die ungeachtet des Systemstatus problematisch sind (z. B. ein ungültiger Dateiname). Versuchen Sie es nicht, ohne das Problem zu beheben.
4 DEADLINE_EXCEEDED Die Frist ist abgelaufen, bevor der Vorgang abgeschlossen werden konnte. Bei Vorgängen, die den Systemstatus ändern, wird dieser Fehler möglicherweise zurückgegeben, auch wenn der Vorgang erfolgreich abgeschlossen wurde. Zum Beispiel könnte eine erfolgreiche Antwort von einem Server so lange verzögert worden sein, dass die Frist abgelaufen ist. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
5 NOT_FOUND Eine angeforderte Entität, z. B. eine FHIR-Ressource, wurde nicht gefunden. Versuchen Sie es nicht, ohne das Problem zu beheben.
6 ALREADY_EXISTS Die Entität, die ein Client erstellen wollte, z. B. eine DICOM-Instanz, ist bereits vorhanden. Versuchen Sie es nicht, ohne das Problem zu beheben.
7 PERMISSION_DENIED Der Aufrufer ist nicht berechtigt, den angegebenen Vorgang auszuführen. Dieser Fehlercode bedeutet nicht, dass die Anfrage gültig ist oder die angeforderte Entität existiert oder andere Voraussetzungen erfüllt. Versuchen Sie es nicht, ohne das Problem zu beheben.
8 RESOURCE_EXHAUSTED Eine Ressource, z. B. ein Kontingent pro Projekt, ist erschöpft. Empfohlene Maßnahmen finden Sie unter Best Practices für die Kontingentverwaltung. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Das Kontingent kann im Laufe der Zeit verfügbar werden.
9 FAILED_PRECONDITION Der Vorgang wurde abgelehnt, weil der Systemzustand nicht für die Ausführung des Vorgangs geeignet ist. Beispiel: Das zu löschende Verzeichnis ist nicht leer oder ein rmdir-Vorgang wird auf ein Nicht-Verzeichnis angewendet. Versuchen Sie es nicht, ohne das Problem zu beheben.
10 ABORTED Der Vorgang wurde abgebrochen, in der Regel aufgrund eines Parallelitätsproblems wie einer fehlgeschlagenen Sequencer-Überprüfung oder einer abgebrochenen Transaktion. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
11 OUT_OF_RANGE Beim Vorgang wurde versucht, den gültigen Bereich zu überschreiten, z. B. bei einer Such- oder Leseaktion hinter dem Dateiende. Im Gegensatz zu INVALID_ARGUMENT zeigt dieser Fehler ein Problem an, das behoben werden kann, wenn sich der Systemstatus ändert. Versuchen Sie es nicht, ohne das Problem zu beheben.
12 UNIMPLEMENTED Der Vorgang ist nicht implementiert oder wird in der Cloud Healthcare API nicht unterstützt bzw. aktiviert. Nicht wiederholen.
13 INTERNAL Interne Fehler. Dies weist darauf hin, dass bei der Verarbeitung des zugrunde liegenden Systems ein unerwarteter Fehler aufgetreten ist. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
14 UNAVAILABLE Die Cloud Healthcare API ist derzeit nicht verfügbar. Dies ist höchstwahrscheinlich ein vorübergehender Zustand, der durch Wiederholen mit einem Backoff korrigiert werden kann. Es ist nicht immer sicher, nicht idempotente Vorgänge zu wiederholen. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
15 DATA_LOSS Dauerhafter Datenverlust oder Datenkorruption. Wenden Sie sich an Ihren Systemadministrator. Der Systemadministrator möchte sich bei Datenverlust oder -beschädigung an einen Supportmitarbeiter wenden.
16 UNAUTHENTICATED Die Anfrage enthält keine gültigen Authentifizierungsdaten für diesen Vorgang. Versuchen Sie es nicht, ohne das Problem zu beheben.