Auf dieser Seite wird erläutert, wie Sie FHIR-Ressourcen durch Ausführen von FHIR-Bundles verwalten. Das sind Sammlungen von FHIR-Ressourcen und Vorgängen, die für diese FHIR-Ressourcen ausgeführt werden sollen.
Die Methode ExecuteBundle
implementiert die FHIR-Standard-Batch-/Transaktionsinteraktion (DSTU2, STU3 und R4) und Verlaufsvorgänge.
FHIR-Sets
Ein FHIR-Bundle enthält ein Array von Einträgen, die jeweils einen Vorgang wie das Erstellen, Aktualisieren oder Löschen einer Ressource wie einer Beobachtung oder eines Patienten darstellen. Weitere Informationen finden Sie in den detaillierten Beschreibungen der Elemente in der Bundle-Ressource.
Wenn Sie ein FHIR-Bundle ausführen, bestimmt der Bundle-Typ, wie die Vorgänge im Bundle ausgeführt werden. Folgende Bundle-Typen sind verfügbar:
batch
: Führt Vorgänge als mehrere unabhängige Anfragen aus.transaction
: Führt Vorgänge als mehrere Anfragen aus, die voneinander abhängen.history
: Fügen Sie die Einträge in den Verlauf einer Ressource ein.
Angenommen, ein Transaktions-Bundle umfasst das Erstellen einer Patienten- und einer Beobachtungsressource. Wenn die Anfrage zum Erstellen einer Patientenressource fehlschlägt, wird die Beobachtungsressource nicht erstellt.
Wenn ein Vorgang fehlschlägt, wenn der Bundle-Typ batch
ist, führt die Cloud Healthcare API die verbleibenden Vorgänge im Bundle aus. Wenn ein Vorgang fehlschlägt, wenn der Bundle-Typ transaction
ist, beendet die Cloud Healthcare API die Ausführung von Vorgängen und die Transaktion wird zurückgesetzt.
Pakete mit Dokumentationen
Verlaufsbundles sind benutzerdefinierte Erweiterungen des FHIR-Standards, die Anwendungsfälle wie Sicherung und Wiederherstellung unterstützen, z. B. Synchronisierung. Mit Verlaufspaketen können Sie Ressourcenversionen in den Verlauf einer FHIR-Ressource einfügen oder ersetzen. Sie können Ressourcenversionen nur mit der Methode Resource-purge
entfernen. Das history
-Bundle wird als einzelne Transaktion mit einem Limit von 100 Einträgen pro Bundle ausgeführt. Wenn eine Ressourcenversion im history
-Bundle einen Zeitstempel hat, der höher als der der neuesten Version im FHIR-Shop ist, wird die neueste Version entsprechend aktualisiert. Wenn das history
-Bundle erfolgreich eingefügt wurde, wird eine leere Antwort zurückgegeben. Andernfalls wird eine OperationOutcome
zurückgegeben, die den Fehler beschreibt.
Die Unterstützung für Verlaufspakete ist standardmäßig nicht aktiviert. Ein FHIR-Speicheradministrator muss enableHistoryModifications
in der FHIR-Speicherkonfiguration auf true
festlegen.
Sie können keine Verlaufsbundles verwenden, wenn disableResourceVersioning
in der FHIR-Speicherkonfiguration auf true
festgelegt ist.
Verlaufspakete werden im selben Format bereitgestellt, in dem sie von der Methode fhir.history
zurückgegeben werden. Jeder Bundle-Eintrag benötigt eine Ressourcen-ID, einen Änderungszeitstempel und einen Status, um gültig zu sein. Außerdem müssen alle Einträge dieselbe Ressourcen-ID haben. Die Ressourcen-ID wird im Feld resource.id
oder request.url
angegeben. Wenn Felder angegeben werden, muss die angegebene Ressourcen-ID identisch sein. Der Zeitstempel der Ressource wird über das Feld meta.lastUpdated
in der Ressource oder das Feld response.lastModified
angegeben.
Berechtigungen zum Ausführen von Bundles
Die Berechtigungsrolle datasets.fhirStores.fhir.executeBundle
ist erforderlich, um Bundles auszuführen. Verwenden Sie zum Erteilen dieser Berechtigung die Rolle healthcare.fhirResourceReader
. Die Schritte zum Erteilen dieser Berechtigung finden Sie unter Richtlinie ändern.
Zum Ausführen von Verlaufs-Bundles ist außerdem die Berechtigungsrolle datasets.fhirStores.fhir.import
erforderlich.
Die Cloud Healthcare API prüft die Berechtigungen für jeden Vorgang im Bundle.
Wenn Sie die Berechtigung healthcare.fhirResources.create
, aber nicht die Berechtigung healthcare.fhirResources.update
haben, können Sie nur Bundles ausführen, die healthcare.fhirResources.create
-Vorgänge enthalten.
Ein Bundle wird ausgeführt
Verwenden Sie zum Ausführen eines FHIR-Bundles die Methode projects.locations.datasets.fhirStores.fhir.executeBundle
.
In den folgenden Beispielen ist BUNDLE.json der Pfad und Dateiname eines JSON-codierten FHIR-Bundles. Sie können das Bundle auch in den Anfragetext einfügen.
Im folgenden Beispiel-Bundle wird eine Patientenressource erstellt und eine andere Patientenressource gelöscht.
{
"resourceType": "Bundle",
"id": "bundle-transaction",
"meta": {
"lastUpdated": "2018-03-11T11:22:16Z"
},
"type": "transaction",
"entry": [
{
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Smith",
"given": [
"Darcy"
]
}
],
"gender": "female",
"address": [
{
"line": [
"123 Main St."
],
"city": "Anycity",
"state": "CA",
"postalCode": "12345"
}
]
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"request": {
"method": "DELETE",
"url": "Patient/1234567890"
}
}
]
}
Die folgenden Beispiele zeigen, wie ein Bundle ausgeführt wird.
curl
Stellen Sie zum Ausführen eines Bundles eine POST
-Anfrage und geben Sie die folgenden Informationen an:
- Name und Speicherort des übergeordneten Datasets und FHIR-Speichers
- Speicherort der Bundle-Datei auf Ihrem lokalen Computer
- Ein Zugriffstoken
Das folgende Beispiel zeigt eine POST
-Anfrage mit curl:
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
Unabhängig vom Ergebnis der einzelnen Vorgänge gibt der Server nach der Ausführung eines Batchpakets eine JSON-codierte Darstellung einer Bundle
-Ressource des Typs batch-response
zurück. Die Ressource Bundle
enthält einen Eintrag für jeden Eintrag in der Anfrage mit dem Ergebnis der Verarbeitung des Eintrags. Dies kann eine Mischung aus Erfolgs- und Fehlerergebnissen sein.
Wenn ein Transaktionspaket erfolgreich ist, gibt der Server eine JSON-codierte Darstellung einer Bundle
-Ressource vom Typ transaction-response
zurück, die einen Eintrag für jeden Eintrag in der Anfrage mit dem erfolgreichen Ergebnis des Vorgangs enthält.
Wenn während der Ausführung eines Transaktionspakets ein Fehler auftritt, enthält der Antworttext kein Paket. Stattdessen enthält es eine JSON-codierte OperationOutcome
-Ressource, die die Fehlerursache beschreibt. Erfolgreiche Vorgänge, für die ein Rollback durchgeführt wurde, werden in der Antwort nicht aufgeführt.
Das folgende Beispiel-Bundle ist die Ausgabe der erfolgreichen Ausführung des obigen Beispiels. Der erste Eintrag gibt den Erfolg des Vorgangs zum Erstellen eines Patienten an und enthält die ID der neuen Ressource. Der zweite Eintrag gibt den Erfolg des Löschvorgangs an.
{ "entry": [ { "response": { "location": projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID, "status": "201 Created" } }, { "response": { "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
Stellen Sie zum Ausführen eines Bundles eine POST
-Anfrage und geben Sie die folgenden Informationen an:
- Name und Speicherort des übergeordneten Datasets und FHIR-Speichers
- Speicherort der Bundle-Datei auf Ihrem lokalen Computer
- Ein Zugriffstoken
Das folgende Beispiel zeigt eine POST
-Anfrage mit Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
Unabhängig vom Ergebnis der einzelnen Vorgänge gibt der Server nach der Ausführung eines Batchpakets eine JSON-codierte Darstellung einer Bundle
-Ressource des Typs batch-response
zurück. Die Ressource Bundle
enthält einen Eintrag für jeden Eintrag in der Anfrage mit dem Ergebnis der Verarbeitung des Eintrags. Dies kann eine Mischung aus Erfolgs- und Fehlerergebnissen sein.
Wenn ein Transaktionspaket erfolgreich ist, gibt der Server eine JSON-codierte Darstellung einer Bundle
-Ressource vom Typ transaction-response
zurück, die einen Eintrag für jeden Eintrag in der Anfrage mit dem erfolgreichen Ergebnis des Vorgangs enthält.
Wenn während der Ausführung eines Transaktionspakets ein Fehler auftritt, enthält der Antworttext kein Paket. Stattdessen enthält es eine JSON-codierte OperationOutcome
-Ressource, die die Fehlerursache beschreibt. Erfolgreiche Vorgänge, für die ein Rollback durchgeführt wurde, werden in der Antwort nicht aufgeführt.
Das folgende Beispiel-Bundle ist die Ausgabe der erfolgreichen Ausführung des obigen Beispiels. Der erste Eintrag gibt den Erfolg des Vorgangs zum Erstellen eines Patienten an und enthält die ID der neuen Ressource. Der zweite Eintrag gibt den Erfolg des Löschvorgangs an.
{ "entry": [ { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "location": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
Go
Java
Node.js
Ein Beispiel für eine Bundle-Datei ist im GitHub-Repository des Codebeispiels verfügbar.
Python
Ein Beispiel für eine Bundle-Datei ist im GitHub-Repository des Codebeispiels verfügbar.
PATCH
-Anfrage stellen
Mit FHIR-Bundles können Sie JSON-PATCH
-Anfragen an FHIR-Ressourcen senden.
Weitere Informationen finden Sie unter PATCH
-Anfrage in einem FHIR-Bundle ausführen.
Verweise auf Ressourcen in einem Bundle aufheben
Ressourcen in einem Transaktionsset können Verweise auf Ressourcen enthalten, die im Zielsystem nicht vorhanden sind, aber während der Bundle-Ausführung erstellt werden. Die Cloud Healthcare API löst die Zuordnung zwischen den Ressourcen mithilfe des Felds entry.fullUrl
auf. Referenzen, die mit dem entry.fullUrl
-Wert einer anderen Ressource im Bundle entsprechen, werden in die ID der entsprechenden Ressource im Speicher umgeschrieben. Dieser Vorgang ist unabhängig von der Reihenfolge der Vorgänge im Bundle erfolgreich.
Die Cloud Healthcare API akzeptiert die fullUrl
in den folgenden Formaten:
urn:uuid:UUID
urn:oid:OID
- einer beliebigen URL
- einem Ressourcennamen im Format
RESOURCE_TYPE/RESOURCE_ID
, z. B.Patient/123
. Die Verwendung dieses Formats wird nicht empfohlen, dafullUrl
ein Platzhalter für das Bundle ist. Dies kann Verwirrung stiften, wenn eine Ressource im Speicher den gleichen Namen hat, aber die Ressource im Bundle aufgrund eines Erstellungsvorgangs in einen anderen Namen aufgelöst wird.
Im folgenden Beispiel-Bundle werden eine Patientenressource und eine Beobachtungsressource erstellt, die sich auf die Patientenressource bezieht.
{
"resourceType": "Bundle",
"type": "transaction",
"entry":[
{
"request": {
"method":"POST",
"url":"Patient"
},
"fullUrl": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9",
"resource": {
"resourceType":"Patient",
"gender":"male"
}
},
{
"request": {
"method":"POST",
"url":"Observation"
},
"resource": {
"resourceType":"Observation",
"subject": {
"reference": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9"
},
"status":"preliminary",
"code": {
"text":"heart rate"
}
}
}
]
}
Die folgenden Beispiele zeigen, wie ein Bundle ausgeführt wird.
curl
Ein Beispiel für eine Bundle-Datei ist im GitHub-Repository des Codebeispiels verfügbar.
Stellen Sie zum Ausführen eines Bundles eine POST-Anfrage und geben Sie die folgenden Informationen an:
- Name und Speicherort des übergeordneten Datasets und FHIR-Speichers
- Speicherort der Bundle-Datei in Cloud Storage
- Ein Zugriffstoken
Das folgende Beispiel zeigt eine POST
-Anfrage mit curl:
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
Das folgende Beispiel-Bundle ist die Ausgabe der erfolgreichen Ausführung des obigen Beispiels. Der erste Eintrag gibt den Erfolg des Vorgangs zum Erstellen eines Patienten an und enthält die ID der neuen Ressource. Der zweite Eintrag gibt den Erfolg des Vorgangs zum Erstellen der Beobachtung an und enthält die ID der neuen Ressource.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
Ein Beispiel für eine Bundle-Datei ist im GitHub-Repository des Codebeispiels verfügbar.
Stellen Sie zum Ausführen eines Bundles eine POST-Anfrage und geben Sie die folgenden Informationen an:
- Name und Speicherort des übergeordneten Datasets und FHIR-Speichers
- Speicherort der Bundle-Datei in Cloud Storage
- Ein Zugriffstoken
Das folgende Beispiel zeigt eine POST
-Anfrage mit Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
Das folgende Beispiel-Bundle ist die Ausgabe der erfolgreichen Ausführung des obigen Beispiels. Der erste Eintrag gibt den Erfolg des Vorgangs zum Erstellen eines Patienten an und enthält die ID der neuen Ressource. Der zweite Eintrag gibt den Erfolg des Vorgangs zum Erstellen der Beobachtung an und enthält die ID der neuen Ressource.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }