FHIR-REST-API-Funktionen für den Azure Health Data Services-FHIR-Dienst
In diesem Artikel werden einige der Nuancen der RESTful-Interaktionen des Azure Health Data Services FHIR-Diensts (hier als FHIR-Dienst bezeichnet) behandelt.
Bedingtes Erstellen/Aktualisieren
Der FHIR-Dienst unterstützt erstellung, bedingte Erstellung, Aktualisierung und bedingte Aktualisierung gemäß der FHIR-Spezifikation. Ein nützlicher Header in diesen Szenarien ist der If-Match-Header . Der If-Match Header wird verwendet und überprüft die version, die aktualisiert wird, bevor das Update durchgeführt wird. Wenn der ETag nicht mit dem erwarteten ETagübereinstimmt, wird die Fehlermeldung 412 Vorbedingung fehlgeschlagen erzeugt.
Löschen und bedingtes Löschen
Der FHIR-Dienst bietet zwei Löschtypen. Es gibt Delete, die auch als "Hartes + vorläufiges Löschen" und "Bedingtes Löschen" bezeichnet wird.
Löschen (Hartes + vorläufiges Löschen)
Das durch die FHIR-Spezifikation definierte Löschen erfordert, dass nach dem Löschen einer Ressource nachfolgende, nicht versionsspezifische Lesevorgänge einer Ressource einen 410-HTTP-status-Code zurückgeben. Daher wird die Ressource bei der Suche nicht mehr gefunden. Darüber hinaus können Sie mit dem FHIR-Dienst die Ressource vollständig löschen (einschließlich des gesamten Verlaufs). Um die Ressource vollständig zu löschen, können Sie parametereinstellungen hardDelete an true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true)übergeben. Wenn Sie diesen Parameter nicht übergeben oder auf false festlegen hardDelete , sind die historischen Versionen der Ressource weiterhin verfügbar.
Hinweis
Wenn Sie nur den Verlauf löschen möchten, unterstützt der FHIR-Dienst einen benutzerdefinierten Vorgang namens $purge-history. Mit diesem Vorgang können Sie den Verlauf einer Ressource löschen.
Bedingtes Löschen
Mit bedingtem Löschen können Sie Suchkriterien übergeben, um eine Ressource zu löschen. Standardmäßig können Sie mit bedingtem Löschen jeweils ein Element löschen. Sie können auch den _count Parameter angeben, um bis zu 100 Elemente gleichzeitig zu löschen. Nachfolgend finden Sie einige Beispiele für die Verwendung des bedingten Löschens.
Um ein einzelnes Element mithilfe des bedingten Löschens zu löschen, müssen Sie Suchkriterien angeben, die ein einzelnes Element zurückgeben.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
Sie können die gleiche Suche ausführen, aber einschließen hardDelete=true , um auch den gesamten Verlauf zu löschen.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Um mehrere Ressourcen zu löschen, schließen Sie den Parameter ein _count=100 . Dieser Parameter löscht bis zu 100 Ressourcen, die den Suchkriterien entsprechen.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Wiederherstellung gelöschter Dateien
Wenn Sie den Parameter für das harte Löschen nicht verwenden, sollten die Datensätze im FHIR-Dienst weiterhin vorhanden sein. Die Datensätze können gefunden werden, indem Sie eine Verlaufssuche für die Ressource durchführen und nach der letzten Version mit Daten suchen.
Wenn die ID der gelöschten Ressource bekannt ist, verwenden Sie das folgende URL-Muster:
<FHIR_URL>/<resource-type>/<resource-id>/_history
Beispiel: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history
Wenn die ID der Ressource nicht bekannt ist, führen Sie eine Verlaufssuche für den gesamten Ressourcentyp durch:
<FHIR_URL>/<resource-type>/_history
Beispiel: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history
Nachdem Sie den wiederherzustellenden Datensatz gefunden haben, verwenden Sie den PUT Vorgang, um die Ressource mit derselben ID neu zu erstellen, oder verwenden Sie den POST Vorgang, um eine neue Ressource mit denselben Informationen zu erstellen.
Hinweis
Es gibt keinen zeitbasierten Ablauf für Verlaufs-/Vorläufiges Löschen von Daten. Die einzige Möglichkeit zum Entfernen von Verlaufs-/vorläufig gelöschten Daten ist ein harter Löschvorgang oder der Vorgang zum Löschen des Verlaufs.
Batch- und Transaktionspakete
In FHIR können Bündel als Container mit mehreren Ressourcen betrachtet werden. Batch- und Transaktionspakete ermöglichen es Benutzern, eine Reihe von Aktionen zu übermitteln, die auf einem Server in einer einzelnen HTTP-Anforderung/-Antwort ausgeführt werden sollen. Die Aktionen können unabhängig als "Batch" oder als einzelne atomare "Transaktion" ausgeführt werden, bei der der gesamte Satz von Änderungen erfolgreich ist oder als einzelne Entität fehlschlägt. Aktionen für mehrere Ressourcen desselben oder unterschiedlichen Typs können übermittelt werden, z. B. Erstellen, Aktualisieren oder Löschen. Weitere Informationen finden Sie unter FHIR-Bündel.
Eine Batch- oder Transaktionspaketinteraktion mit dem FHIR-Dienst wird mit dem HTTP POST-Befehl an der Basis-URL ausgeführt.
POST {{fhir_url}}
{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "patient-1",
"name": [
{
"given": ["Alice"],
"family": "Smith"
}
],
"gender": "female",
"birthDate": "1990-05-15"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Patient",
"id": "patient-2",
"name": [
{
"given": ["Bob"],
"family": "Johnson"
}
],
"gender": "male",
"birthDate": "1985-08-23"
},
"request": {
"method": "POST",
"url": "Patient"
}
}
}
]
}
Im Fall eines Batches wird jeder Eintrag als individuelle Interaktion oder Vorgang behandelt. Im Fall eines Transaktionspakets sind alle Interaktionen oder Vorgänge entweder erfolgreich oder schlagen zusammen fehl. Für einen Batch oder ein erfolgreiches Transaktionspaket enthält die Antwort einen Eintrag für jeden Eintrag in der Anforderung. Bei fehlgeschlagenen Transaktionspaketen gibt der FHIR-Dienst einzelne OperationOutcome zurück.
Hinweis
Bei Batchbündeln sollte es keine Interdependenz zwischen verschiedenen Einträgen im FHIR-Bundle geben. Der Erfolg oder Fehler eines Eintrags sollte sich nicht auf den Erfolg oder Fehler eines anderen Eintrags auswirken.
Parallelverarbeitung von Batchpaketen in der öffentlichen Vorschau
Derzeit werden Batch- und Transaktionspakete seriell im FHIR-Dienst ausgeführt. Um Leistung und Durchsatz zu verbessern, ermöglichen wir die parallele Verarbeitung von Batchpaketen in der öffentlichen Vorschau.
So verwenden Sie die Funktion der parallelen Batchbündelverarbeitung:
- Legen Sie den Headerwert "x-bundle-processing-logic" auf "parallel" fest.
- Stellen Sie sicher, dass keine überlappende Ressourcen-ID vorhanden ist, die für DELETE-, POST-, PUT- oder PATCH-Vorgänge im selben Paket ausgeführt wird.
Wichtig
Die parallele Bündelverarbeitung befindet sich derzeit in der öffentlichen Vorschauphase. Vorschau-APIs und -SDKs werden ohne Vereinbarung zum Servicelevel bereitgestellt. Es wird empfohlen, diese nicht für Produktionsworkloads zu verwenden. Einige Features werden möglicherweise nicht unterstützt oder bieten nur eingeschränkte Funktionalität. Weitere Informationen finden Sie unter Ergänzende Nutzungsbedingungen für Microsoft Azure Previews.
Patch und bedingter Patch
Patch ist ein wertvoller RESTful-Vorgang, wenn Sie nur einen Teil der FHIR-Ressource aktualisieren müssen. Mithilfe von Patch können Sie die Elemente angeben, die Sie in der Ressource aktualisieren möchten, ohne den gesamten Datensatz aktualisieren zu müssen. FHIR definiert drei Möglichkeiten zum Patchen von Ressourcen: JSON-Patch, XML-Patch und FHIRPath-Patch. Der FHIR-Dienst unterstützt sowohl JSON-Patch als auch FHIRPath-Patch zusammen mit bedingtem JSON-Patch und bedingtem FHIRPath-Patch (wodurch Sie eine Ressource basierend auf einem Suchkriterium anstelle einer Ressourcen-ID patchen können). Informationen zu einigen Beispielen finden Sie in der FHIRPath-Patch-REST-Beispieldatei und in der JSON-Patch-REST-Datei für jeden Ansatz. Weitere Informationen finden Sie in der HL7-Dokumentation für Patchvorgänge mit FHIR.
Hinweis
Wenn Sie für STU3 verwenden PATCH und ein Verlaufspaket Bundle.entry.request.method anfordern, wird die gepatchte Ressource zugeordnet PUT. Dies liegt daran, dass STU3 keine Definition für das PATCH Verb im HTTPVerb-Wertsatz enthält.
Patchen mit FHIRPath-Patch
Diese Patchmethode ist die leistungsstärkste, da sie FHIRPath für die Auswahl des Zielelements nutzt. Ein häufiges Szenario ist die Verwendung von FHIRPath Patch, um ein Element in einer Liste zu aktualisieren, ohne die Reihenfolge der Liste zu kennen. Wenn Sie beispielsweise die Telekommunikationsinformationen eines Patienten löschen möchten, ohne den Index zu kennen, können Sie das folgende Beispiel verwenden.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Inhaltstyp: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{
"name": "type",
"valueCode": "delete"
},
{
"name": "path",
"valueString": "Patient.telecom.where(use = 'home')"
}
]
}
]
}
Für alle FHIRPath-Patchvorgänge muss der application/fhir+json Content-Type-Header festgelegt sein. FHIRPatch Patch unterstützt Add-, Insert-, Delete-, Remove- und Move-Vorgänge. FHIRPatch-Patchvorgänge können auch einfach in Bundles integriert werden. Weitere Beispiele findest du in der FHIRPath-Patch-REST-Beispieldatei.
Patchen mit JSON-Patch
Der JSON-Patch im FHIR-Dienst entspricht der häufig verwendeten Spezifikation, die von der Internet Engineering Task Force definiert wurde. Das Nutzlastformat verwendet keine FHIR-Ressourcen und verwendet stattdessen ein JSON-Dokument, das JSON-Pointers für die Elementauswahl nutzt. DER JSON-Patch ist kompakter und verfügt über einen Testvorgang, mit dem Sie überprüfen können, ob eine Bedingung erfüllt ist, bevor Sie den Patch ausführen. Wenn Sie beispielsweise einen Patienten nur dann als verstorben festlegen möchten, wenn er noch nicht als verstorben gekennzeichnet ist, können Sie das folgende Beispiel verwenden.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Inhaltstyp: application/json-patch+json
[
{
"op": "test",
"path": "/deceasedBoolean",
"value": false
},
{
"op": "replace",
"path": "/deceasedBoolean",
"value": true
}
]
Für alle JSON-Patchvorgänge muss der application/json-patch+json Content-Type-Header festgelegt sein. JSON Patch unterstützt Vorgänge zum Hinzufügen, Entfernen, Ersetzen, Kopieren, Verschieben und Testen. Weitere Beispiele findest du in der JSON-Patch-REST-Beispieldatei.
JSON-Patch in Bundles
Standardmäßig wird JSON-Patch in Bundle-Ressourcen nicht unterstützt. Dies liegt daran, dass ein Bundle nur FHIR-Ressourcen unterstützt und die JSON-Patchnutzlast keine FHIR-Ressource ist. Um dies zu umgehen, verwenden wir Binäre Ressourcen mit einem Inhaltstyp von "application/json-patch+json" und der base64-Codierung der JSON-Nutzlast in einem Bundle. Informationen zu dieser Problemumgehung finden Sie in diesem Thema unter FHIR Chat Zulip.
Im folgenden Beispiel möchten wir das Geschlecht des Patienten in weiblich ändern. Wir haben den JSON-Patch [{"op":"replace","path":"/gender","value":"female"}] verwendet und in base64 codiert.
POST https://{FHIR-SERVICE-HOST-NAME}/
Content-Type: application/json
{
"resourceType": "Bundle",
"id": "bundle-batch",
"type": "batch",
"entry": [
{
"fullUrl": "Patient/{PatientID}",
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/{PatientID}"
}
}
]
}
Nächste Schritte
In diesem Artikel haben Sie einige der REST-Funktionen des FHIR-Diensts kennengelernt. Als Nächstes erfahren Sie mehr über die wichtigsten Aspekte bei der Suche nach Ressourcen im FHIR-Dienst.
FHIR ist eine eingetragene Marke von HL7 und wird mit Genehmigung von HL7 verwendet.