FHIR REST API-képességek az Azure Health Data Services FHIR szolgáltatáshoz

  • Cikk

Ebben a cikkben az Azure Health Data Services FHIR szolgáltatás (ezennel FHIR szolgáltatás) RESTful interakcióinak néhány árnyalatát ismertetjük.

Feltételes létrehozás/frissítés

Az FHIR szolgáltatás támogatja a létrehozást, a feltételes létrehozást, a frissítést és a feltételes frissítést az FHIR-specifikációban meghatározottak szerint. Ezekben a forgatókönyvekben az egyik hasznos fejléc az If-Match fejléc. A If-Match rendszer a fejlécet használja, és a frissítés előtt ellenőrzi a frissített verziót. Ha a ETag nem egyezik meg a várt ETagértékkel, akkor a 412-s előfeltétel meghiúsult hibaüzenetet fogja eredményezni.

Törlés és feltételes törlés

Az FHIR szolgáltatás két törlési típust kínál. Itt található a Törlés, amely a Hard + Soft Delete és a Feltételes törlés néven is ismert.

Törlés (Kemény + Helyreállítható törlés)

Az FHIR-specifikáció által definiált törléshez az erőforrás törlése után az erőforrás későbbi, nem verzióspecifikus olvasásai 410 HTTP-állapotkódot ad vissza. Ezért az erőforrás már nem található kereséssel. Emellett az FHIR szolgáltatás lehetővé teszi az erőforrás teljes törlését (az összes előzményt is beleértve). Az erőforrás teljes törléséhez átadhat egy paraméterbeállítást hardDelete a true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true)értéknek. Ha nem adja meg ezt a paramétert, vagy hamis értékre állítja hardDelete , az erőforrás korábbi verziói továbbra is elérhetők lesznek.

Megjegyzés

Ha csak az előzményeket szeretné törölni, az FHIR szolgáltatás támogatja a nevű $purge-historyegyéni műveletet. Ez a művelet lehetővé teszi az erőforrások előzményeinek törlését.

Feltételes törlés

A feltételes törlés lehetővé teszi, hogy keresési feltételeket adjon meg egy erőforrás törléséhez. Alapértelmezés szerint a feltételes törlés lehetővé teszi, hogy egyszerre egy elemet töröljön. Megadhatja azt a _count paramétert is, amely egyszerre legfeljebb 100 elemet töröl. Az alábbiakban néhány példa látható a feltételes törlés használatára.

Ha egyetlen elemet szeretne törölni a feltételes törléssel, meg kell adnia egy keresési feltételt, amely egyetlen elemet ad vissza.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704

Ugyanezt a keresést végezheti el, de belefoglalhatja hardDelete=true az összes előzmény törlését is.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true

Több erőforrás törléséhez adja meg _count=100 a paramétert. Ez a paraméter legfeljebb 100 olyan erőforrást töröl, amely megfelel a keresési feltételeknek.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100

Törölt fájlok helyreállítása

Ha nem használja a kemény törlés paramétert, akkor az FHIR szolgáltatásban lévő rekord(ok)nak továbbra is létezniük kell. A rekord(ok) az erőforrás előzménykeresésével és az adatokkal rendelkező utolsó verzió megkeresésével találhatók meg.

Ha a törölt erőforrás azonosítója ismert, használja a következő URL-mintát:

<FHIR_URL>/<resource-type>/<resource-id>/_history

Például: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history

Ha az erőforrás azonosítója nem ismert, keressen előzménykeresést a teljes erőforrástípuson:

<FHIR_URL>/<resource-type>/_history

Például: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history

Miután megtalálta a visszaállítani kívánt rekordot, a PUT művelettel hozza létre újra az erőforrást ugyanazzal az azonosítóval, vagy a művelettel POST hozzon létre egy új erőforrást ugyanazokkal az információkkal.

Megjegyzés

Az előzmény-/helyreállítható törlési adatokhoz nincs időalapú lejárat. Az előzmények/helyreállítható módon törölt adatok eltávolításának egyetlen módja a végleges törlés vagy a végleges törlési előzményművelet.

Kötegek és tranzakciós kötegek

Az FHIR-ben a csomagok több erőforrást tartalmazó tárolónak tekinthetők. A kötegek és a tranzakciós kötegek lehetővé teszik a felhasználók számára, hogy egyetlen HTTP-kérésben/-válaszban küldjenek el egy kiszolgálón végrehajtandó műveleteket. A műveletek egymástól függetlenül végrehajthatók "kötegként", vagy egyetlen atomi "tranzakcióként", ahol a módosítások teljes készlete sikeres vagy sikertelen egyetlen entitásként. Több, azonos vagy különböző típusú erőforráson végrehajtható műveletek, például létrehozás, frissítés vagy törlés. További információ: FHIR-csomagok.

Az FHIR szolgáltatással folytatott köteg- vagy tranzakciócsomag-interakció a HTTP POST paranccsal történik az alap URL-címen.

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" 
      } 
    } 
   } 
  ] 
}

Köteg esetén a rendszer minden bejegyzést egyéni interakcióként vagy műveletként kezel. Tranzakciós csomag esetén az összes interakció vagy művelet együtt sikeres vagy sikertelen. Köteg vagy sikeres tranzakciós köteg esetén a válasz egy bejegyzést tartalmaz a kérelem minden egyes bejegyzéséhez. Sikertelen tranzakciós köteg esetén az FHIR szolgáltatás egyetlen OperationOutcome értéket ad vissza.

Megjegyzés

Kötegcsomagok esetén az FHIR-köteg különböző bejegyzései között nem lehetnek egymástól függő eltérések. Az egyik bejegyzés sikeressége vagy sikertelensége nem befolyásolhatja egy másik bejegyzés sikerességét vagy sikertelenségét.

Batch-köteg párhuzamos feldolgozása nyilvános előzetes verzióban

A Batch és a tranzakciós kötegek végrehajtása jelenleg sorosan történik az FHIR szolgáltatásban. A teljesítmény és az átviteli sebesség javítása érdekében nyilvános előzetes verzióban engedélyezzük a kötegelt kötegek párhuzamos feldolgozását.
A párhuzamos kötegelt kötegfeldolgozási képesség használata:

  • Állítsa az "x-bundle-processing-logic" fejléc értékét "parallel" értékre.
  • Győződjön meg arról, hogy nincs olyan átfedésben lévő erőforrás-azonosító, amely a DELETE, POST, PUT vagy PATCH műveleteken fut ugyanabban a csomagban.

Fontos

A köteg párhuzamos feldolgozása jelenleg nyilvános előzetes verzióban érhető el. Az előzetes verziójú API-k és SDK-k szolgáltatói szerződés nélkül érhetők el. Azt javasoljuk, hogy ne használja őket éles számítási feladatokhoz. Előfordulhat, hogy egyes funkciók nem támogatottak, vagy korlátozott képességekkel rendelkeznek. További információ: Kiegészítő használati feltételek a Microsoft Azure előzetes verziójához

Javítás és feltételes javítás

A javítás értékes RESTful művelet, ha az FHIR-erőforrásnak csak egy részét kell frissítenie. A patch használatával a teljes rekord frissítése nélkül adhatja meg az erőforrásban frissíteni kívánt elemeket. Az FHIR az erőforrások javításának három módját határozza meg: JSON-javítás, XML-javítás és FHIRPath-javítás. Az FHIR szolgáltatás támogatja a JSON-javítást és az FHIRPath-javítást, valamint a feltételes JSON-javítást és a feltételes FHIRPath-javítást (amely lehetővé teszi, hogy erőforrás-azonosító helyett keresési feltételek alapján javítson egy erőforrást). Néhány példa megtekintéséhez tekintse meg az FHIRPath patch REST-fájlt és a JSON Patch REST-fájlt minden megközelítéshez. További részletekért olvassa el a HL7 dokumentációját az FHIR-vel végzett javítási műveletekhez.

Megjegyzés

Ha a STU3-at használja PATCH , és előzménycsomagot kér, a javított erőforrás Bundle.entry.request.method a következőre PUTlesz leképezve: . Ennek az az oka, hogy a STU3 nem tartalmaz definíciót a PATCHHTTPVerb-értékkészletben lévő parancshoz.

Javítás FHIRPath-javítással

Ez a javítási módszer a leghatékonyabb, mivel az FHIRPath használatával választja ki a megcélozandó elemet. Az egyik gyakori forgatókönyv az FHIRPath-javítás használata a lista elemeinek frissítéséhez a lista sorrendjének ismerete nélkül. Ha például az index ismerete nélkül szeretné törölni a beteg otthoni távközlési adatait, használja az alábbi példát.

JAVÍTÁS http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tartalomtípus: application/fhir+json

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "operation",
            "part": [
                {
                    "name": "type",
                    "valueCode": "delete"
                },
                {
                    "name": "path",
                    "valueString": "Patient.telecom.where(use = 'home')"
                }
            ]
        }
    ]
}

Minden FHIRPath-javítási műveletnek rendelkeznie kell a application/fhir+json Content-Type fejléckészlettel. Az FHIRPatch Patch támogatja a hozzáadási, beszúrási, törlési, eltávolítási és áthelyezési műveleteket. A FHIRPatch Patch-műveletek könnyen integrálhatók a Bundles szolgáltatásba is. További példákért tekintse meg a minta FHIRPath Patch REST-fájlt.

Javítás JSON-javítással

A JSON Patch az FHIR szolgáltatásban megfelel az Internet Engineering Task Force által meghatározott jól használt specifikációnak. A hasznos adatformátum nem használ FHIR-erőforrásokat, hanem JSON-dokumentumot használ, amely JSON-Pointers használ elemkijelöléshez. A JSON-javítás kompaktabb, és olyan tesztművelettel rendelkezik, amely lehetővé teszi, hogy a javítás elvégzése előtt ellenőrizze, hogy egy feltétel teljesül-e. Ha például egy beteget csak akkor szeretne elhunytként beállítani, ha még nincs megjelölve elhunytként, használja az alábbi példát.

JAVÍTÁS http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tartalomtípus: application/json-patch+json

[
	{
		"op": "test",
		"path": "/deceasedBoolean",
		"value": false
	},
	{
		"op": "replace",
		"path": "/deceasedBoolean",
		"value": true
	}
]

Minden JSON-javítási műveletnek rendelkeznie kell a application/json-patch+json Content-Type fejléckészlettel. A JSON Patch támogatja a hozzáadási, eltávolítási, csere-, másolási, áthelyezési és tesztelési műveleteket. További példákért tekintse meg a JSON Patch REST-fájlt.

JSON-javítás kötegekben

Alapértelmezés szerint a JSON-javítás nem támogatott a Kötegerőforrásokban. Ennek az az oka, hogy a csomag csak az FHIR-erőforrásokat támogatja, és a JSON Patch hasznos adatai nem FHIR-erőforrások. Ennek megkerüléséhez bináris erőforrásokat használunk a Content-Type ( "application/json-patch+json" Tartalomtípus) és a JSON hasznos adat base64 kódolásával egy csomagon belül. A kerülő megoldással kapcsolatos információkért tekintse meg ezt a témakört az FHIR-csevegési zulipben.

Az alábbi példában a páciens nemét szeretnénk nőire módosítani. Felvettük a JSON-javítást [{"op":"replace","path":"/gender","value":"female"}] , és base64-be kódoltuk.

POST https://{FHIR-SERVICE-HOST-NAME}/
Tartalomtípus: 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}"
			}
		}
	]
}

Következő lépések

Ebben a cikkben megismerkedett az FHIR szolgáltatás REST-képességeivel. Ezután többet is megtudhat az FHIR szolgáltatás erőforrásainak keresésének fő szempontjairól.

Az FHIR-keresés áttekintése

(FHIR®) a HL7 bejegyzett védjegye, és a HL7 engedélyével használják.