Omówienie wyszukiwania FHIR
Specyfikacja Fast Healthcare Interoperability Resources (FHIR®) definiuje interfejs API do wykonywania zapytań dotyczących zasobów w bazie danych serwera FHIR. Ten artykuł przeprowadzi Cię przez kluczowe aspekty wykonywania zapytań dotyczących danych w środowisku FHIR. Aby uzyskać szczegółowe informacje na temat interfejsu API wyszukiwania FHIR, zapoznaj się z dokumentacją wyszukiwania FHIR HL7.
W tym artykule przedstawiono składnię wyszukiwania FHIR w przykładowych wywołaniach interfejsu API z symbolem {{FHIR_URL}} zastępczym reprezentującym adres URL serwera FHIR. Jeśli usługa FHIR znajduje się w usługach Azure Health Data Services, ten adres URL to https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.
Wyszukiwanie FHIR może dotyczyć określonego typu zasobu, określonego przedziału lub wszystkich zasobów w bazie danych serwera FHIR. Najprostszym sposobem wykonania wyszukiwania w standardzie FHIR jest użycie GET żądania. Jeśli na przykład chcesz ściągnąć wszystkie Patient zasoby w bazie danych, możesz użyć następującego żądania.
GET {{FHIR_URL}}/Patient
Możesz również wyszukać za pomocą polecenia POST. Aby wyszukać przy użyciu metody POST, parametry wyszukiwania są dostarczane w treści żądania. Ułatwia to wysyłanie zapytań z dłuższą, bardziej złożoną serią parametrów.
POST GETJeśli żądanie wyszukiwania zakończy się pomyślnie, otrzymasz pakiet FHIR searchset zawierający wystąpienia zasobów zwrócone z wyszukiwania. Jeśli wyszukiwanie zakończy się niepowodzeniem OperationOutcome , szczegóły błędu znajdziesz w odpowiedzi.
W poniższych sekcjach omówiono różne aspekty wykonywania zapytań dotyczących zasobów w środowisku FHIR. Po przejrzeniu tych tematów zapoznaj się ze stroną przykładów wyszukiwania FHIR, która zawiera przykłady różnych metod wyszukiwania FHIR.
Parametry wyszukiwania
Podczas wyszukiwania w środowisku FHIR wyszukujesz bazę danych pod kątem zasobów spełniających określone kryteria. 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. W wywołaniu interfejsu API wyszukiwania FHIR, jeśli zostanie znalezione pozytywne dopasowanie między parametrami wyszukiwania żądania i odpowiednimi wartościami elementów przechowywanymi w wystąpieniu zasobu, serwer FHIR zwraca pakiet zawierający wystąpienia zasobów, których elementy spełniają kryteria wyszukiwania.
Dla każdego parametru wyszukiwania specyfikacja FHIR definiuje typ danych, którego można użyć. Obsługa w usłudze FHIR dla różnych typów danych została opisana poniżej.
| 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 | |
| string | Tak | Tak | |
| token | Tak | Tak | |
| reference | Tak | Tak | |
| Kompozytowe | 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
Istnieją typowe parametry wyszukiwania, które mają zastosowanie do wszystkich zasobów w standardze FHIR. Są one wymienione w następujący sposób, wraz z ich wsparciem 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. Parametry wyszukiwania, które nie są obsługiwane, są wymienione w poniższych linkach:
Bieżąca obsługa parametrów wyszukiwania jest również widoczna w instrukcji funkcji FHIR z następującym żądaniem:
GET {{FHIR_URL}}/metadata
Aby wyświetlić obsługiwane parametry wyszukiwania w instrukcji capability, przejdź do CapabilityStatement.rest.resource.searchParam parametrów wyszukiwania specyficznych dla zasobu i CapabilityStatement.rest.searchParam wyszukaj parametry wyszukiwania, które mają zastosowanie do wszystkich zasobów.
Uwaga
Usługa FHIR w usługach Azure Health Data Services nie indeksuje automatycznie parametrów wyszukiwania, które nie są zdefiniowane w podstawowej specyfikacji FHIR. Usługa FHIR obsługuje parametry wyszukiwania niestandardowego.
Parametry wyszukiwania złożonego
Wyszukiwanie złożone w standardze FHIR umożliwia wyszukiwanie par elementów jako logicznie połączonych jednostek. Jeśli na przykład szukano obserwacji, w których wysokość pacjenta wynosiła ponad 60 cali, warto upewnić się, że jedna właściwość obserwacji zawierała kod wysokości i wartość większą niż 60 cali (wartość powinna dotyczyć tylko wysokości). Na przykład nie chcesz mieć pozytywnego dopasowania do obserwacji z kodem wysokości i kodem długości ramienia powyżej 60 cali. Parametry wyszukiwania złożonego uniemożliwiają ten problem, wyszukując wstępnie określone pary elementów, których wartości muszą spełniać kryteria wyszukiwania, aby wystąpiło pozytywne dopasowanie.
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.
- Odwołanie, token
- Token, data
- Token, Liczba, Liczba
- Token, Ilość
- Token, ciąg
- Token, Token
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
Modyfikatory umożliwiają zakwalifikowanie parametrów wyszukiwania z dodatkowymi warunkami. Poniżej znajduje się tabela modyfikatorów FHIR i ich obsługa 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 (identyfikator URI) |
Tak | Tak | |
:above (identyfikator 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ść (liczby, daty i ilości), można użyć prefiksu przed wartością parametru, aby uściślić kryteria wyszukiwania (na przykład gdzie Patient?_lastUpdated=gt2022-08-01 prefiks gt oznacza "większe niż"). Usługa FHIR w usługach Azure Health Data Services obsługuje wszystkie prefiksy zdefiniowane w standardzie FHIR.
Parametry wyników wyszukiwania
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 . Poniżej znajduje się tabela parametrów wyników wyszukiwania FHIR i ich obsługa 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 jest ograniczony do 1000 zasobów. Jeśli zostanie ustawiona wartość wyższa niż 1000, zostanie zwróconych tylko 1000, a ostrzeżenie zostanie uwzględnione w pakiecie. |
_include |
Tak | Tak | Elementy pobierane z _include programem są ograniczone do 100. _include w usługach PaaS i OSS w usłudze Azure Cosmos DB nie jest obsługiwane :iterate (#2137). |
_revinclude |
Tak | Tak | Elementy pobierane z _revinclude programem są ograniczone do 100. _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 są 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. |
Uwaga:
- Domyślnie
_sortrozmieszcza 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. - Usługa FHIR obsługuje wyszukiwanie symboli wieloznacznego z ponownymi nazwami. Dodanie parametru zapytania "." w zapytaniu revinclude przekierowuje usługę FHIR w celu odwołania się do wszystkich zasobów zamapowanych na zasób źródłowy.
Domyślnie usługa FHIR w usługach Azure Health Data Services jest ustawiona na łagodną obsługę. Oznacza to, że serwer ignoruje wszystkie nieznane lub nieobsługiwane parametry. Jeśli chcesz używać ścisłej Prefer obsługi, możesz dołączyć nagłówek i ustawić wartość handling=strict.
Wyszukiwanie łańcuchowe i odwrotne
Wyszukiwanie łańcuchowe umożliwia wykonywanie precyzyjnych zapytań dotyczących zasobów, które mają odwołanie 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ą wyszukiwania łańcuchowego do parametru docelowego (name w tym przypadku).
Podobnie można wykonać odwrotne wyszukiwanie łańcuchowe za pomocą parametru _has . Dzięki temu można 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ładów wyszukiwania FHIR.
Podział na strony
Jak wspomniano wcześniej, wyniki wyszukiwania FHIR są dostępne 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żna to zwiększyć (lub zmniejszyć), ustawiając _count parametr . Jeśli na jednej stronie znajduje się więcej dopasowań niż pasuje, pakiet zawiera next link. Wielokrotne pobieranie z linku next daje kolejne strony wyników. Należy pamiętać, że wartość parametru _count nie może przekraczać 1000.
Obecnie usługa FHIR w usługach Azure Health Data Services obsługuje next tylko link i nie obsługuje firstlinków , lastani previous linków w pakietach zwracanych z wyszukiwania.
Następne kroki
Teraz, gdy znasz już podstawy wyszukiwania FHIR, zobacz stronę przykładów wyszukiwania, aby uzyskać szczegółowe informacje na temat wyszukiwania przy użyciu parametrów wyszukiwania, modyfikatorów i innych metod wyszukiwania FHIR.
Uwaga
FHIR® jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7.