Teilen über

FHIR-REST-API-Funktionen für Azure API for FHIR

  • Artikel

In diesem Artikel werden einige der Nuancen der RESTful-Interaktionen von Azure API for FHIR behandelt.

Bedingtes Erstellen/Aktualisieren

Azure API for FHIR unterstützt das Erstellen, bedingte Erstellen, Aktualisieren und bedingte Updates 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

Azure API for FHIR 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 den HTTP-Statuscode 410 zurückgeben. Daher wird die Ressource bei der Suche nicht mehr gefunden. Darüber hinaus können Sie mit Azure API for FHIR 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 Azure API for FHIR 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 zum Löschen einer Ressource übergeben. Standardmäßig können Sie mit dem bedingten 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 in Azure API for FHIR 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 datensatz gefunden haben, den Sie wiederherstellen möchten, 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.

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 von Azure API for FHIR kennengelernt. Als Nächstes erfahren Sie mehr über die wichtigsten Aspekte beim Durchsuchen von Ressourcen in FHIR.

Übersicht über die Suche in Azure API für FHIR

FHIR ist eine eingetragene Marke von HL7 und wird mit Genehmigung von HL7 verwendet.