Omówienie wyszukiwania FHIR w Azure Health Data Services

Specyfikacja Fast Healthcare Interoperability Resources (FHIR®) definiuje interfejs API do wykonywania zapytań dotyczących zasobów w bazie danych serwera FHIR. W tym artykule przedstawiono kluczowe aspekty wyszukiwania FHIR w Azure Health Data Services, w tym parametry wyszukiwania, modyfikatory, stronicowanie i wyszukiwania łańcuchowe. Aby uzyskać pełne informacje na temat interfejsu API wyszukiwania standardu FHIR, zapoznaj się z dokumentacją HL7 dotyczącą FHIR Search.

W całym artykule symbol zastępczy {{FHIR_URL}} oznacza bazowy adres URL usługi FHIR w przykładowych wywołaniach interfejsu API pokazujących składnię wyszukiwania FHIR. Jeśli usługa FHIR znajduje się w Azure Health Data Services, ten adres URL to https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.

Wyszukiwanie FHIR można wykonać względem określonego typu zasobu, określonego przedziału lub wszystkich zasobów w bazie danych serwera FHIR. Najprostszym sposobem wykonywania wyszukiwania w FHIR jest użycie żądania GET. Jeśli na przykład chcesz ściągnąć wszystkie Patient zasoby w bazie danych, użyj następującego żądania.

GET {{FHIR_URL}}/Patient

Możesz również wyszukać za pomocą polecenia POST. Aby wyszukać przy użyciu polecenia POST, uwzględnij parametry wyszukiwania w treści żądania. Ta metoda ułatwia wysyłanie zapytań z dłuższymi, bardziej złożonymi seriami parametrów.

Używając POST lub GET, jeśli żądanie wyszukiwania zakończy się pomyślnie, otrzymasz pakiet FHIR searchset zawierający instancje zasobów zwrócone przez wyszukiwanie. Jeśli wyszukiwanie zakończy się niepowodzeniem, OperationOutcome odpowiedź zawiera szczegóły błędu.

W poniższych sekcjach przedstawiono różne aspekty wykonywania zapytań dotyczących zasobów w środowisku FHIR. Po zakończeniu przeglądania tych tematów zobacz stronę przykładów wyszukiwania FHIR, która zawiera przykłady różnych metod wyszukiwania FHIR.

Parametry wyszukiwania

Podczas wyszukiwania w standardzie FHIR należy wyszukać zasoby zgodne z określonymi kryteriami w bazie danych. Interfejs API FHIR określa bogaty zestaw parametrów wyszukiwania dla dostrajania kryteriów wyszukiwania. Każdy zasób w standardzie FHIR zawiera informacje jako zestaw elementów, a parametry wyszukiwania działają w celu wykonywania zapytań dotyczących informacji w tych elementach.

Jeśli parametry wyszukiwania pozytywnie pasują do wartości elementów zasobu, serwer FHIR zwraca pakiet pasujących zasobów.

Dla każdego parametru wyszukiwania specyfikacja FHIR definiuje typ danych , którego można użyć. W poniższej tabeli przedstawiono obsługę usługi FHIR dla różnych typów danych.

Typ parametru wyszukiwania Usługa FHIR w usługach Azure Health Data Services Interfejs API platformy Azure dla standardu FHIR Komentarz
Liczba Tak Tak
data Tak Tak
ciąg Tak Tak
kod przedpłaty Tak Tak
odwołanie Tak Tak
kompozytowy Częściowe Częściowe Lista obsługiwanych typów złożonych znajduje się poniżej w tym artykule.
ilość Tak Tak
URI Tak Tak
specjalny Nie Nie

Typowe parametry wyszukiwania

Typowe parametry wyszukiwania mają zastosowanie do wszystkich zasobów w środowisku FHIR. W poniższej tabeli wymieniono te parametry wraz z ich obsługą w usłudze FHIR.

Typowy parametr wyszukiwania Usługa FHIR w usługach Azure Health Data Services Interfejs API platformy Azure dla standardu FHIR Komentarz
_id Tak Tak
_lastUpdated Tak Tak
_tag Tak Tak
_type Tak Tak
_security Tak Tak
_profile Tak Tak
_has Tak Tak
_query Nie Nie
_filter Nie Nie
_list Nie Nie
_text Nie Nie
_content Nie Nie

Parametry specyficzne dla zasobu

Usługa FHIR w usługach Azure Health Data Services obsługuje prawie wszystkie parametry wyszukiwania specyficzne dla zasobów zdefiniowane w specyfikacji FHIR. Poniższe linki zawierają listę parametrów wyszukiwania, które nie są obsługiwane:

Możesz również sprawdzić aktualnie obsługiwane parametry wyszukiwania w instrukcji możliwości FHIR, za pomocą następującego żądania:

GET {{FHIR_URL}}/metadata

Aby wyświetlić obsługiwane parametry wyszukiwania w oświadczeniu o możliwościach, przejdź do CapabilityStatement.rest.resource.searchParam, aby wyświetlić parametry wyszukiwania specyficzne dla zasobu, oraz do CapabilityStatement.rest.searchParam, aby wyświetlić parametry wyszukiwania mające zastosowanie do wszystkich zasobów.

Uwaga

Usługa FHIR w Azure Health Data Services nie indeksuje automatycznie parametrów wyszukiwania, które nie są zdefiniowane w podstawowej specyfikacji FHIR. Usługa FHIR obsługuje niestandardowe parametry wyszukiwania.

Parametry wyszukiwania złożonego

Wyszukiwania złożone w FHIR traktują pary elementów jako pojedynczą jednostkę. Na przykład podczas wyszukiwania obserwacji, w których wysokość pacjenta wynosi ponad 60 cali, kod wysokości i wartość muszą pochodzić z tej samej obserwacji. Bez wyszukiwania złożonego obserwacja z kodem wysokości i wartości długości ramienia powyżej 60 cali może być również zgodna. Parametry wyszukiwania złożonego unikają tego problemu, wymagając, aby obie wartości w wstępnie zdefiniowanej parze elementów spełniały kryteria.

Usługa FHIR w usługach Azure Health Data Services obsługuje następujące pary typów parametrów wyszukiwania na potrzeby wyszukiwania złożonego.

  • Odniesienie, token
  • Token, dane
  • Token, Liczba, Liczba
  • Token, Ilość
  • Token, ciąg
  • Żeton, Żeton

Aby uzyskać więcej informacji, zobacz dokumentację parametrów wyszukiwania złożonego HL7.

Uwaga

Parametry wyszukiwania złożonego nie obsługują modyfikatorów zgodnie ze specyfikacją FHIR.

Modyfikatory i prefiksy parametrów wyszukiwania FHIR

Modyfikatory umożliwiają zakwalifikowanie parametrów wyszukiwania z dodatkowymi warunkami. W poniższej tabeli przedstawiono modyfikatory FHIR i ich obsługę w usłudze FHIR.

Modyfikatory Usługa FHIR w usługach Azure Health Data Services Interfejs API platformy Azure dla standardu FHIR Komentarz
:missing Tak Tak
:exact Tak Tak
:contains Tak Tak
:text Tak Tak
:type (odwołanie) Tak Tak
:not Tak Tak
:below (uri) Tak Tak
:above (URI) Tak Tak
:in (token) Nie Nie
:below (token) Nie Nie
:above (token) Nie Nie
:not-in (token) Nie Nie
:identifier Nie Nie

W przypadku parametrów wyszukiwania, które mają określoną kolejność, takie jak liczby, daty i ilości, użyj prefiksu przed wartością parametru, aby uściślić kryteria wyszukiwania. Na przykład Patient?_lastUpdated=gt2022-08-01 używa prefiksu gt , aby oznaczać wartość większą niż. Usługa FHIR w usługach Azure Health Data Services obsługuje wszystkie prefiksy zdefiniowane w standardzie FHIR.

rhia

Parametry wyników wyszukiwania FHIR

FHIR określa zestaw parametrów wyników wyszukiwania, aby ułatwić zarządzanie informacjami zwróconymi z wyszukiwania. Aby uzyskać szczegółowe informacje na temat używania parametrów wyników wyszukiwania w standardzie FHIR, zapoznaj się z witryną internetową HL7 . W poniższej tabeli przedstawiono parametry wyników wyszukiwania FHIR i ich obsługę w usłudze FHIR.

Parametry wyników wyszukiwania Usługa FHIR w usługach Azure Health Data Services Interfejs API platformy Azure dla standardu FHIR Komentarz
_elements Tak Tak
_count Tak Tak _count ma limit 1 000 zasobów. Jeśli ustawisz ją wyższą niż 1000, usługa zwróci tylko 1000 zasobów i zawiera ostrzeżenie w pakiecie.
_include Tak Tak _include w usługach PaaS i OSS w usłudze Azure Cosmos DB nie jest obsługiwane :iterate(#2137).
_revinclude Tak Tak _revinclude w usługach PaaS i OSS w usłudze Azure Cosmos DB nie jest obsługiwane :iterate(#2137). Istnieje również nieprawidłowy kod stanu nieprawidłowego żądania: #1319.
_summary Tak Tak
_total Częściowe Częściowe _total=none i _total=accurate
_sort Częściowe Częściowe sort=_lastUpdated jest obsługiwany w usłudze FHIR. W przypadku usług FHIR i serwerów OSS SQL DB FHIR obsługiwane jest sortowanie według ciągów i pól dateTime. W przypadku baz danych usługi Azure API for FHIR i OSS usługi Azure Cosmos DB utworzonych po 20 kwietnia 2021 r. sortowanie jest obsługiwane na imię, nazwisko, data urodzenia i data kliniczna.
_contained Nie Nie
_containedType Nie Nie
_score Nie Nie
_not-referenced Tak Nie _not-referenced=*:* aby wyszukać zasoby, do których nie odwołują się inne zasoby. Na przykład /Patient?_not-referenced=*:* służy do wyszukiwania zasobów pacjenta, do których nie odwołują się inne zasoby. /Patient?_not-referenced=Encounter:subject służy do wyszukiwania zasobów typu Patient, których zasoby Encounter nie wymieniają jako podmiotu. Lista może być również używana dla wielu pól referencyjnych; na przykład za pomocą /Patient/$bulk-delete?_not-referenced=Encounter:subject&_not-referenced=DiagnosticReport:subject można wyszukiwać zasoby Patient, do których nie odwołują się zasoby Encounter i DiagnosticReport.

Uwaga

  1. Domyślnie _sort rozmieszcza rekordy w kolejności rosnącej. Można również użyć prefiksu - do sortowania w kolejności malejącej. Usługa FHIR umożliwia sortowanie tylko na jednym polu jednocześnie.
  2. Usługa FHIR obsługuje wyszukiwanie symboli wieloznacznych za pomocą parametru _revinclude . Dodanie parametru zapytania . do zapytania _revinclude powoduje, że usługa FHIR odwołuje się do wszystkich zasobów skojarzonych z zasobem źródłowym.

Domyślnie usługa FHIR w usługach Azure Health Data Services jest ustawiona na łagodną obsługę. To ustawienie oznacza, że serwer ignoruje wszystkie nieznane lub nieobsługiwane parametry. Jeśli chcesz użyć ścisłej obsługi, dołącz nagłówek Prefer i ustaw handling=strict.

wyszukiwanie _include i _revinclude

Usługa FHIR obsługuje zapytania wyszukiwania używające parametrów _include i _revinclude. Te parametry umożliwiają pobieranie zasobów referencyjnych w wynikach wyszukiwania.

_include Parametr wyszukiwania umożliwia pobieranie określonego zasobu FHIR i innych zasobów FHIR, do których się odwołuje. W przypadku użycia w zapytaniu _include parametr zwraca określony zasób i zasoby , do których się odwołuje. Parametr wyszukiwania działa odwrotnie, umożliwiając pobieranie zasobu wraz z innymi zasobami odwołującymi się do niego, zapewniając sposób wyszukiwania zasobów na _revincludepodstawie ich relacji z innymi zasobami. Aby uzyskać szczegółowe informacje o include i _revinclude w parametrach wyszukiwania, zapoznaj się z dokumentacją wyszukiwania FHIR.

Parametry żądania

Podczas wykonywania żądania wyszukiwania z parametrami _include i _revinclude użyj następujących opcjonalnych parametrów, aby kontrolować liczbę.

Nazwa Wartość Opis
_count Wartość domyślna: 10 Wartość maksymalna: 1000 Wartość reprezentuje liczbę zasobów docelowych do pobrania na żądanie.
_includesCount Wartość domyślna: 1000 Wartość oznacza liczbę dopasowanych zasobów, do których odwołują się zasoby docelowe, do pobrania w ramach jednego żądania.

Odpowiedź na wyszukiwania _include i _revinclude zawiera do 1000 elementów. Jeśli istnieje więcej niż 1000 dopasowanych elementów, odpowiedź zawiera link, którego można użyć do nawigowania po kompletnym zestawie wyników.

W poniższym przykładzie wysyłane jest żądanie wyszukiwania zasobu Observations dla pacjenta z identyfikatorem 123.

GET {{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10

Odpowiedź zawiera dane obserwacji pacjenta 123. Dopasowane zasoby są wyświetlane po 10 na stronę, a link umożliwia przejście do pełnej listy wyników.

{ 

  	"resourceType": "Bundle", 

 	 "id": "b5491e39-8f8f-4405-a4cf-2a6716755d73", 

  	"meta": { 

    	"lastUpdated": "2025-04-10T21:09:42.6517693+00:00" 

  	}, 

  	"type": "searchset", 

  "	link": [ 

    	{ 

      	"relation": "next", 

      	"url": "{{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10&ct=er97f5lRTbShgbGOqaGhgbGlsZGFmaWJiYWBgYGpSSwAAAD%2F%2Fw%3D%3D" 

    	}, 

   	 { 

    	  "relation": "related", 

      	"url": "{{FHIR_URL}}/Observation/$include?subject.identifier=123&_include=Observation:subject&_includesCount=10&includesCt=er97f5lRTbShgbGOqaGhgbGlsZGFmaWJiYWBgYGhAaaYqYmOqQUWYaNYAAAAAP%2F%2F" 

   	 }, 

    	{ 

    	  "relation": "self", 

     	 "url": "{{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10” 

    	} 

  	], 

  "entry": [….] 

}

Wyszukiwanie łańcuchowe i odwrotne wyszukiwanie łańcuchowe

Wyszukiwanie łańcuchowe umożliwia wykonywanie ukierunkowanych zapytań dotyczących zasobów odwołujących się do innego zasobu. Jeśli na przykład chcesz znaleźć spotkania, w których imię pacjenta to Jane, użyj:

GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane

Element . w poprzednim żądaniu kieruje ścieżkę przeszukiwania łańcuchowego do parametru docelowego (name w tym przypadku).

Podobnie można wykonać odwrotne wyszukiwanie łańcuchowe za pomocą parametru _has . Ten parametr pobiera wystąpienia zasobów, określając kryteria dotyczące innych zasobów odwołujących się do interesujących zasobów. Przykłady wyszukiwania łańcuchowego i odwrotnego można znaleźć na stronie Przykłady wyszukiwania FHIR.

Podział na strony

Jak wspomniano wcześniej, możesz wyświetlić wyniki z wyszukiwania FHIR w formularzu podzielonym na strony pod linkiem podanym w pakiecie searchset . Domyślnie usługa FHIR wyświetla 10 wyników wyszukiwania na stronę, ale możesz zmienić tę liczbę, ustawiając _count parametr . Jeśli dopasowań jest więcej, niż mieści się na jednej stronie, zestaw zawiera łącze next. Wielokrotne pobieranie z linku next daje kolejne strony wyników. Wartość parametru _count nie może przekroczyć 1000.

Obecnie usługa FHIR w Azure Health Data Services obsługuje tylko link next i nie obsługuje linków first, last ani previous w pakietach zwracanych w wyniku wyszukiwania.

Często zadawane pytania

Co oznacza "częściowa obsługa" w nieobsługiwanych parametrach wyszukiwania R4?

Niektóre parametry wyszukiwania specyficzne dla zasobu obejmują więcej niż jeden typ danych, a usługa FHIR w Azure Health Data Services może obsługiwać tylko ten parametr wyszukiwania na jednym z tych typów danych. Na przykład Condition-abatement-age i Condition-onset-age obejmują dwa różne typy danych: Wiek i Przedział. Jednak usługa FHIR w Azure Health Data Services obsługuje te dwa parametry wyszukiwania dla typu Range, ale nie dla typu Age.

Czy operacja $lastn dla obserwacji jest obsługiwana?

Ta operacja nie jest obsługiwana. Alternatywną metodą jest _count ograniczenie zwracanych zasobów na stronę i _sort zapewnienie wyników w kolejności malejącej.

Następne kroki

Aby dowiedzieć się więcej na temat wyszukiwania FHIR, zobacz stronę przykładów wyszukiwania . Szczegółowe informacje na temat wyszukiwania można znaleźć przy użyciu parametrów wyszukiwania, modyfikatorów i innych metod wyszukiwania FHIR.

Przykłady wyszukiwania FHIR

Uwaga

FHIR® jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7.

  • Last updated on