Diese Seite wurde von der Cloud Translation API übersetzt.

Best Practices für lang andauernde Vorgänge

Auf dieser Seite werden Best Practices für das 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 Vorgänge mit langer Ausführungszeit verwalten.

LRO-Properties

Die folgenden Abschnitte beziehen sich auf die Methoden, die unter Methoden, die einen LRO zurückgeben aufgeführt sind.

Auswirkungen auf das Kontingent

LROs teilen sich kein Kontingent mit den CRUD-Methoden (Create, Read, Update, Delete) der Cloud Healthcare API, die die folgenden Kontingenttypen verbrauchen:

Das LRO-Kontingent wird anhand der Messwerte fhir_store_lro_ops und dicom_store_lro_ops berechnet.

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

Datendurchsatz

LRO-Methoden erreichen in der Regel einen höheren Datendurchsatz als entsprechende CRUD-Methoden. Beispielsweise ist der Import von DICOM-Instanzen mit dicomStores.import in der Regel schneller als das Speichern der Instanzen einzeln mit dicomStores.storeInstances.

Wenn Sie mehrere LROs gleichzeitig ausführen, wird der Datendurchsatz aufgrund der folgenden Einschränkungen möglicherweise nicht erhöht, insbesondere bei der Verarbeitung großer Datenmengen:

Kontingenteinschränkungen
Ressourcenkonflikt
Anderer Traffic, den Ihr Google Cloud-Projekt während der Ausführung eines LRO an die Cloud Healthcare API sendet

Beachten Sie Folgendes, um beim Ausführen von LROs den maximalen Datendurchsatz zu erzielen:

Kleine Import- und Export-Batches haben aufgrund des Overheads in der Regel einen geringen Durchsatz.
LROs werden unabhängig von anderen Cloud Healthcare API-Vorgängen ausgeführt und verbrauchen ein eigenes Kontingent.
Jeder LRO hat einen maximalen Durchsatz.
Gleichzeitige LROs für dieselbe Ressource können zu Sperrkonflikten führen.
Die Cloud Healthcare API begrenzt die Anzahl der LROs, die gleichzeitig in einem Google Cloud-Projekt ausgeführt werden können. Weitere Informationen finden Sie unter Einschränkungen für die Anzahl der LROs.

Planen Sie die Anzahl der LROs, die für Ihren Anwendungsfall erforderlich sind. Wenn Sie große Datenbatches auf mehrere LROs aufteilen müssen, sollten Sie die Anzahl der Partitionen möglichst gering halten.

Referenzielle FHIR-Integrität

Bei der Methode fhirStores.import wird die Einstellung disableReferentialIntegrity nicht berücksichtigt. So können Sie Daten mit beliebigen Abhängigkeiten importieren, die nicht sortiert oder gruppiert werden müssen. Dadurch wird der Datendurchsatz erhöht. Wenn die Eingabedaten ungültige Referenzen enthalten oder einige FHIR-Ressourcen nicht importiert werden, kann der Status des FHIR-Speichers die referenzielle Integrität verletzen.

Damit Sie fhirStores.import verwenden können, muss Ihre Clientanwendung prüfen, ob FHIR-Ressourcenverweise gültig sind. Dazu müssen Sie Folgendes prüfen:

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

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

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.

Bei den folgenden Importmethoden werden keine Pub/Sub-Benachrichtigungen gesendet:

Wenn für Teile Ihrer Anwendung eine Benachrichtigung erforderlich ist, wenn ein Import abgeschlossen 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 verursacht. Implementieren Sie eine Möglichkeit, die LRO-Verarbeitung und Fehler separat zu erfassen. Weitere Informationen finden Sie unter Fehlerbehandlung bei Ressourcen.

Daten- und Suchindexierung

Aufgrund der asynchronen Indexierung der Suche kann es zu Verzögerungen bei den Suchergebnissen kommen. Wenn eine LRO eine FHIR-Ressource erstellt oder aktualisiert, kann es etwas dauern, bis die Änderungen in den Suchergebnissen angezeigt werden.

Beispielsweise werden bei einer Suche nach Patientenressourcen in einem FHIR-Speicher nach einem FHIR-Importvorgang möglicherweise nicht sofort alle Ergebnisse zurückgegeben.

Ausführungsreihenfolge

LROs werden basierend auf der Verfügbarkeit von Google Cloud-Ressourcen geplant. Die Reihenfolge, in der LROs ausgeführt und abgeschlossen werden, entspricht möglicherweise nicht der Reihenfolge, 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, tragen dazu bei, den Datendurchsatz zu skalieren, indem große Datenmengen schnell verarbeitet und Lastspitzen vermieden werden. Wenn Sie kleine Datenmengen speichern möchten, verwenden Sie eine andere Methode aus den Best Practices zum Speichern von Daten.

Beschränkungen für die Anzahl der LROs

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

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

Wenn Sie zu viele LROs ausführen, werden die Cloud Healthcare API-Geschwindigkeitslimits überschritten, es kommt zu Fehlern und der LRO-Durchsatz kann sinken. Die Cloud Healthcare API schont automatisch Google Cloud-Ressourcen, damit die Anzahl der LROs innerhalb der Ressourcenlimits bleibt.

LROs sind Hintergrundprozesse. Wenn die Auslastung durch LROs Prozesse mit höherer Priorität beeinträchtigt, z. B. CRUD-Vorgänge, kann die Cloud Healthcare API den LRO-Durchsatz reduzieren. So wird sichergestellt, dass die Prozesse mit höherer Priorität verfügbar sind.

Overhead bei der Ressourcenzuweisung und Bereinigung

Wenn ein LRO gestartet wird, weist die Cloud Healthcare API Ressourcen zu. Das kann einige Minuten dauern, da die Cloud Healthcare API Folgendes tun muss:

Starten Sie einen Controller-Prozess.
Worker aus einem Worker-Pool zuweisen
Legen Sie die Größe der Eingabedaten fest.
Aufgaben im großen Stil zuweisen

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

Aufgrund des Overheads kann ein LRO, der eine kleine Datenmenge verarbeitet, die meiste Zeit damit verbringen, Worker-Pools zuzuweisen und Ressourcen zu bereinigen.

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

Limits für das Anfordern von LRO-Kontingenten

Bevor Sie mehr LRO-Kontingent beantragen, sollten Sie die Best Practices für die Kontingentverwaltung implementieren. Wenn Sie noch mehr Kontingent benötigen, wenden Sie sich an den Google Cloud-Kundenservice. Informationen zum Anfordern eines zusätzlichen Kontingents finden Sie unter Best Practices für das Anfordern zusätzlicher Kontingente.

Möglicherweise benötigen Sie ein zusätzliches Kontingent, wenn Ihre Eingabedaten groß sind, z. B.:

Sie importieren DICOM-Instanzen mit einer Größe von mehreren Petabyte (PB).
Sie importieren Dutzende von Milliarden FHIR-Ressourcen.

LRO-Status und Fehlerstatus

Wenn Sie einen LRO starten, enthält die Antwort eine eindeutige ID. Sie können den Status einer LRO abrufen, indem Sie die ID abfragen. Nach Abschluss der LRO hat sie einen der folgenden Status:

Erfolgreich abgeschlossen, ohne Fehler
Mit einigen Fehlern erfolgreich abgeschlossen
Die Ausführung konnte nicht abgeschlossen werden, es wurde aber möglicherweise eine teilweise Ausgabe erstellt, bevor der Fehler aufgetreten ist.

Im folgenden JSON-Beispiel wird die Antwort beschrieben, die zurückgegeben wird, wenn eine 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 von LROs und zum Abbrechen von LROs finden Sie unter Vorgänge mit langer Ausführungszeit verwalten.

LRO-Status und Fehlerstatus verwalten

Beachten Sie die folgenden Best Practices, um den LRO-Status und den Fehlerstatus zu verwalten:

LROs abfragen, um ihren Status zu erhalten und zu prüfen, ob sie abgeschlossen sind Für die Abfrage eines LRO 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. Wenn die Antwort "done": true enthält, ist die LRO abgeschlossen.
Prüfen Sie nach Abschluss eines LRO, ob die Antwort ein Feld error enthält. Wenn ja, entscheiden Sie anhand der folgenden Kriterien, ob Sie den Vorgang wiederholen möchten:
- Den Fehlercode. Fehlercodes und empfohlene Maßnahmen finden Sie unter Fehlerbehebung bei LROs.
- Die Anzahl der bereits durchgeführten Neuversuche.
- Die Zeitspanne zwischen Beginn der LRO und Auftreten des Fehlers. Wenn eine LRO, die normalerweise mehrere Stunden dauert, beispielsweise mehrere Tage in Anspruch nimmt und kein Fehlerstatus zurückgegeben wurde, sollten Sie einen Mitarbeiter bitten, einzugreifen. Weitere Informationen dazu, wann eine manuelle Intervention erforderlich sein könnte, finden Sie unter Endgültige Fehlerstatus planen.
Informationen zum Wiederholen eines LRO finden Sie unter LRO in die Warteschlange stellen.
Wenn Sie den LRO nicht noch einmal versuchen, sehen Sie im Feld metadata.counter.failure nach, 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

Eine LRO kann mit Fehlern abgeschlossen werden. Fehler in der LRO-Antwort folgen dem Google Cloud-Fehlermodell. Die LRO-Antwort enthält einen Link zu Cloud Logging mit weiteren Informationen.

LRO-Fehlerdetails

LRO-Fehler in Cloud Logging haben folgende Eigenschaften:

Das Cloud Logging-Fehlerprotokoll enthält keine LRO-ID. In den Feldern operation.id und operation.producer finden Sie den Status und die Fehler des LRO. LROs, die über die Methode projects.locations.datasets.fhirStores.import aufgerufen werden, enthalten beispielsweise import_fhir im Feld operation.producer.

Wenn mehrere LROs dieselbe operation.id und operation.producer haben, verwende die Zeitstempel createTime und endTime, um die richtige LRO zu ermitteln.
Nicht alle LRO-Fehler sind in Cloud Logging verfügbar. Die Anzahl der tatsächlich protokollierten Fehler kann die im Feld metadata.counter.failure angegebene Anzahl überschreiten. Das kann folgende Gründe haben:
- Einschränkungen für Cloud Logging-Kontingente
- Verfügbarkeit des Cloud Logging-Dienstes
- Limits für LRO-Logs
Wenn beispielsweise 10 Millionen FHIR-Ressourcen über eine LRO importiert werden und 50% davon Formatierungsfehler aufweisen, werden aufgrund der Ratenbegrenzung und der Cloud Logging-Kontingente möglicherweise nur einige hundert oder tausend Fehler protokolliert.

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

Auswirkungen des erneuten Versuchs mit einem LRO

Wenn bei einem LRO ein Fehler auftritt und eine Clientanwendung den Vorgang automatisch mit denselben Daten noch einmal ausführt, kann der Neuversuch zu weiteren Fehlern führen.

Angenommen, ein fhirStores.import-LRO endet mit Fehlern, weil einige der FHIR-Ressourcen, die importiert werden sollten, ungültig waren. Wenn Sie den Import automatisch mit denselben Daten wiederholen, kann es zu vielen 409 ALREADY_EXISTS-Fehlern kommen, da einige FHIR-Ressourcen bereits beim 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 von einem Mitarbeiter überprüft werden.

Wenn ein erneuter Versuch 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 des erfolgreichen Wiederholungsversuchs keine Fehler aus früheren Versuchen enthält.

LRO noch einmal versuchen

Wenn Sie eine clientseitige Verarbeitungspipeline haben, die LRO-Fehler erkennt, sollten Sie Cloud Logging nicht verwenden. Wie unter Details zu LRO-Fehlern beschrieben, sind die Cloud Logging-Fehlerprotokolle für LROs unzuverlässig und unvollständig. Verwenden Sie stattdessen die Methoden in den folgenden Abschnitten.

Importvorgänge wiederholen

Um Daten zu ermitteln, die nicht importiert werden konnten, vergleichen Sie die importierten Daten in der Cloud Healthcare API mit den Quelldaten in Cloud Storage. Sie haben folgende Möglichkeiten, Daten zu importieren:

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

Unter Auswirkungen des Wiederholens eines LROs finden Sie Informationen dazu, was Sie beim Wiederholen eines Importvorgangs beachten müssen.

Wenn Sie einen Import noch einmal ausführen, werden möglicherweise Ressourcen neu erstellt, die Sie zuvor gelöscht haben. 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 der Zwischenzeit bittet ein Patient Sie, seine Daten zu entfernen.
Wenn Sie den Import noch einmal ausführen, besteht das Risiko, dass die Daten des Patienten, die Sie gelöscht haben, wiederhergestellt werden.

Exportvorgänge wiederholen

Wenn Sie Daten ermitteln möchten, die nicht nach BigQuery exportiert wurden, schreiben Sie ein Script, um eindeutige IDs in den Quelldaten mit den exportierten Daten zu vergleichen.

Sie haben folgende Möglichkeiten, Daten nach BigQuery zu exportieren:

LROs in die Warteschlange stellen und verwalten

Wenn Sie LROs ausführen, die große Datenmengen für das Onboarding oder in regelmäßigen Abständen verarbeiten, implementieren Sie die folgenden LRO-Warteschlangentechniken:

Begrenzen Sie die Anzahl gleichzeitiger LROs auf eine kleine Zahl wie 5. Sie können dieses Limit je nach Größe und Art der von Ihnen ausgeführten LROs anpassen.
LRO-Abschluss überwachen Wenn Fehler auftreten, planen Sie die LRO neu oder beheben Sie die Fehler separat in Ihrer Verarbeitungspipeline.
Beheben Sie nach Möglichkeit die Fehler unter Umgang mit Ressourcenfehlern automatisch.
- Informieren Sie sich über den Anwendungsfall für FHIR-Importe, um zu entscheiden, ob 409 ALREADY_EXISTS-Fehler ignoriert oder separate CRUD-Vorgänge ausgeführt werden sollen, um die Fehler zu beheben. Wie in den Details zu LRO-Fehlern gezeigt, werden einige 409 ALREADY_EXISTS-Fehler möglicherweise nicht in Cloud Logging protokolliert. Wenn Ihre Anwendung Fehlerprotokolle verwendet, verwenden Sie eine der Methoden unter LRO noch einmal versuchen.
- Wenn Sie nur einige Fehler beheben möchten, legen Sie eine kleinere LRO für die Daten in die Warteschlange, bei denen die Fehler aufgetreten sind, oder führen Sie separate CRUD-Vorgänge aus.
- Um viele Fehler zu beheben, ist das erneute Ausführen des LRO möglicherweise die einfachste Option, um für Konsistenz zu sorgen. Unter Importvorgänge wiederholen finden Sie Informationen zu den Risiken, die mit dem erneuten Ausführen eines Imports auf gelöschte Daten verbunden sind.
Automatisch erkennen, ob menschliches Eingreifen erforderlich ist, um Fehler zu beheben. Sie sollten Tools und operative Playbooks für Systemadministratoren haben. Zu den Aufgaben zur Behebung von Fehlern gehören:
- LRO verschieben
- Eine Teilmenge von Daten aus einem vorherigen LRO neu planen.
- Prüfen Sie die Fehler und beheben Sie die Probleme mit den einzelnen Datenelementen. Diese Aufgabe ist nur möglich, wenn Sie feststellen können, dass alle Fehler im LRO protokolliert wurden.
LRO-Zeitpläne festlegen. 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.

Monitoring und Benachrichtigungen

Verfahren zum Überwachen von LROs und zum Beheben von Benachrichtigungen erstellen und pflegen Benachrichtigungen werden hauptsächlich durch LRO-Status und Warteschlangenprobleme verursacht. Die Verfahren sollten die folgenden Situationen abdecken:

LROs, die mehrmals als konfiguriert erfolglos wiederholt werden.
Probleme, bei denen menschliches Eingreifen erforderlich ist, um einen Teil der Fehler zu beheben. Wenn beispielsweise ein LRO fehlschlägt und der Kunde die Fehler nicht beheben kann, ist wahrscheinlich manuelles Eingreifen erforderlich. Weitere Informationen zur Behebung von Problemen, die manuelles Eingreifen erfordern, finden Sie unter LROs in der Warteschlange verwalten.
Warteschlangen, die eine bestimmte Länge überschreiten oder zu schnell wachsen
Richtlinienanforderungen werden nicht erfüllt, z. B. ein Berechtigungsproblem oder eine Fehlkonfiguration.
Konsistenzprüfungen, die systemische Probleme in mehreren LROs aufzeigen. Möglicherweise haben Sie mehrere LROs zur De-Identifikation, für die das Quell- und das Ziel-Dataset dieselbe Anzahl von FHIR-Ressourcen enthalten müssen. Wenn eine Abweichung mit der Zeit zunimmt, kann das auf nicht verarbeitete Daten hinweisen.
Probleme mit LRO-Kontingenten Weitere Informationen finden Sie unter Kontingent verwalten, um den Datendurchsatz zu maximieren und Best Practices für die Kontingentverwaltung.