Omówienie wyszukiwania w usłudze Azure API for FHIR
Ważne
Interfejs API platformy Azure dla standardu FHIR zostanie wycofany 30 września 2026 r. Postępuj zgodnie ze strategiami migracji, aby przejść do usługi Azure Health Data Services FHIR do tej daty. Ze względu na wycofanie usługi Azure API for FHIR nowe wdrożenia nie będą dozwolone od 1 kwietnia 2025 r. Usługa FHIR usług Azure Health Data Services to rozwinięta wersja usługi Azure API for FHIR, która umożliwia klientom zarządzanie usługami FHIR, DICOM i MedTech z integracją z innymi usługami platformy Azure.
Specyfikacja Fast Healthcare Interoperability Resources (FHIR) definiuje podstawy wyszukiwania zasobów FHIR®. Ten artykuł przeprowadzi Cię przez niektóre kluczowe aspekty wyszukiwania zasobów w FHIR. Aby uzyskać szczegółowe informacje na temat wyszukiwania zasobów FHIR, zobacz Wyszukiwanie w specyfikacji HL7 FHIR. W tym artykule przedstawimy przykłady składni wyszukiwania. Każde wyszukiwanie będzie mieć wartość względem serwera FHIR, który zazwyczaj ma adres URL https://<FHIRSERVERNAME>.azurewebsites.net. W przykładach użyjemy symbolu zastępczego {{FHIR_URL}} dla tego adresu URL.
Wyszukiwanie FHIR może dotyczyć określonego typu zasobu, określonego przedziału lub wszystkich zasobów. Najprostszym sposobem wykonania wyszukiwania w standardzie FHIR jest użycie GET żądania. Jeśli na przykład chcesz ściągnąć wszystkich pacjentów w bazie danych, możesz użyć następującego żądania:
GET {{FHIR_URL}}/Patient
Możesz również wyszukiwać za pomocą polecenia POST, co jest przydatne, jeśli ciąg zapytania jest za długi. Aby wyszukać przy użyciu metody POST, parametry wyszukiwania można przesłać jako treść formularza. Umożliwia to dłuższe, bardziej złożone serie parametrów zapytania, które mogą być trudne do zobaczenia i zrozumienia w ciągu zapytania.
Jeśli żądanie wyszukiwania zakończy się pomyślnie, otrzymasz odpowiedź pakietu FHIR z typem searchset. Jeśli wyszukiwanie zakończy się niepowodzeniem, szczegóły błędu znajdziesz w OperationOutcome pliku , aby zrozumieć, dlaczego wyszukiwanie nie powiodło się.
W poniższych sekcjach omówimy różne aspekty związane z wyszukiwaniem. Po przejrzeniu tych szczegółów zapoznaj się z naszą stroną przykładów zawierającą przykłady wyszukiwań, które można wykonać w interfejsie AZURE API for FHIR.
Parametry wyszukiwania
Podczas wyszukiwania będziesz wyszukiwać na podstawie różnych atrybutów zasobu. Te atrybuty są nazywane parametrami wyszukiwania. Każdy zasób ma zestaw zdefiniowanych parametrów wyszukiwania. Parametr wyszukiwania należy zdefiniować i zaindeksować w bazie danych, aby można było go pomyślnie wyszukać.
Każdy parametr wyszukiwania ma zdefiniowane typy danych. Obsługa różnych typów danych została opisana poniżej:
Ostrzeżenie
Obecnie występuje problem podczas korzystania z _sort w interfejsie API platformy Azure for FHIR z wyszukiwaniem łańcuchowym. Aby uzyskać więcej informacji, zobacz problem typu open source #2344. Zostanie to rozwiązane podczas wydania w grudniu 2021 r.
| Typ parametru wyszukiwania | Interfejs API platformy Azure dla standardu FHIR | Usługa FHIR w usługach Azure Health Data Services | 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 została opisana w dalszej części tego artykułu |
| ilość | Tak | Tak | |
| uri | Tak | Tak | |
| Specjalne | Nie | Nie. |
Typowe parametry wyszukiwania
Istnieją typowe parametry wyszukiwania, które mają zastosowanie do wszystkich zasobów. Poniżej wymieniono te elementy wraz z obsługą interfejsu API platformy Azure for FHIR:
| Typowy parametr wyszukiwania | Interfejs API platformy Azure dla standardu FHIR | Usługa FHIR w usługach Azure Health Data Services | Komentarz |
|---|---|---|---|
| _id | Tak | Tak | |
| _Lastupdated | Tak | Tak | |
| _Tag | Tak | Tak | |
| _Typu | Tak | Tak | |
| _Zabezpieczeń | Tak | Tak | |
| _Profil | Tak | Tak | |
| _Hsa | Częściowe | Tak | Obsługa _has jest w MVP interfejsu API for FHIR platformy Azure i wersji systemu operacyjnego wspieranej przez usługę Azure Cosmos DB. Więcej szczegółów znajduje się w poniższej sekcji tworzenia łańcucha. |
| _Kwerendy | Nie | Nie. | |
| _Filtr | Nie | Nie. | |
| _Listy | Nie | Nie. | |
| _Tekst | Nie | Nie. | |
| _Zawartości | Nie | Nie. |
Parametry specyficzne dla zasobu
W przypadku interfejsu API platformy Azure dla standardu FHIR obsługujemy prawie wszystkie parametry wyszukiwania specyficzne dla zasobów zdefiniowane przez specyfikację FHIR. Jedyne parametry wyszukiwania, których nie obsługujemy, są dostępne 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ć parametry wyszukiwania w instrukcji capability, przejdź do strony , aby CapabilityStatement.rest.resource.searchParam wyświetlić parametry wyszukiwania dla każdego zasobu i CapabilityStatement.rest.searchParam znaleźć parametry wyszukiwania dla wszystkich zasobów.
Uwaga
Interfejs API platformy Azure dla standardu FHIR nie tworzy ani nie indeksuje żadnych parametrów wyszukiwania, które nie są zdefiniowane przez specyfikację FHIR. Zapewniamy jednak obsługę definiowania własnych parametrów wyszukiwania.
Parametry wyszukiwania złożonego
Wyszukiwanie złożone umożliwia wyszukiwanie par wartości. Jeśli na przykład szukasz obserwacji wysokości, w której osoba miała 60 cali, warto upewnić się, że pojedynczy składnik obserwacji zawierał kod wysokości i wartość 60. Nie chcesz uzyskać obserwacji, w której przechowywano wagę 60 i wysokość 48, mimo że obserwacja zawierałaby wpisy, które zakwalifikowały się do wartości 60 i kodu wysokości, tylko w różnych sekcjach składowych.
W przypadku interfejsu API platformy Azure dla standardu FHIR obsługujemy następujące pary typów parametrów wyszukiwania:
- Odwołanie, token
- Token, data
- Token, Liczba, Liczba
- Token, Ilość
- Token, ciąg
- Token, Token
Aby uzyskać więcej informacji, zobacz Parametry 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ą modyfikowanie parametru wyszukiwania. Poniżej przedstawiono omówienie wszystkich modyfikatorów FHIR i pomocy technicznej w usłudze Azure API for FHIR.
| Modyfikatory | Interfejs API platformy Azure dla standardu FHIR | Usługa FHIR w usługach Azure Health Data Services | Komentarz |
|---|---|---|---|
| :Brakuje | Tak | Tak | |
| :Dokładne | Tak | Tak | |
| :Zawiera | Tak | Tak | |
| :Tekst | Tak | Tak | |
| :type (odwołanie) | Tak | Tak | |
| :Nie | 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. |
W przypadku parametrów wyszukiwania, które mają określoną kolejność (liczby, daty i ilości), możesz użyć prefiksu dla parametru , aby ułatwić znajdowanie dopasowań. Interfejs API platformy Azure dla standardu FHIR obsługuje wszystkie prefiksy.
Parametry wyników wyszukiwania
Aby ułatwić zarządzanie zwróconych zasobów, istnieją parametry wyników wyszukiwania, których można użyć w wyszukiwaniu. Aby uzyskać szczegółowe informacje na temat używania poszczególnych parametrów wyników wyszukiwania, zapoznaj się z witryną internetową HL7 .
| Parametry wyników wyszukiwania | Interfejs API platformy Azure dla standardu FHIR | Usługa FHIR w usługach Azure Health Data Services | Komentarz |
|---|---|---|---|
| _Elementy | Tak | Tak | |
| _Liczba | Tak | Tak | _count jest ograniczona do 1000 zasobów. Jeśli zostanie ustawiona wartość wyższa niż 1000, zostanie zwróconych tylko 1000, a w pakiecie zostanie zwrócone ostrzeżenie. |
| _Obejmują | Tak | Tak | Uwzględnione elementy są ograniczone do 100. _include w usługach PaaS i OSS w usłudze Azure Cosmos DB nie obejmują obsługi iteracji (#2137). |
| _revinclude | Tak | Tak | Uwzględnione elementy są ograniczone do 100. _revinclude w usługach PaaS i OSS w usłudze Azure Cosmos DB nie obejmują obsługi iteracji (#2137). Istnieje również nieprawidłowy kod stanu nieprawidłowego żądania #1319 |
| _Krótki opis | Tak | Tak | |
| _Łącznych | Częściowe | Częściowe | _total=none i _total=dokładne |
| _Sortowania | Częściowe | Częściowe | funkcja sort=_lastUpdated jest obsługiwana w usłudze Azure API for FHIR i FHIR. 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. |
| _Zawarte | Nie | Nie. | |
| _containedType | Nie | Nie. | |
| _Ocena | Nie | Nr |
Uwaga
Domyślnie _sort sortuje rekord w kolejności rosnącej. Prefiks '-' można sortować w kolejności malejącej. Ponadto usługa FHIR i interfejs API platformy Azure for FHIR umożliwiają sortowanie tylko w jednym polu naraz.
Domyślnie interfejs API platformy Azure dla standardu FHIR jest ustawiony na łagodną obsługę. Oznacza to, że serwer zignoruje wszystkie nieznane lub nieobsługiwane parametry. Jeśli chcesz używać ścisłej obsługi, możesz użyć nagłówka Preferuj i ustawić .handling=strict
Wyszukiwanie łańcuchowe i odwrotne
Wyszukiwanie łańcuchowe umożliwia wyszukiwanie przy użyciu parametru wyszukiwania w zasobie, do którego odwołuje się inny zasób. 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
Podobnie można wykonywać odwrotne wyszukiwanie łańcuchowe. Dzięki temu można pobierać zasoby, określając kryteria dotyczące innych odwołujących się do nich zasobów. Aby uzyskać więcej przykładów wyszukiwania łańcuchowego i odwrotnego, zapoznaj się ze stroną przykładów wyszukiwania FHIR.
Uwaga
W usłudze Azure API for FHIR i środowisku open source wspieranym przez usługę Azure Cosmos DB istnieje ograniczenie, w którym każde podzapytywanie wymagane do wyszukiwania łańcuchowego i odwrotnego zwróci tylko 1000 elementów. Jeśli znaleziono więcej niż 1000 elementów, zostanie wyświetlony następujący komunikat o błędzie: "Podzapytania w wyrażeniu łańcuchowym nie mogą zwrócić więcej niż 1000 wyników, użyj bardziej selektywnych kryteriów". Aby uzyskać pomyślne zapytanie, musisz być bardziej szczegółowy w tym, czego szukasz.
Podział na strony
Jak wspomniano powyżej, wyniki wyszukiwania będą pakietem stronicowanym. Domyślnie wyszukiwanie zwróci 10 wyników na stronę, ale można je zwiększyć (lub zmniejszyć), określając wartość _count. W pakiecie będzie dostępny link własny zawierający bieżący wynik wyszukiwania. Jeśli istnieją dodatkowe dopasowania, pakiet będzie zawierać następny link. Możesz nadal używać następnego linku, aby uzyskać kolejne strony wyników. _count jest ograniczony do 1000 elementów lub mniej.
Następny link w pakiecie ma limit rozmiaru tokenu kontynuacji 3 KB. Masz elastyczność dostosowywania rozmiaru tokenu kontynuacji z zakresu od 1 do 3 KB przy użyciu nagłówka "x-ms-documentdb-responsecontinuationtokenlimitinkb".
Obecnie interfejs API platformy Azure for FHIR obsługuje tylko następny link w pakietach i nie obsługuje pierwszych, ostatnich ani poprzednich linków.
Następne kroki
Teraz, gdy znasz już podstawy wyszukiwania, zobacz stronę przykładów wyszukiwania, aby uzyskać szczegółowe informacje na temat sposobu wyszukiwania przy użyciu różnych parametrów wyszukiwania, modyfikatorów i innych scenariuszy wyszukiwania FHIR.
FHIR® jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7.