Eksportowanie danych FHIR 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.
Funkcja eksportu zbiorczego umożliwia eksportowanie danych z serwera FHIR zgodnie ze specyfikacją FHIR.
Przed użyciem $export należy upewnić się, że interfejs API platformy Azure dla standardu FHIR jest skonfigurowany do korzystania z niego. Aby skonfigurować ustawienia eksportu i utworzyć konto usługi Azure Storage, zapoznaj się ze stroną konfigurowanie eksportu danych.
Uwaga
Tylko konta magazynu w tej samej subskrypcji co w przypadku usługi Azure API for FHIR mogą być zarejestrowane jako miejsce docelowe dla operacji $export.
Używanie polecenia $export
Po skonfigurowaniu interfejsu API platformy Azure for FHIR na potrzeby eksportu możesz użyć polecenia $export, aby wyeksportować dane z usługi. Dane będą przechowywane na koncie magazynu określonym podczas konfigurowania eksportu. Aby dowiedzieć się, jak wywołać polecenie $export na serwerze FHIR, przeczytaj dokumentację specyfikacji $export HL7 FHIR.
Zadania zablokowane w złym stanie
W niektórych sytuacjach istnieje potencjał, aby praca utknęła w złym stanie. Może się tak zdarzyć, zwłaszcza jeśli uprawnienia konta magazynu nie zostały prawidłowo skonfigurowane. Jednym ze sposobów weryfikacji eksportu jest sprawdzenie konta magazynu, aby sprawdzić, ndjsonczy istnieją odpowiednie pliki kontenera (czyli ). Jeśli nie są obecne i nie ma żadnych innych uruchomionych zadań eksportu, istnieje możliwość, że bieżące zadanie jest zablokowane w złym stanie. Zadanie eksportowania należy anulować, wysyłając żądanie anulowania i ponownie wysyłając zadanie w kolejce. Domyślny czas wykonywania eksportu w złym stanie wynosi 10 minut, zanim zostanie zatrzymany i przeniesiony do nowego zadania lub ponowi próbę eksportu.
Interfejs API platformy Azure for FHIR obsługuje $export na następujących poziomach:
- System:
GET https://<<FHIR service base URL>>/$export>> - Pacjent:
GET https://<<FHIR service base URL>>/Patient/$export>> - Grupa pacjentów* — usługa Azure API for FHIR eksportuje wszystkie powiązane zasoby, ale nie eksportuje cech grupy:
GET https://<<FHIR service base URL>>/Group/[ID]/$export>>
W przypadku eksportu dane są eksportowane w wielu plikach, z których każdy zawiera tylko jeden typ. Liczba zasobów w pojedynczym pliku będzie ograniczona. Maksymalna liczba zasobów zależy od wydajności systemu. Jest ona obecnie ustawiona na 5000, ale może ulec zmianie. Wynikiem jest to, że możesz uzyskać wiele plików dla typu zasobu. Nazwy plików będą zgodne z formatem "resourceName-number-number.ndjson". Kolejność plików nie ma gwarancji, że odpowiada żadnej kolejności zasobów w bazie danych.
Uwaga
Patient/$export i Group/[ID]/$export może eksportować zduplikowane zasoby, jeśli zasób znajduje się w przedziale więcej niż jednego zasobu lub znajduje się w wielu grupach.
Ponadto sprawdzanie stanu eksportu za pomocą adresu URL zwróconego przez nagłówek lokalizacji podczas kolejkowania jest obsługiwane wraz z anulowaniem rzeczywistego zadania eksportu.
Eksportowanie danych FHIR do usługi ADLS Gen2
Obecnie obsługujemy $export dla kont magazynu z obsługą usługi ADLS Gen2 z następującym ograniczeniem:
- Użytkownik nie może korzystać z hierarchicznych przestrzeni nazw, ale nie istnieje sposób na docelowy eksport do określonego podkatalogu w kontenerze. Udostępniamy tylko możliwość kierowania określonego kontenera (w którym tworzymy nowy folder dla każdego eksportu).
- Po zakończeniu eksportu nigdy nie będziemy ponownie eksportować niczego do tego folderu, ponieważ kolejne eksporty do tego samego kontenera będą znajdować się w nowo utworzonym folderze.
Ustawienia i parametry
Nagłówki
Istnieją dwa wymagane parametry nagłówka, które należy ustawić dla zadań $export. Wartości są definiowane przez bieżącą specyfikację $export.
- Akceptuj — application/fhir+json
- Preferuj — respond-async
Parametry zapytań
Interfejs API platformy Azure dla standardu FHIR obsługuje następujące parametry zapytania. Wszystkie te parametry są opcjonalne:
| Parametr zapytania | Zdefiniowane przez specyfikację FHIR? | opis |
|---|---|---|
| _outputFormat | Tak | Obecnie obsługuje trzy wartości w celu wyrównania do specyfikacji FHIR: application/fhir+ndjson, application/ndjson lub ndjson. Wszystkie zadania eksportu zwracają ndjson wartość i przekazana wartość nie ma wpływu na zachowanie kodu. |
| _Od | Tak | Umożliwia eksportowanie tylko zasobów, które zostały zmodyfikowane od czasu |
| _Typu | Tak | Umożliwia określenie typów zasobów, które zostaną uwzględnione. Na przykład _type=Pacjent zwróci tylko zasoby pacjentów |
| _typefilter | Tak | Aby zażądać bardziej szczegółowego filtrowania, można użyć _typefilter wraz z parametrem _type. Wartość parametru _typeFilter jest rozdzielaną przecinkami listą zapytań FHIR, które dodatkowo ograniczają wyniki |
| _Kontenera | Nie. | Określa kontener na skonfigurowanym koncie magazynu, na którym mają być eksportowane dane. Jeśli zostanie określony kontener, dane zostaną wyeksportowane do folderu do tego kontenera. Jeśli kontener nie zostanie określony, dane zostaną wyeksportowane do nowego kontenera. |
| _Do | Nie. | Umożliwia eksportowanie tylko zasobów, które zostały zmodyfikowane do czasu. Ten parametr ma zastosowanie tylko do eksportu na poziomie systemu. W takim przypadku, jeśli wersje historyczne nie zostały wyłączone lub przeczyszczone, eksport gwarantuje prawdziwy widok migawki lub, innymi słowy, umożliwia podróż w czasie. |
| includeAssociatedData | Nie. | Umożliwia eksportowanie historii i nietrwałych usuniętych zasobów. Ten filtr nie działa z parametrem zapytania "_typeFilter". Uwzględnij wartość jako "_history", aby wyeksportować historię/nie najnowsze wersje zasobów. Uwzględnij wartość jako "_deleted", aby wyeksportować nietrwałe usunięte zasoby. |
| _isparallel | Nie. | Parametr zapytania "_isparallel" można dodać do operacji eksportowania w celu zwiększenia przepływności. Wartość musi być ustawiona na true, aby umożliwić równoległe przetwarzanie. Należy pamiętać, że użycie tego parametru może spowodować zwiększenie zużycia jednostek żądania w czasie eksportu. |
Uwaga
Istnieje znany problem z operacją $export, która może spowodować niekompletne eksporty z powodzeniem stanu. Problem występuje, gdy użyto flagi is_parallel. W przypadku tego problemu ma wpływ na zadania eksportu wykonywane przy użyciu parametru zapytania _isparallel od 13 lutego 2024 r.
Bezpieczny eksport do usługi Azure Storage
Interfejs API platformy Azure dla standardu FHIR obsługuje operację bezpiecznego eksportu. Wybierz jedną z dwóch poniższych opcji:
Zezwalanie usłudze Azure API for FHIR na dostęp do konta usługi Azure Storage jako zaufanej usługi firmy Microsoft.
Zezwalanie określonym adresom IP skojarzonym z interfejsem AZURE API for FHIR w celu uzyskania dostępu do konta usługi Azure Storage. Ta opcja zapewnia dwie różne konfiguracje w zależności od tego, czy konto magazynu znajduje się w tej samej lokalizacji, co lub znajduje się w innej lokalizacji niż w przypadku interfejsu API platformy Azure dla standardu FHIR.
Zezwalanie na korzystanie z interfejsu API platformy Azure dla standardu FHIR jako zaufanej usługi firmy Microsoft
Wybierz konto magazynu w witrynie Azure Portal, a następnie wybierz blok Sieć . Wybierz pozycję Wybrane sieci na karcie Zapory i sieci wirtualne.
Ważne
Upewnij się, że udzielono ci uprawnień dostępu do konta magazynu dla usługi Azure API for FHIR przy użyciu jego tożsamości zarządzanej. Aby uzyskać więcej informacji, zobacz Konfigurowanie ustawienia eksportu i konfigurowanie konta magazynu.
W sekcji Wyjątki wybierz pole Zezwalaj zaufanym usługi firmy Microsoft na dostęp do tego konta magazynu i zapisz ustawienie.
Teraz możesz bezpiecznie wyeksportować dane FHIR do konta magazynu. Należy pamiętać, że konto magazynu znajduje się w wybranych sieciach i nie jest publicznie dostępne. Aby uzyskać dostęp do plików, możesz włączyć i użyć prywatnych punktów końcowych dla konta magazynu lub włączyć wszystkie sieci dla konta magazynu przez krótki czas.
Ważne
Interfejs użytkownika zostanie zaktualizowany później, aby umożliwić wybranie typu zasobu dla usługi Azure API for FHIR i określonego wystąpienia usługi.
Zezwalaj określonym adresom IP na dostęp do konta usługi Azure Storage z innych regionów świadczenia usługi Azure
W witrynie Azure Portal przejdź do konta usługi Azure Data Lake Storage Gen2.
W menu po lewej stronie wybierz pozycję Sieć.
Wybierz pozycję Włączone z wybranych sieci wirtualnych i adresów IP.
W sekcji Zapora w polu Zakres adresów określ adres IP. Dodaj zakresy adresów IP, aby zezwolić na dostęp z Internetu lub sieci lokalnych. Adres IP można znaleźć w poniższej tabeli dla regionu świadczenia usługi Azure, w którym aprowizowana jest usługa FHIR.
Region platformy Azure Publiczny adres IP Australia Wschodnia 20.53.44.80 Kanada Środkowa 20.48.192.84 Środkowe stany USA 52.182.208.31 Wschodnie stany USA 20.62.128.148 Wschodnie stany USA 2 20.49.102.228 Wschodnie stany USA 2 — EUAP 20.39.26.254 Niemcy Północne 51.116.51.33 Niemcy Środkowo-Zachodnie 51.116.146.216 Japonia Wschodnia 20.191.160.26 Korea Środkowa 20.41.69.51 Północno-środkowe stany USA 20.49.114.188 Europa Północna 52.146.131.52 Północna Republika Południowej Afryki 102.133.220.197 South Central US 13.73.254.220 Southeast Asia 23.98.108.42 Szwajcaria Północna 51.107.60.95 Południowe Zjednoczone Królestwo 51.104.30.170 Zachodnie Zjednoczone Królestwo 51.137.164.94 Zachodnio-środkowe stany USA 52.150.156.44 West Europe 20.61.98.66 Zachodnie stany USA 2 40.64.135.77
Zezwalaj określonym adresom IP na dostęp do konta usługi Azure Storage w tym samym regionie
Proces konfiguracji adresów IP w tym samym regionie jest podobny do poprzedniej procedury, z tą różnicą, że używasz określonego zakresu adresów IP w formacie CiDR (Classless Inter-Domain Routing) (tj. 100.64.0.0/10). Należy określić zakres adresów IP (100.64.0.0 do 100.127.255.255), ponieważ adres IP usługi FHIR jest przydzielany za każdym razem, gdy wysyłasz żądanie operacji.
Uwaga
Można użyć prywatnego adresu IP w zakresie 10.0.2.0/24, ale nie ma gwarancji, że operacja powiedzie się w takim przypadku. Jeśli żądanie operacji zakończy się niepowodzeniem, możesz ponowić próbę, ale dopóki nie użyjesz adresu IP w zakresie 100.64.0.0/10, żądanie nie powiedzie się.
To zachowanie sieci dla zakresów adresów IP jest projektowane. Alternatywą jest skonfigurowanie konta magazynu w innym regionie.
Następne kroki
W tym artykule przedstawiono sposób eksportowania zasobów FHIR przy użyciu polecenia $export. Następnie, aby dowiedzieć się, jak wyeksportować dane, które nie zostały zidentyfikowane, zobacz
FHIR® jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7.