Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Auf dieser Seite werden Optionen zum Speichern großer FHIR-Datenmengen in der Cloud Healthcare API beschrieben.
FHIR-Ressourcen importieren
Verwenden Sie die Methode fhirStores.import, um FHIR-Ressourcen aus Cloud Storage in die Cloud Healthcare API zu laden.
Die Methode funktioniert am besten, wenn Daten ohne Störungen durch andere Anwendungen in einen leeren FHIR-Speicher geladen werden.
Berücksichtigen Sie die folgenden Eigenschaften der fhirStores.import-Methode, wenn Sie entscheiden, ob Sie sie verwenden möchten. Wenn fhirStores.import für Ihre Anwendung nicht geeignet ist, können Sie Daten mit der fhir.executeBundle-Methode laden. Weitere Informationen zum Aufrufen von fhir.executeBundle finden Sie unter FHIR-Ressourcen mithilfe von FHIR-Bundles verwalten.
Die fhirStores.import-Methode akzeptiert Bundles, die größer als das Limit von 50 MB für fhir.executeBundle sind.
Die Größe jeder einzelnen Ressource im Bundle ist jedoch auf 10 MB begrenzt.
Mit fhirStores.import werden die Komplexitäten bei der Ausführung großer FHIR-Bundles beseitigt, z. B.:
FHIR-Bundles in kleinere Bundles aufteilen
Mehrere Zeitpläne für Sets verwalten
Vorübergehende Fehler verwalten, die auf Ressourcen- oder Bundle-Ebene wiederholt werden können
Oft überwiegen diese Vorteile die Vorteile von Sets.
Jede Ressource in der Eingabe muss eine vom Kunden bereitgestellte ID enthalten. Ressourcen werden unabhängig von der enableUpdateCreate-Einstellung des FHIR-Speichers gespeichert.
Der Importprozess erzwingt keine referenzielle Integrität, egal, was in der disableReferentialIntegrity-Einstellung des FHIR-Speichers angegeben ist. Wird die referenzielle Integrität nicht erzwungen, können Sie Ressourcen mit beliebigen Abhängigkeiten importieren, ohne die Gruppierung oder Sortierung zu berücksichtigen. Falls die Eingabedaten ungültige Referenzen enthalten oder einige Ressourcen nicht importiert werden, kann der Status des FHIR-Speichers die referenzielle Integrität verletzen.
Ist eine Ressource mit einer bestimmten ID bereits im Speicher vorhanden, so wird die neueste Version der Ressource überschrieben, ohne dass eine neue Verlaufsversion erstellt wird. Das Überschreiben erfolgt unabhängig von der disableResourceVersioning-Einstellung des FHIR-Speichers. Wenn beim Import vorübergehende Fehler auftreten, können erfolgreich importierte Ressourcen mehrmals überschrieben werden.
Der Importvorgang ist idempotent, es sei denn, die Eingabedaten enthalten mehrere gültige Ressourcen mit derselben ID, aber unterschiedlichen Inhalten. In diesem Fall enthält der Speicher nach Abschluss des Imports genau eine Ressource mit jeder ID, die doppelten Einträge können jedoch eine beliebige Version des Inhalts enthalten. Beispiel: Wenn Sie eine Million Ressourcen mit derselben ID importieren, wird nur eine Ressource in den Speicher geschrieben.
Die Vorgangsergebniszähler zählen gedoppelte IDs nicht als Fehler. Jede Ressource in der Eingabe zählt als Erfolg. Dies kann zu einer Erfolgsrate führen, die über der Anzahl der Ressourcen im FHIR-Speicher liegt. Dies geschieht häufig beim Importieren von in Patient-everything erstellten Daten, wobei jedes Bundle eine eigene Kopie einer Ressource enthält, z. B. Practitioner, auf die viele Patientenressourcen verweisen können.
Wenn Ressourcen nicht erfolgreich importiert werden, z. B. aufgrund von Parsing-Fehlern, werden importierte Ressourcen nicht zurückgesetzt. Beispiel: Werden fünf von 100 Ressourcen nicht importiert, so werden die verbleibenden 95 Ressourcen in den FHIR-Speicher importiert.
Bei Verwendung des BUNDLE-Formats werden von der Importmethode Bundles mit einer Bundle.type von history abgelehnt. Die Importmethode wendet die Semantik für die Bundle-Verarbeitung nicht auf Batch- oder Transaktionsbundles an.
Im Gegensatz zu fhir.executeBundle werden Transaktions-Bundles nicht als einzelne Transaktion ausgeführt. Weiter werden clusterinterne Referenzen nicht neu geschrieben. Das Bundle wird als eine Sammlung von Ressourcen behandelt, die wie in Bundle.entry.resource festgelegt bereitgestellt werden sollen, wobei Bundle.entry.request ignoriert wird. Dies ermöglicht beispielsweise das Importieren von Searchset-Bundles, die von einem FHIR-Such- oder Patient-everything-Vorgang erstellt wurden.
FHIR-Bundles verwenden
Eine Übersicht über FHIR-Bundles finden Sie unter FHIR-Bundles.
Wann sollten FHIR-Bundles verwendet werden?
Berücksichtigen Sie die folgenden Eigenschaften und Vorteile der fhir.executeBundle-Methode, wenn Sie entscheiden, ob Sie sie zum Speichern von FHIR-Ressourcen verwenden möchten:
Wenn es zu teuer ist, entweder in Bezug auf die Abrechnungskosten oder die Netzwerkbandbreite, eine Pipeline zu erstellen, die Daten in Cloud Storage speichert und sie dann mit fhirStores.import importiert, verwenden Sie fhir.executeBundle.
Bei der Ausführung von Bundles kann die Transaktionsintegrität erzwungen werden.
Bei der Ausführung von Bundles kann die FHIR-Profilvalidierung erzwungen werden.
Wenn Sie Pub/Sub-Benachrichtigungen senden müssen, wenn FHIR-Vorgänge zum Erstellen, Aktualisieren oder Löschen ausgeführt werden, verwenden Sie fhir.executeBundle.
Pub/Sub-Benachrichtigungen werden nicht gesendet, wenn FHIR-Ressourcen mit fhirStores.import importiert werden.
Wenn die Zeit, zu der eine bestimmte FHIR-Ressource verarbeitet werden muss, in Sekunden oder Minuten angegeben ist, verwenden Sie fhir.executeBundle. Wenn die Zeit, zu der eine bestimmte FHIR-Ressource verarbeitet werden muss, in Stunden oder Tagen angegeben ist, verwenden Sie fhirStores.import.
Wenn in Ihrem Google Cloud Projekt viele Vorgänge mit langer Ausführungszeit (Long-Running Operations, LROs) vorhanden sind, die andere Aufgaben ausführen, erzielen Sie mit fhir.executeBundle möglicherweise eine bessere Leistung als mit fhirStores.import.
Wenn die Anwendung, die den fhirStores.import-Vorgang verwaltet, keine gute Strategie für Folgendes hat, verwende fhir.executeBundle:
Umgang mit Bulk-Fehlern
Fehler bei einer Teilmenge von FHIR-Ressourcen oder bei ganzen Batches beheben
Wann FHIR-Bundles nicht verwendet werden sollten
Berücksichtigen Sie die folgenden Einschränkungen von fhir.executeBundle, wenn Sie entscheiden, ob Sie es zum Speichern von FHIR-Ressourcen verwenden möchten:
Für Bundles gilt für die Vorgänge innerhalb des Bundles dasselbe Kontingent und dieselbe Abrechnung wie für Vorgänge, die außerhalb des Bundles ausgeführt werden. Wenn ein Paket beispielsweise 10 POST-Vorgänge, 5 GET-Vorgänge und 1 DELETE-Vorgang enthält, sind das Kontingent und die Abrechnung für das Paket gleich, als würden diese Vorgänge unabhängig voneinander ausgeführt.
Daher sind niedrigere Kontingentlimits und FHIR-Betriebskosten keine Gründe, Bundles anstelle von fhirStores.import zu verwenden.
Bei großen Transaktionspaketen ist die Wahrscheinlichkeit höher, dass es zu Transaktionskonflikten kommt, was zu Datenkonflikten und fehlgeschlagenen Vorgängen führt. Informationen dazu, wie diese Probleme auftreten können und wie sie behoben werden, finden Sie unter 429 Resource Exhausted operation_too_costly-Fehler verhindern.
Mit Batch-Bundles können Sie einen hohen Datendurchsatz erzielen und aufrechterhalten, wodurch Datenkonflikte vermieden werden. Batch-Bundles bieten jedoch keine Funktionen für transaktionale Konsistenz wie die referenzielle Integrität.
Wenn ein Bundle groß ist, kann der Datendurchsatz sinken, auch wenn es sich um ein Batch-Bundle handelt. Weitere Informationen finden Sie unter Große Transaktionspakete vermeiden.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-18 (UTC)."],[[["\u003cp\u003eThis page outlines two primary methods for storing large amounts of FHIR data in the Cloud Healthcare API: using \u003ccode\u003efhirStores.import\u003c/code\u003e or \u003ccode\u003efhir.executeBundle\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efhirStores.import\u003c/code\u003e method is ideal for loading data from Cloud Storage into an empty FHIR store, accepting bundles larger than 50MB but with individual resource size limits of 10MB.\u003c/p\u003e\n"],["\u003cp\u003eUsing \u003ccode\u003efhirStores.import\u003c/code\u003e simplifies managing large FHIR data sets by removing the need to break down bundles, manage schedules, and handle transient errors, however, it does not enforce referential integrity or resource versioning.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efhir.executeBundle\u003c/code\u003e method is best when real-time processing of resources is necessary, such as when Pub/Sub notifications or FHIR profile validation is needed, and is preferable for applications with many long-running operations.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003efhir.executeBundle\u003c/code\u003e provides transactional integrity, but batch bundles lack transactional consistency, and large bundles may have data contention, impacting data throughput.\u003c/p\u003e\n"]]],[],null,["# FHIR import options\n\nThis page describes options for storing large batches of FHIR data in the\nCloud Healthcare API.\n| **Tip:** If you're importing data from an external bulk FHIR server, consider using the Google open source [Bulk FHIR Tools](https://github.com/google/bulk_fhir_tools) to load data directly into the Cloud Healthcare API.\n\nImport FHIR resources\n---------------------\n\nUse the\n[`fhirStores.import`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores/import)\nmethod to load FHIR resources from Cloud Storage into the Cloud Healthcare API.\nThe method performs best when loading data into an empty FHIR store without interference\nfrom other applications.\n\nTo call `fhirStores.import`, see\n[Importing and exporting FHIR resources using Cloud Storage](/healthcare-api/docs/how-tos/fhir-import-export).\n\nConsider the following properties of `fhirStores.import`\nmethod when deciding whether to use it. If `fhirStores.import` isn't suitable\nfor your application, consider using the\n[`fhir.executeBundle`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores.fhir/executeBundle)\nmethod to load data. For information about how to call `fhir.executeBundle`, see\n[Managing FHIR resources using FHIR bundles](/healthcare-api/docs/how-tos/fhir-bundles).\n\n- The `fhirStores.import` method accepts bundles larger than the [50 MB limit](/healthcare-api/quotas#resource_limits) on `fhir.executeBundle`. However, the size of each individual resource within the bundle is limited to [10 MB](/healthcare-api/quotas#resource_limits).\n- Using `fhirStores.import` removes the complexities of executing\n large FHIR bundles, such as the following:\n\n - Breaking up FHIR bundles into smaller bundles\n - Managing multiple bundle schedules\n - Managing transient errors that can be retried at the resource or bundle level\n\n Often, these advantages outweigh the advantages from using bundles.\n- Each resource in the input must contain a client-supplied ID. Each resource is\n stored using the provided ID regardless of the\n [`enableUpdateCreate`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore.FIELDS.enable_update_create)\n setting on the FHIR store.\n\n- The import process doesn't enforce referential integrity, regardless of the\n [`disableReferentialIntegrity`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore.FIELDS.disable_referential_integrity)\n setting on the FHIR store. Not enforcing referential integrity lets you\n import resources with arbitrary interdependencies without considering grouping\n or ordering. If the input data contains invalid references or if some\n resources fail to import, the state of the FHIR store might violate\n referential integrity.\n\n- If a resource with a given ID already exists in the store, the most recent\n version of the resource is overwritten without creating a new historical\n version. The overwriting occurs regardless of the\n [`disableResourceVersioning`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore.FIELDS.disable_resource_versioning)\n setting on the FHIR store. If transient failures occur during the import, a\n successfully imported resource could be overwritten more than once.\n\n- The import operation is idempotent unless the input data contains multiple\n valid resources with the same ID but different contents. In that case, after\n the import completes, the store contains exactly one resource with each ID,\n but the duplicate entries could contain any version of the contents. For\n example, importing a million resources with the same ID writes only one\n resource to the store.\n\n- The operation result counters don't count duplicate IDs as an error. Each\n resource in the input counts as one success. This could result\n in a success count larger than the number of resources in the FHIR store. This\n often occurs when importing data organized in bundles produced by\n `Patient-everything` where each bundle contains its own copy of a resource,\n such as `Practitioner`, that might be referenced by many Patient resources.\n\n- If some resources fail to import, such as due to parsing errors,\n successfully imported resources aren't rolled back. For example, if 5 of 100\n resources fail to import, the remaining 95 resources are imported into the\n FHIR store.\n\n- When using the `BUNDLE` format, the import method rejects bundles with\n `Bundle.type` of `history`. The import method doesn't apply the bundle\n processing semantics for batch or transaction bundles.\n Unlike in `fhir.executeBundle`, transaction bundles aren't executed as a\n single transaction and bundle-internal references aren't rewritten. The\n bundle is treated as a collection of resources to be written as provided in\n `Bundle.entry.resource`, ignoring `Bundle.entry.request`. For example, this\n allows the import of searchset bundles produced by a FHIR search or\n `Patient-everything` operation.\n\nUse FHIR bundles\n----------------\n\nSee [FHIR bundles](/healthcare-api/docs/how-tos/fhir-bundles#fhir_bundles) for\nan overview of FHIR bundles.\n\n### When to use FHIR bundles\n\nConsider the following characteristics and advantages of using the `fhir.executeBundle`\nmethod when deciding whether to use it to store FHIR resources:\n\n- If it is too costly, either in terms of billing costs or network bandwidth, to build a pipeline that stores data in Cloud Storage and then imports the data using `fhirStores.import`, use `fhir.executeBundle`.\n- When executing bundles, transaction integrity can be enforced.\n- When executing bundles, FHIR profile validation can be enforced.\n- If you need to send [Pub/Sub notifications](/healthcare-api/docs/how-tos/pubsub) when FHIR create, update, or delete operations occur, use `fhir.executeBundle`. Pub/Sub notifications are not sent when FHIR resources are imported using `fhirStores.import`.\n- If the time at which a particular FHIR resource must be processed is in in seconds or minutes, use `fhir.executeBundle`. If the time at which a particular FHIR resource must be processed is in hours or days, use `fhirStores.import`.\n- If your Google Cloud project has many existing long-running operations (LRO) performing other tasks, you might see better performance with `fhir.executeBundle` over `fhirStores.import`.\n- If the application managing the `fhirStores.import` operation doesn't\n have a good strategy for the following, use `fhir.executeBundle`:\n\n - Handling bulk errors\n - Addressing failures on a subset of FHIR resources or entire batches\n\n### When not to use FHIR bundles\n\nConsider the following limitations of `fhir.executeBundle` when determining\nwhether to use it to store FHIR resources:\n\n- Bundles have the equivalent quota and billing applied to the operations inside\n the bundle as if the operations were executed outside of the bundle. For example,\n if a bundle has 10 `POST` operations, 5 `GET` operations, and 1 `DELETE` operation,\n the quota and billing applied to the bundle is the same as if those operations\n were executed independently.\n\n As a result, aiming to lower quota limits and FHIR operation costs are not reasons to use\n bundles instead of `fhirStores.import`.\n- Large transaction bundles might be more likely to have transaction conflicts\n which leads to data contention and failed operations. For information on\n how these issues can occur, and how to resolve them, see [Prevent `429 Resource Exhausted operation_too_costly` errors](/healthcare-api/docs/best-practices-data-throughput#prevent-429).\n\n- You can achieve and maintain high data throughput using batch bundles, which\n helps you to avoid data contention. However, batch bundles do not\n have transactional consistency\n capabilities, such as [referential integrity](/healthcare-api/docs/concepts/fhir-referential-integrity)\n\n- If a bundle is large, even if it's a batch bundle, you might see reduced\n data throughput. For more information, see [Avoid large transaction bundles](/healthcare-api/docs/best-practices-data-throughput#avoid-large)."]]
