Omówienie wyszukiwania w usłudze Azure API for FHIR
Ważne
Usługa Azure API for FHIR zostanie wycofana 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ą możliwe 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 standardzie FHIR. Aby uzyskać szczegółowe informacje na temat wyszukiwania zasobów FHIR, zobacz Wyszukiwanie w specyfikacji HL7 FHIR. W tym artykule przedstawiono przykłady składni wyszukiwania. Każde wyszukiwanie dotyczy 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ć przy użyciu elementu POST, co jest przydatne, jeśli ciąg zapytania jest 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, możesz znaleźć szczegóły błędu w OperationOutcome pliku , aby dowiedzieć się, dlaczego wyszukiwanie nie powiodło się.
W poniższych sekcjach omówiono 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
Wyszukiwania są oparte na różnych atrybutach 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. W poniższej tabeli przedstawiono obsługę różnych typów danych.
Ostrzeżenie
Obecnie występuje problem podczas korzystania z _sort interfejsu API platformy Azure dla standardu 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 | |
| specjalny | Nie | Nie. |
Typowe parametry wyszukiwania
Istnieją typowe parametry wyszukiwania, które mają zastosowanie do wszystkich zasobów. Znajdują się one na poniższej liście 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 | |
| _znacznik | Tak | Tak | |
| _typ | Tak | Tak | |
| _bezpieczeństwo | Tak | Tak | |
| _profil | Tak | Tak | |
| _Ma | Częściowe | Tak | _has Obsługa programu jest w programie MVP w interfejsie AZURE API for FHIR i wersji systemu operacyjnego wspieranej przez usługę Azure Cosmos DB. Więcej szczegółów znajduje się w poniższej sekcji tworzenia łańcucha. |
| _zapytanie | Nie | Nie. | |
| _filtr | Nie | Nie. | |
| _lista | Nie | Nie. | |
| _Tekst | Nie | Nie. | |
| _zawartość | 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ższa tabela zawiera omówienie wszystkich modyfikatorów FHIR i ich obsługi w interfejsie API platformy Azure for FHIR.
| Modyfikatory | Interfejs API platformy Azure dla standardu FHIR | Usługa FHIR w usługach Azure Health Data Services | Komentarz |
|---|---|---|---|
| :brakujący | Tak | Tak | |
| :dokładny | Tak | Tak | |
| :Contains | 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ć. 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 |
|---|---|---|---|
| _pierwiastki | Tak | Tak | |
| _hrabia | Tak | Tak | _count jest ograniczona do 1000 zasobów. W przypadku ustawienia wyższego niż 1000 zostanie zwróconych tylko 1000, a w pakiecie zostanie zwrócone ostrzeżenie. |
| _zawierać | 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 |
| _streszczenie | Tak | Tak | |
| _łączny | Częściowe | Częściowe | _total=none i _total=dokładne |
| _rodzaj | 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. | |
| _wynik | 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 ignoruje 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 wcześniej, wyniki wyszukiwania są pakietem stronicowanym. Domyślnie wyszukiwanie zwraca 10 wyników na stronę, ale można to 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 ograniczona 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 KB 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.
Uwaga
FHIR® jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7.