Lange laufende Vorgänge verwalten

Auf dieser Seite wird beschrieben, wie Sie den Lebenszyklus eines lang laufenden Vorgangs (Long-Running Operation, LRO) der Cloud Healthcare API verwalten.

Wenn die Ausführung einer API-Methode sehr lange dauert, kann eine Operation an die Kundschaft. Der Client kann den Status der API-Methode asynchron abrufen, indem er den Vorgang abfragt. LROs in der Cloud Healthcare API entsprechen dem Google Cloud-Designmuster für LROs.

Die Cloud Healthcare API erstellt LROs für mehrere wie z. B. 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 eine eindeutige Kennung hat, mit der Sie den Status des LRO abrufen können.

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

Neben der REST API generieren die folgenden Quellen lang andauernde -Vorgänge, wenn Sie die unter Methoden, die einen LRO zurückgeben aufgeführten Methoden 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

Bei den folgenden Methoden wird ein LRO zurückgegeben.

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 in der Antwort beim Abrufen von Details zu einem LRO 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, das den LRO enthält, 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 der LRO
    • Details zum LRO, z. B. die Vorgangs-ID und die Methode, mit der der LRO aufgerufen wurde
    • Eine Teilmenge der Logeinträge

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 so lange ausgeführt, bis er abgeschlossen ist. Dann gibt er Folgendes aus:

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.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • 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 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 der LROs auch abrufen, indem Sie LROs auflisten.

Mit der Methode projects.locations.datasets.operations.get können Sie den Status des LRO abrufen. Rufen Sie zum Abfragen eines LRO wiederholt die Methode projects.locations.datasets.operations.get auf. bis der Vorgang abgeschlossen ist. Verwenden Sie einen Backoff zwischen den Abfrageanfragen, z. B. 10 Sekunden.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • 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 das 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, wird der lang andauernden Vorgang abgeschlossen ist.

LROs auflisten

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

Console

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

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

    Zu Datasets

  2. Klicken Sie auf den Namen des Datasets, das den LRO enthält, 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.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

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

Führen Sie 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.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • 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 das 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 eine JSON-Antwort ähnlich wie diese erhalten:

LRO abbrechen

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

Console

So kündigen Sie eine LRO in der Google Cloud Console:

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

    Zu Datasets

  2. Klicken Sie auf den Namen des Datasets mit dem Vorgang mit langer Ausführungszeit, den Sie anzeigen möchten.

  3. Klicken Sie auf Vorgänge.

  4. Öffnen Sie in der Zeile mit dem LRO, den Sie abbrechen möchten, die Liste Aktionen und klicken Sie auf Vorgang beenden.

REST

Verwenden Sie zum Abbrechen eines LRO die Methode projects.locations.datasets.operations.cancel .

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • 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 eine JSON-Antwort ähnlich wie diese erhalten:

Verwenden Sie die Methode projects.locations.datasets.operations.get, um den Status der Stornierungsanfrage aufzurufen.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • 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 das 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 eine JSON-Antwort ähnlich wie diese erhalten:

Mehrere LROs abbrechen

So brechen Sie mehrere LROs ab:

  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-Script bereit, mit dem Sie alle Vorgänge für einen bestimmten Datensatz abbrechen können.

Fehlerbehebung bei LROs

Wenn ein LRO fehlschlägt, enthält seine Antwort einen kanonischen Google Cloud-Fehlercode. In der folgenden Tabelle finden Sie eine Erklärung der Ursache für jeden Code und eine Empfehlung für wie mit dem Code umgegangen wird. Bei vielen Fehlern empfiehlt es sich, das mit exponentiellem Backoff. Informationen zur Implementierung exponentiellen Backoff 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 der Fehler einer API nicht genügend Informationen zurückgibt, wird der Fehler möglicherweise in diesen Fehler umgewandelt. 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). Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
4 DEADLINE_EXCEEDED Die Frist ist abgelaufen, bevor der Vorgang abgeschlossen werden konnte. Bei Vorgängen, die den Systemstatus verändern, kann dieser Fehler angezeigt werden, 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. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
6 ALREADY_EXISTS Die Entität, die ein Client erstellen wollte, z. B. eine DICOM-Instanz, ist bereits vorhanden. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
7 PERMISSION_DENIED Der Aufrufer hat keine Berechtigung zur Ausführung des angegebenen Vorgangs. Dieser Fehlercode bedeutet nicht, dass die Anfrage gültig ist oder die angeforderte Entität existiert oder andere Voraussetzungen erfüllt. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
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. Möglicherweise wird das Kontingent im Laufe der Zeit verfügbar.
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. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
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. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
12 UNIMPLEMENTED Der Vorgang ist in der Cloud Healthcare API nicht implementiert oder wird nicht unterstützt bzw. ist dort nicht aktiviert. Wiederholen Sie den Vorgang nicht.
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 kann sich im Falle von Datenverlust oder -beschädigung an einen Supportmitarbeiter wenden.
16 UNAUTHENTICATED Die Anfrage enthält keine gültigen Authentifizierungsdaten für diesen Vorgang. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.