Přehled vyhledávání ve službě Azure API for FHIR
Důležité
Rozhraní Azure API for FHIR bude vyřazeno 30. září 2026. Postupujte podle strategií migrace a do tohoto data přejděte na službu FHIR® služby Azure Health Data Services. Vzhledem k vyřazení rozhraní Azure API for FHIR nebudou nová nasazení od 1. dubna 2025 povolena. Služba FHIR služby Azure Health Data Services je vyvinutá verze rozhraní Azure API for FHIR, která zákazníkům umožňuje spravovat služby FHIR, DICOM a MedTech s integrací do jiných služeb Azure.
Specifikace FHIR (Fast Healthcare Interoperability Resources) definuje základy hledání prostředků FHIR®. Tento článek vás provede některými klíčovými aspekty vyhledávání prostředků v FHIR. Úplné podrobnosti o vyhledávání prostředků FHIR najdete ve specifikaci HL7 FHIR. V tomto článku uvádíme příklady syntaxe vyhledávání. Každé vyhledávání je proti vašemu serveru FHIR, který má obvykle adresu URL https://<FHIRSERVERNAME>.azurewebsites.net. V příkladech používáme zástupný symbol {{FHIR_URL}} pro tuto adresu URL.
Hledání FHIR může být v konkrétním typu prostředku, zadaném oddílu nebo všech prostředcích. Nejjednodušší způsob, jak provést vyhledávání v FHIR, je použít GET požadavek. Pokud například chcete vyžádat všechny pacienty v databázi, můžete použít následující požadavek.
GET {{FHIR_URL}}/Patient
Můžete také hledat pomocí POST, což je užitečné, pokud je řetězec dotazu dlouhý. Pokud chcete hledat pomocí POST, dají se parametry hledání odeslat jako text formuláře. To umožňuje delší a složitější řadu parametrů dotazu, které by mohly být obtížné zobrazit a pochopit v řetězci dotazu.
Pokud je žádost o vyhledávání úspěšná, obdržíte odpověď sady FHIR s typem searchset. Pokud hledání selže, najdete podrobnosti o chybě v nápovědě OperationOutcome , abyste pochopili, proč hledání selhalo.
V následujících částech se podíváme na různé aspekty vyhledávání. Jakmile si projdete tyto podrobnosti, projděte si naši stránku s ukázkami, která obsahuje příklady hledání, která můžete provést v rozhraní Azure API for FHIR.
Parametry vyhledávání
Vyhledávání jsou založená na různých atributech prostředku. Tyto atributy se nazývají parametry vyhledávání. Každý prostředek má sadu definovaných parametrů hledání. Aby bylo možné úspěšně vyhledávat, musí být parametr vyhledávání definován a indexován v databázi.
Každý parametr vyhledávání má definované datové typy. Následující tabulka popisuje podporu různých datových typů.
Upozorňující
V současné době dochází k problému při použití _sort rozhraní Azure API for FHIR s zřetězeným vyhledáváním. Další informace najdete v opensourcovém problému č. 2344. Tento problém bude vyřešen během vydání v prosinci 2021.
| Typ vyhledávacího parametru | Azure API for FHIR | Služba FHIR ve službě Azure Health Data Services | Komentář |
|---|---|---|---|
| Číslo | Ano | Yes | |
| datum | Ano | Yes | |
| string | Yes | Yes | |
| token | Ano | Yes | |
| reference | Ano | Yes | |
| složený | Částečná | Částečná | Seznam podporovaných složených typů je popsán dále v tomto článku. |
| množství. | Ano | Yes | |
| uri | Ano | Yes | |
| zvláštní | No | Ne |
Běžné parametry hledání
Existují běžné parametry hledání, které se vztahují na všechny prostředky. Najdete je v následujícím seznamu spolu s jejich podporou v rámci rozhraní Azure API for FHIR.
| Běžný parametr vyhledávání | Azure API for FHIR | Služba FHIR ve službě Azure Health Data Services | Komentář |
|---|---|---|---|
| _id | Ano | Yes | |
| _lastUpdated | Ano | Yes | |
| _značka | Ano | Yes | |
| _typ | Ano | Yes | |
| _bezpečnost | Ano | Yes | |
| _profil | Ano | Yes | |
| _má | Částečná | Ano | _has Podpora pro MVP v rozhraní Azure API for FHIR a verze operačního systému podporovaná službou Azure Cosmos DB. Další podrobnosti najdete v následující části řetězení. |
| _dotaz | No | Ne | |
| _filtr | No | Ne | |
| _seznam | No | Ne | |
| _Text | No | Ne | |
| _obsah | No | Ne |
Parametry specifické pro prostředky
S rozhraním Azure API for FHIR podporujeme téměř všechny parametry hledání specifické pro prostředky definované specifikací FHIR. Na následujících odkazech jsou k dispozici pouze parametry hledání, které nepodporujeme.
Aktuální podporu parametrů hledání můžete zobrazit také v příkazu FHIR Capability s následujícím požadavkem.
GET {{FHIR_URL}}/metadata
Pokud chcete zobrazit parametry hledání v příkazu capability, přejděte k CapabilityStatement.rest.resource.searchParam zobrazení parametrů hledání pro jednotlivé prostředky a CapabilityStatement.rest.searchParam vyhledejte parametry hledání pro všechny prostředky.
Poznámka:
Rozhraní Azure API for FHIR automaticky nevytvoří ani neindexuje žádné parametry hledání, které nejsou definovány specifikací FHIR. Poskytujeme ale podporu pro definování vlastních parametrů hledání.
Složené parametry hledání
Složené vyhledávání umožňuje vyhledávat podle párů hodnot. Pokud byste například hledali pozorování výšky, ve kterém byla osoba 60 palců, měli byste se ujistit, že jedna komponenta pozorování obsahovala kód výšky a hodnotu 60. Nechtěli byste získat pozorování, kde byla uložena hmotnost 60 a výška 48, i když by pozorování měl záznamy, které jsou kvalifikované pro hodnotu 60 a kód výšky, pouze v různých částech součástí.
S rozhraním Azure API for FHIR podporujeme následující párování typů parametrů vyhledávání.
- Referenční informace, token
- Token, Datum
- Token, Číslo, Číslo
- Token, Množství
- Token, Řetězec
- Token, Token
Další informace najdete ve složených parametrech hledání HL7.
Poznámka:
Složené parametry hledání nepodporují modifikátory podle specifikace FHIR.
Modifikátory a předpony
Modifikátory umožňují upravit parametr vyhledávání. Následující tabulka obsahuje přehled všech modifikátorů FHIR a jejich podpory v rozhraní Azure API for FHIR.
| Modifikátory | Azure API for FHIR | Služba FHIR ve službě Azure Health Data Services | Komentář |
|---|---|---|---|
| :nepřítomný | Ano | Yes | |
| :přesný | Ano | Yes | |
| :obsahuje | Ano | Yes | |
| :Text | Ano | Yes | |
| :type (odkaz) | Ano | Yes | |
| :ne | Ano | Yes | |
| :below (URI) | Ano | Yes | |
| :above (URI) | Ano | Yes | |
| :in (token) | No | Ne | |
| :below (token) | No | Ne | |
| :above (token) | No | Ne | |
| :not-in (token) | No | Ne |
Pro parametry hledání, které mají konkrétní pořadí (čísla, kalendářní data a množství), můžete použít předponu parametru, která vám pomůže najít shody. Rozhraní Azure API for FHIR podporuje všechny předpony.
Parametry výsledků hledání
Pro usnadnění správy vrácených prostředků existují parametry výsledků hledání, které můžete použít. Podrobnosti o tom, jak používat jednotlivé parametry výsledků hledání, najdete na webu HL7 .
| Parametry výsledků hledání | Azure API for FHIR | Služba FHIR ve službě Azure Health Data Services | Komentář |
|---|---|---|---|
| _elementy | Ano | Yes | |
| _počítat | Ano | Yes | _count je omezeno na 1 000 prostředků. Pokud je nastavená hodnota vyšší než 1000, vrátí se pouze 1000 a v sadě se vrátí upozornění. |
| _zahrnovat | Ano | Yes | Zahrnuté položky jsou omezeny na 100. _include v PaaS a OSS ve službě Azure Cosmos DB nezahrnuje podporu iterace (#2137). |
| _revinclude | Ano | Yes | Zahrnuté položky jsou omezeny na 100. _revinclude v PaaS a OSS ve službě Azure Cosmos DB nezahrnuje podporu iterace (#2137). Pro chybný požadavek č. 1319 je také nesprávný stavový kód. |
| _shrnutí | Ano | Yes | |
| _totální | Částečná | Částečná | _total=none and _total=accurate |
| _třídit | Částečná | Částečná | sort=_lastUpdated se podporuje v rozhraní Azure API for FHIR a službě FHIR. U databází Azure API for FHIR a OSS Azure Cosmos DB vytvořených po 20. dubnu 2021 se řazení podporuje podle jména, příjmení, narození a klinického data. |
| _obsahoval | No | Ne | |
| _containedType | No | Ne | |
| _partitura | No | Číslo |
Poznámka:
Ve výchozím nastavení _sort seřadí záznam ve vzestupném pořadí. Předponu '-' můžete použít k řazení sestupně. Kromě toho služba FHIR a rozhraní Azure API for FHIR umožňují řazení pouze na jednom poli najednou.
Ve výchozím nastavení je rozhraní Azure API for FHIR nastavené na lenientní zpracování. To znamená, že server ignoruje všechny neznámé nebo nepodporované parametry. Pokud chcete použít striktní zpracování, můžete použít záhlaví Prefer a nastavit handling=strict.
Zřetězený a zřetězený vyhledávání
Zřetězený vyhledávání umožňuje hledat pomocí vyhledávacího parametru u prostředku, na který odkazuje jiný prostředek. Pokud například chcete zjistit, kde je jméno pacienta Jane, použijte:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane.
Podobně můžete provést reverzní zřetězené vyhledávání. To umožňuje získat prostředky, u kterých zadáte kritéria pro jiné prostředky, které na ně odkazují. Další příklady zřetězených a obrácených zřetězených vyhledávání najdete na stránce s příklady hledání FHIR.
Poznámka:
V rozhraní Azure API for FHIR a opensourcovém prostředí zálohovaném službou Azure Cosmos DB platí omezení, kdy každý poddotaz vyžadovaný pro zřetězený a zřetězený hledání vrátí jenom 1 000 položek. Pokud se najde více než 1 000 položek, zobrazí se následující chybová zpráva: "Poddotazy ve zřetězené výrazy nemůžou vrátit více než 1000 výsledků, použijte další selektivní kritéria." Pokud chcete získat úspěšný dotaz, budete muset být konkrétnější v tom, co hledáte.
Stránkování
Jak jsme už zmínili, výsledky hledání jsou stránkovanou sadou. Ve výchozím nastavení vrátí hledání 10 výsledků na stránku, ale to lze zvýšit (nebo snížit) zadáním _count. V rámci sady bude odkaz na sebe, který obsahuje aktuální výsledek hledání. Pokud existují další shody, sada bude obsahovat další odkaz. Další odkaz můžete dál používat k získání dalších stránek výsledků. _count je omezena na 1 000 položek nebo méně.
Další odkaz v sadě obsahuje limit velikosti tokenu pokračování o velikosti 3 kB. Pomocí hlavičky x-ms-documentdb-responsecontinuationtokenlimitinkbmůžete upravit velikost tokenu pokračování mezi 1 kB až 3 kB.
Rozhraní Azure API for FHIR v současné době podporuje pouze další odkaz v balíčcích a nepodporuje první, poslední nebo předchozí odkazy.
Další kroky
Teď, když jste se seznámili se základy vyhledávání, najdete na stránce s ukázkami hledání podrobnosti o tom, jak hledat pomocí různých parametrů hledání, modifikátorů a dalších scénářů hledání FHIR.
Poznámka:
FHIR® je registrovaná ochranná známka HL7 a používá se s povolením HL7.