Diese Seite wurde von der Cloud Translation API übersetzt.

Best Practices für lang andauernde Vorgänge

Auf dieser Seite werden Best Practices zum Ausführen und Verwalten von Vorgängen mit langer Ausführungszeit (Long Running Operations, LROs) in der Cloud Healthcare API beschrieben. Eine Übersicht über LROs in der Cloud Healthcare API finden Sie unter Lang andauernde Vorgänge verwalten.

Attribute von LRO

Die folgenden Abschnitte gelten für die unter Methoden, die einen LRO zurückgeben aufgeführten Methoden.

Auswirkungen auf das Kontingent

LROs teilen keine Kontingente mit den CRUD-Methoden (Erstellen, Lesen, Aktualisieren und Löschen) der Cloud Healthcare API, die die folgenden Kontingenttypen nutzen:

Das Kontingent für LRO wird mit den Messwerten fhir_store_lro_ops und dicom_store_lro_ops berechnet.

Die Cloud Healthcare API begrenzt die Anzahl der LROs, die in einem Google Cloud-Projekt gleichzeitig ausgeführt werden können. Weitere Informationen finden Sie unter Limits für die Anzahl der LROs.

Datendurchsatz

LRO-Methoden erzielen in der Regel einen höheren Datendurchsatz als äquivalente CRUD-Methoden. Zum Beispiel ist das Importieren von DICOM-Instanzen mit dicomStores.import in der Regel besser als das Speichern der Instanzen einzeln mit dicomStores.storeInstances.

Die gleichzeitige Ausführung mehrerer LROs kann den Datendurchsatz aufgrund der folgenden Einschränkungen nicht erhöhen, insbesondere bei der Verarbeitung großer Datenmengen:

Kontingentbeschränkungen
Ressourcenkonflikte
Anderen Traffic, den Ihr Google Cloud-Projekt während der Ausführung eines LRO an die Cloud Healthcare API sendet

Für einen maximalen Datendurchsatz beim Ausführen von LROs ist Folgendes zu berücksichtigen:

Kleine Import- und Export-Batches haben aufgrund eines Aufwands in der Regel einen geringen Durchsatz.
LROs werden getrennt von anderen Cloud Healthcare API-Vorgängen ausgeführt und verbrauchen Kontingente.
Jeder LRO hat einen maximalen Durchsatz.
Gleichzeitige LROs in derselben Ressource können zu Sperrkonflikten führen.
Die Cloud Healthcare API begrenzt die Anzahl der LROs, die in einem Google Cloud-Projekt gleichzeitig ausgeführt werden können. Weitere Informationen finden Sie unter Limits für die Anzahl der LROs.

Planen Sie die Anzahl der LROs ein, die für Ihren Anwendungsfall erforderlich sind. Wenn Sie große Daten-Batches über mehrere LROs hinweg partitionieren müssen, versuchen Sie, die Anzahl der Partitionen gering zu halten.

Referenzielle FHIR-Integrität

Die Einstellung disableReferentialIntegrity wird in der Methode fhirStores.import nicht berücksichtigt. Auf diese Weise können Sie Daten mit beliebigen Abhängigkeiten importieren, die keine Sortierung oder Gruppierung erfordern, wodurch der Datendurchsatz erhöht wird. Wenn die Eingabedaten ungültige Verweise enthalten oder einige FHIR-Ressourcen nicht importiert werden können, verstößt der Status des FHIR-Speichers möglicherweise gegen die referenzielle Integrität.

Um fhirStores.import verwenden zu können, muss Ihre Clientanwendung sicherstellen, dass FHIR-Ressourcenverweise gültig sind. Dazu muss Folgendes überprüft werden:

FHIR-Ressourcendaten und -formatierung sind korrekt
Alle Fehler, die während des Imports auftreten, werden verwaltet

Verwenden Sie fhir.create oder fhir.executeBundle anstelle von fhirStores.import, um referenzielle Integrität zu erzwingen. Weitere Informationen finden Sie unter FHIR-Daten im Vergleich zum Ausführen von Bundles.

Pub/Sub-Benachrichtigungen

Einige Cloud Healthcare API-Methoden senden Pub/Sub-Benachrichtigungen für klinische Ereignisse, z. B. das Erstellen oder Löschen einer Gesundheitsressource. Eine Liste der Methoden zum Senden von Pub/Sub-Benachrichtigungen finden Sie unter Pub/Sub-Benachrichtigungen konfigurieren.

Die folgenden Importmethoden senden keine Pub/Sub-Benachrichtigungen:

Wenn für Teile Ihrer Anwendung nach Abschluss eines Imports eine Benachrichtigung erforderlich ist, verwenden Sie eine andere Benachrichtigungsmethode, mit der die Daten im Import aufgelistet werden können.

Limits für die Fehlerbehandlung

Die Cloud Healthcare API protokolliert möglicherweise nicht alle Fehler in einem LRO, insbesondere wenn der LRO große Datenmengen verarbeitet und viele Fehler erzeugt. Implementieren Sie eine Möglichkeit, die LRO-Verarbeitung und Fehler separat zu verfolgen. Weitere Informationen finden Sie unter Umgang mit Ressourcenfehlern.

Daten- und Suchindexierung

Aufgrund der asynchronen Suchindexierung kann es zu Verzögerungen bei den Suchergebnissen kommen. Wenn ein LRO eine FHIR-Ressource erstellt oder aktualisiert, kann es zusätzliche Zeit dauern, bis die Änderungen in den Suchergebnissen verfügbar sind.

Beispielsweise gibt eine Suche nach Patientenressourcen in einem FHIR-Speicher möglicherweise nicht alle Ergebnisse sofort nach einem FHIR-Importvorgang zurück.

Ausführungsreihenfolge

LROs werden basierend auf der Verfügbarkeit von Google Cloud-Ressourcen geplant. Die Reihenfolge, in der LROs ausgeführt und beendet werden, stimmt möglicherweise nicht mit der Reihenfolge überein, in der sie angefordert wurden.

Kleine Import- und Exportanfragen vermeiden

In diesem Abschnitt werden die Einschränkungen von LRO bei der Verarbeitung kleiner Datenmengen beschrieben.

LROs, die von Import- und Exportvorgängen zurückgegeben werden, helfen bei der Skalierung des Datendurchsatzes, da große Datenmengen schnell verarbeitet und Lastspitzen vermieden werden. Verwenden Sie zum Speichern kleiner Datenmengen eine andere Technik aus den Best Practices zum Speichern von Daten.

Limits für die Anzahl der LROs

Die Cloud Healthcare API begrenzt die Anzahl der LROs, die in einem Google Cloud-Projekt gleichzeitig ausgeführt werden können. Das Limit basiert auf Folgendem:

Der Typ des LRO.
Die Menge der Google Cloud-Ressourcen, die dem LRO zugewiesen sind. Dies hängt von der Größe der Eingabedaten ab.

Wenn Sie zu viele LROs ausführen, begrenzt die Cloud Healthcare API die Ratenbegrenzung, erzeugt Fehler und kann den LRO-Durchsatz verringern. Die Cloud Healthcare API spart automatisch Google Cloud-Ressourcen, sodass die Anzahl der LROs innerhalb der Ressourcenlimits bleibt.

LROs sind Hintergrundprozesse. Wenn die Last von LROs also Prozesse mit höherer Priorität, wie CRUD-Vorgänge, beeinträchtigt, kann die Cloud Healthcare API den LRO-Durchsatz reduzieren. Dadurch wird sichergestellt, dass die Prozesse mit höherer Priorität verfügbar sind.

Aufwand für Ressourcenzuweisung und Bereinigung

Wenn ein LRO gestartet wird, weist die Cloud Healthcare API Ressourcen zu. Dies kann einige Minuten dauern, da die Cloud Healthcare API Folgendes ausführen muss:

Starten Sie einen Controller-Prozess.
Worker aus einem Worker-Pool zuweisen.
Bestimmen Sie die Größe der Eingabedaten.
Mit der Zuweisung von Aufgaben in großem Umfang beginnen.

Das Beenden und Bereinigen eines LRO kann ebenfalls einige Minuten dauern.

Aufgrund des Aufwands kann ein LRO, der eine kleine Datenmenge verarbeitet, die meiste Zeit für das Zuweisen von Worker-Pools und das Bereinigen von Ressourcen aufwenden.

Wenn Sie viele dieser LROs haben, ist der Datendurchsatz möglicherweise geringer, da Sie die Kontingentlimits Ihres Google Cloud-Projekts eher erreichen.

Limits für das Anfordern von LRO-Kontingenten

Lesen Sie die Best Practices für die Kontingentverwaltung, bevor Sie ein höheres Kontingent für LRO beantragen. Wenn Sie ein größeres Kontingent benötigen, wenden Sie sich an Google Cloud Customer Care. Informationen zum Anfordern eines zusätzlichen Kontingents finden Sie unter Best Practices zum Anfordern eines zusätzlichen Kontingents.

Wenn Ihre Eingabedaten sehr groß sind, benötigen Sie möglicherweise zusätzliche Kontingente, zum Beispiel:

Sie importieren DICOM-Instanzen, die mehrere Petabyte (PB) groß sind.
Sie importieren Milliarden von FHIR-Ressourcen.

LRO-Status und Fehlerstatus

Wenn Sie einen LRO starten, enthält die Antwort eine eindeutige ID. Sie können den Status eines LRO durch Abfragen seiner ID anzeigen. Nachdem der LRO abgeschlossen ist, hat er einen der folgenden Status:

Ohne Fehler abgeschlossen
Mit einigen Fehlern abgeschlossen
Fertigstellen fehlgeschlagen, aber möglicherweise wurde vor dem Fehlschlagen eine Teilausgabe erzeugt

Im folgenden JSON-Beispiel wird die Antwort beschrieben, die zurückgegeben wird, wenn ein LRO abgeschlossen ist:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "METADATA_TYPE",
    "apiMethodName": "API_METHOD_NAME",
    "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": 
    
  },
  // 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: ...,
        ...
      }
    ]
  }
}

Informationen zum Abrufen des Status eines LRO, zum Auflisten und Abbrechen von LROs finden Sie unter Lang andauernde Vorgänge verwalten.

LRO-Status und Fehlerstatus verwalten

Folgen Sie diesen Best Practices, um den Status von LRO und Fehlerstatus zu verwalten:

Fragen Sie LROs ab, um ihren Status zu erhalten und zu prüfen, ob sie fertig sind. 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. Wenn die Antwort "done": true enthält, ist der LRO abgeschlossen.
Prüfen Sie nach Abschluss eines LRO, ob die Antwort das Feld error enthält. Wenn dies der Fall ist, bestimmen Sie anhand folgender Daten, ob der Vorgang wiederholt werden soll:
- Der Fehlercode. Fehlercodes und empfohlene Maßnahmen finden Sie unter Fehlerbehebung bei LROs.
- Die Anzahl der bereits erfolgten Wiederholungsversuche.
- Die Zeit zwischen dem Beginn des LRO und dem Auftreten des Fehlers. Wenn beispielsweise ein LRO, der normalerweise mehrere Stunden dauert, mehrere Tage dauert und keinen Fehlerstatus zurückgegeben hat, sollte möglicherweise ein Mensch eingreifen. Weitere Informationen dazu, wann manuelle Eingriffe erforderlich sein können, finden Sie unter Endgültige Fehlerzustände einplanen.
Informationen zum Wiederholen eines LRO in der Warteschlange finden Sie unter LRO in die Warteschlange stellen.
Wenn Sie den LRO nicht noch einmal ausführen, prüfen Sie im Feld metadata.counter.failure, ob bei bestimmten Ressourcen Fehler aufgetreten sind. Möglicherweise können Sie die Ressourcen einzeln verarbeiten. Weitere Informationen finden Sie unter Umgang mit Ressourcenfehlern.

Ressourcenfehler behandeln

Ein LRO kann mit Fehlern abgeschlossen werden. Für Fehler in der LRO-Antwort gilt das Google Cloud-Fehlermodell. Die Antwort des LRO enthält einen Link zu Cloud Logging für weitere Informationen.

Details zum LRO-Fehler

LRO-Fehler in Cloud Logging haben folgende Attribute:

Das Cloud Logging-Fehlerlog enthält nicht die LRO-ID. Verwenden Sie die Felder operation.id und operation.producer, um den Status und die Fehler des LRO zu ermitteln. Beispielsweise enthalten LROs, die über die Methode projects.locations.datasets.fhirStores.import aufgerufen werden, import_fhir im Feld operation.producer.

Wenn mehrere LROs dieselben operation.id und operation.producer haben, verwenden Sie die Zeitstempel createTime und endTime, um den richtigen LRO zu identifizieren.
Nicht alle LRO-Fehler sind in Cloud Logging verfügbar. Das Feld metadata.counter.failure kann die Anzahl der tatsächlich protokollierten Fehler aus folgenden Gründen überschreiten:
- Cloud Logging-Kontingentlimits
- Verfügbarkeit des Cloud Logging-Dienstes
- LRO-Loglimits
Wenn ein LRO beispielsweise 10 Millionen FHIR-Ressourcen importiert und 50% davon Formatierungsfehler aufweisen, können aufgrund der Ratenbegrenzung und der Cloud Logging-Kontingente nur wenige hundert oder einige tausend Fehler protokolliert werden.

Die Anzahl der protokollierten Fehler hängt auch davon ab, wie lange der LRO bei hohen Fehlerraten ausgeführt wird. Wenn der LRO langsam ausgeführt wird, werden möglicherweise mehr Fehler in Cloud Logging angezeigt, da die Fehler über einen langen Zeitraum verteilt waren und keiner Ratenbegrenzung unterliegen.

Auswirkungen der nochmaligen Ausführung eines LRO

Wenn bei einem LRO ein Fehler auftritt und eine Clientanwendung den Vorgang automatisch mit denselben Daten wiederholt, kann der Wiederholungsversuch weitere Fehler verursachen.

Stellen Sie sich ein Szenario vor, bei dem ein LRO vom Typ fhirStores.import mit Fehlern beendet wird, da einige der zu importierenden FHIR-Ressourcen ungültig waren. Wenn Sie den Import mit denselben Daten automatisch wiederholen, können viele 409 ALREADY_EXISTS-Fehler auftreten, da einige FHIR-Ressourcen im ursprünglichen Vorgang importiert wurden. Wenn Sie einen LRO abfragen und einen fehlgeschlagenen Erstellungsvorgang feststellen, wiederholen Sie den Vorgang nicht automatisch. 409 ALREADY_EXISTS Fehler sollten manuell überprüft werden.

Wenn ein Wiederholungsversuch erfolgreich ist, enthält das Feld metadata.counter.failure keine Fehler aus vorherigen Vorgängen. Dies kann zu einer falschen Fehleranzahl führen, da die Antwort auf den erfolgreichen Wiederholungsversuch keine Fehler aus früheren Versuchen enthält.

LRO wiederholen

Verwenden Sie Cloud Logging nicht, wenn Sie eine clientseitige Verarbeitungspipeline haben, die LRO-Fehler erkennt. Wie in Details zu LRO-Fehlern gezeigt, sind die Cloud Logging-Fehlerlogs für LROs unzuverlässig und unvollständig. Wenden Sie stattdessen die in den folgenden Abschnitten beschriebenen Verfahren an.

Importvorgänge wiederholen

Vergleichen Sie importierte Daten in der Cloud Healthcare API mit ihren Quelldaten in Cloud Storage, um Daten zu erkennen, die nicht importiert werden konnten. Sie können Daten mit den folgenden Methoden importieren:

Verwenden Sie eine eindeutige Kennung wie eine Krankenaktennummer (Medical Record Number, MRN) für eine FHIR-Patientenressource, um die Daten zu vergleichen.

Unter Auswirkungen der Wiederholung eines LRO finden Sie die Schritte, die beim Wiederholen eines Importvorgangs auszuführen sind.

Wenn Sie einen Import noch einmal ausführen, werden möglicherweise zuvor gelöschte Ressourcen neu erstellt. Stellen Sie sich folgendes Szenario vor:

Sie versuchen, 1.000.000 FHIR-Ressourcen zu importieren. 50.000 Ressourcen schlagen aufgrund von Formatierungsfehlern fehl.
Sie verbringen mehrere Tage damit, die Formatierungsfehler zu beheben. In dieser Zeit bittet ein Patient Sie, seine Unterlagen zu entfernen.
Wenn Sie den Import noch einmal ausführen, riskieren Sie, die gelöschten Patientendaten wiederherzustellen.

Exportvorgänge wiederholen

Um Daten zu erkennen, die nicht nach BigQuery exportiert werden konnten, schreiben Sie ein Skript, um eindeutige IDs in den Quelldaten mit den exportierten Daten zu vergleichen.

Sie können Daten mit den folgenden Methoden nach BigQuery exportieren:

LROs in die Warteschlange stellen und verwalten

Wenn Sie LROs ausführen, die große Datenmengen für das Onboarding oder nach einem regelmäßigen Zeitplan verarbeiten, implementieren Sie die folgenden Verfahren für LRO-Warteschlangen:

Beschränken Sie gleichzeitige LROs auf eine kleine Anzahl wie 5. Sie können dieses Limit je nach Größe und Art der ausgeführten Vorgänge mit langer Ausführungszeit anpassen.
Überwachen Sie den Abschluss des LRO. Wenn Fehler auftreten, planen Sie den LRO neu oder beheben Sie die Fehler separat in der Verarbeitungspipeline.
Beheben Sie die Fehler unter Umgang mit Ressourcenfehlern nach Möglichkeit automatisch.
- Informieren Sie sich über den Anwendungsfall für FHIR-Importe, um festzustellen, ob 409 ALREADY_EXISTS-Fehler ignoriert werden sollen oder ob separate CRUD-Vorgänge ausgeführt werden sollen, um die Fehler zu beheben. Wie in Details zu LRO-Fehlern dargestellt, werden einige 409 ALREADY_EXISTS-Fehler möglicherweise nicht in Cloud Logging protokolliert. Wenn Ihre Anwendung auf Fehlerlogs angewiesen ist, verwenden Sie eine der unter Wiederholen eines LRO beschriebenen Techniken.
- Um einige Fehler zu beheben, stellen Sie einen kleineren LRO für die Daten, in denen die Fehler aufgetreten sind, in die Warteschlange oder führen Sie separate CRUD-Vorgänge aus.
- Wenn Sie viele Fehler beheben möchten, ist es am einfachsten, den LRO noch einmal auszuführen, um für Konsistenz zu sorgen. Informationen zu den Risiken beim erneuten Ausführen eines Imports für gelöschte Daten finden Sie unter Importvorgänge wiederholen.
Automatische Erkennung, ob menschliche Eingriffe erforderlich sind, um Fehler zu beheben. Sie sollten Tools und operative Playbooks für Systemadministratoren haben. Aufgaben zur Behebung von Fehlern können Folgendes umfassen:
- Einen LRO verschieben.
- Verschieben Sie eine Teilmenge von Daten aus einem früheren LRO um.
- Untersuchen Sie Fehler und gehen Sie auf einzelne Datenelemente ein. Diese Aufgabe ist nur möglich, wenn Sie feststellen können, dass alle Fehler im LRO protokolliert wurden.
Bestimmen Sie Zeitpläne für LROs. Sie können LROs so planen, dass sie nicht zu Spitzenzeiten ausgeführt werden, wenn viele CRUD-Vorgänge ausgeführt werden. Weitere Informationen finden Sie unter Kontingent verwalten, um den Datendurchsatz zu maximieren.

Überwachen und Benachrichtigungen erhalten

Erstellen und Verwalten von Verfahren zur Überwachung von LROs und zur Behebung von Warnmeldungen. Benachrichtigungen werden hauptsächlich durch LRO-Status und queueing verursacht. Die Verfahren sollten für die folgenden Situationen geeignet sein:

LROs, die öfter erfolglos versucht werden, als konfiguriert ist.
Probleme, die ein manuelles Eingreifen erfordern, um einen Teil der Fehler zu beheben. Wenn beispielsweise ein LRO fehlschlägt und der Client die Fehler nicht beheben kann, ist wahrscheinlich ein menschliches Eingreifen erforderlich. Weitere Informationen zum Beheben von Problemen, die ein menschliches Eingreifen erfordern, finden Sie unter Warteschlangen und Vorgänge verwalten.
Warteschlangen, die eine Länge überschreiten oder zu schnell wachsen.
Richtlinienanforderungen werden nicht erfüllt, z. B. ein Berechtigungsproblem oder eine Fehlkonfiguration.
Konsistenzprüfungen, die systemische Probleme bei mehreren LROs aufzeigen. Möglicherweise haben Sie mehrere LROs für die De-Identifikation, die davon ausgehen, dass das Quell-Dataset und das Ziel-Dataset die gleiche Anzahl von FHIR-Ressourcen haben. Wenn es eine Abweichung gibt, die im Laufe der Zeit zunimmt, kann dies auf unverarbeitete Daten hinweisen.
Probleme mit LRO-Kontingenten. Weitere Informationen finden Sie unter Kontingente verwalten, um den Datendurchsatz zu maximieren und Best Practices für die Kontingentverwaltung.