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:
- Die Google Cloud CLI
- Die Seite Cloud Healthcare API in der Google Cloud Console
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:
projects.locations.datasets.dicomStores.deidentify
projects.locations.datasets.dicomStores.export
projects.locations.datasets.dicomStores.import
projects.locations.datasets.dicomStores.studies.delete
projects.locations.datasets.dicomStores.studies.series.delete
FHIR-Methoden:
projects.locations.datasets.fhirStores.deidentify
projects.locations.datasets.fhirStores.export
projects.locations.datasets.fhirStores.import
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.
Rufen Sie in der Google Cloud Console die Seite Datasets auf.
Klicken Sie auf den Namen des Datasets mit dem LRO, den Sie ansehen möchten.
Klicken Sie auf Vorgänge.
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.
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.
"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:
Rufen Sie in der Google Cloud Console die Seite Datasets auf.
Klicken Sie auf den Namen des Datasets mit dem LRO, den Sie ansehen möchten.
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:
Rufen Sie in der Google Cloud Console die Seite Datasets auf.
Klicken Sie auf den Namen des Datasets mit dem LRO, den Sie ansehen möchten.
Klicken Sie auf Vorgänge.
Ö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:
- Rufen Sie die Methode
operations.list
auf, um die Namen der Vorgänge in einem Dataset abzurufen. - 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. |