Omówienie rozwiązania SMART on 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.

Podstawialne aplikacje medyczne i technologie wielokrotnego użytku (SMART on FHIR®) to standard opieki zdrowotnej, za pomocą którego aplikacje mogą uzyskiwać dostęp do informacji klinicznych za pośrednictwem magazynu danych. Dodaje warstwę zabezpieczeń opartą na otwartych standardach, w tym OAuth2 i OpenID Connect, do interfejsów FHIR w celu umożliwienia integracji z systemami EHR. Korzystanie z funkcji SMART w technologii FHIR zapewnia ważne korzyści, w tym:

• Aplikacje mają znaną metodę uzyskiwania uwierzytelniania/autoryzacji dla repozytorium FHIR.
• Użytkownicy, którzy uzyskują dostęp do repozytorium FHIR za pomocą funkcji SMART on FHIR, są ograniczeni do zasobów skojarzonych z użytkownikiem, a nie do wszystkich danych w repozytorium.
• Użytkownicy mają możliwość udzielenia aplikacji dostępu do bardziej ograniczonego zestawu danych przy użyciu zakresów klinicznych SMART.

W poniższych samouczkach opisano kroki włączania funkcji SMART w aplikacjach FHIR za pomocą usługi FHIR.

Wymagania wstępne

• Wystąpienie usługi FHIR
• Zestaw .NET SDK 6.0
• Włączanie współużytkowania zasobów między źródłami (CORS)
• Rejestrowanie publicznej aplikacji klienckiej w identyfikatorze Entra firmy Microsoft
  • Po zarejestrowaniu aplikacji zanotuj applicationId element dla aplikacji klienckiej.
• Upewnij się, że masz dostęp do subskrypcji platformy Azure usługi FHIR, aby utworzyć zasoby i dodać przypisania ról.

SMART on FHIR using Samples OSS (SMART on FHIR(Enhanced))

Krok 1. Konfigurowanie roli użytkownika FHIR SMART

Wykonaj kroki wymienione w obszarze Zarządzanie użytkownikami: Przypisywanie użytkowników do roli. Każdy użytkownik dodany do roli — "FHIR SMART User" może uzyskać dostęp do usługi FHIR, jeśli ich żądania są zgodne z przewodnikiem implementacji SMART on FHIR, takim jak żądanie posiadania tokenu dostępu, który zawiera fhirUser oświadczenie i oświadczenie zakresów klinicznych. Dostęp udzielony użytkownikom w tej roli będzie ograniczony przez zasoby skojarzone z ich fhirUser przedziałem i ograniczenia w zakresach klinicznych.

Krok 2. Integracja serwera FHIR z przykładami

Wykonaj kroki opisane w artykule Azure Health Data and AI Samples OSS (Przykłady danych i sztucznej inteligencji na platformie Azure). Umożliwia to integrację serwera FHIR z innymi usługami platformy Azure (takimi jak APIM, Azure Functions i inne).

Uwaga

Przykłady to kod typu open source i przed jego użyciem należy przejrzeć informacje i postanowienia licencyjne w witrynie GitHub. Nie są one częścią usługi Azure Health Data Service i nie są obsługiwane przez pomoc techniczna firmy Microsoft. Te przykłady mogą służyć do zademonstrowania, w jaki sposób usługi Azure Health Data Services i inne narzędzia typu open source mogą być używane razem w celu zademonstrowania zgodności ze standardem ONC (g)(10) przy użyciu identyfikatora Entra firmy Microsoft jako przepływu pracy dostawcy tożsamości.

SMART na serwerze proxy FHIR

Kliknij, aby rozwinąć!

Uwaga

Jest to kolejna ścieżka do smart on FHIR (Enhanced), jak wspomniano. Opcja SMART on FHIR Proxy włącza tylko sekwencję uruchamiania EHR.

Krok 1. Ustawianie zgody administratora dla aplikacji klienckiej

Aby korzystać z funkcji SMART w standardzie FHIR, musisz najpierw uwierzytelnić i autoryzować aplikację. Przy pierwszym użyciu funkcji SMART on FHIR należy również uzyskać zgodę administracyjną, aby umożliwić aplikacji dostęp do zasobów FHIR.

Jeśli nie masz roli własności w aplikacji, skontaktuj się z właścicielem aplikacji i poproś go o udzielenie zgody administratora dla Ciebie w aplikacji.

Jeśli masz uprawnienia administracyjne, wykonaj następujące kroki, aby udzielić zgody administratora bezpośrednio na siebie. (Możesz również udzielić zgody administratora na siebie później po wyświetleniu monitu w aplikacji). Możesz wykonać te same kroki, aby dodać innych użytkowników jako właścicieli, aby mogli wyświetlać i edytować tę rejestrację aplikacji.

Aby dodać siebie lub innego użytkownika jako właściciela aplikacji:

1. W witrynie Azure Portal przejdź do identyfikatora Microsoft Entra.
2. W menu po lewej stronie wybierz pozycję Rejestracja aplikacji.
3. Wyszukaj utworzoną rejestrację aplikacji, a następnie wybierz ją.
4. W menu po lewej stronie w obszarze Zarządzaj wybierz pozycję Właściciele.
5. Wybierz pozycję Dodaj właścicieli, a następnie dodaj siebie lub użytkownika, którego chcesz wyrazić zgodę administratora.
6. Wybierz pozycję Zapisz

Krok 2. Włączanie serwera proxy SMART na serwerze proxy FHIR

Funkcja SMART on FHIR wymaga identyfikatora Audience URI identyfikatora równego identyfikatorowi URI usługi FHIR. Standardowa konfiguracja interfejsu API platformy Azure for FHIR używa Audience wartości https://azurehealthcareapis.com. Można jednak również ustawić wartość zgodną z określonym adresem URL usługi FHIR (na przykład https://MYFHIRAPI.azurehealthcareapis.com). Jest to wymagane podczas pracy z serwerem proxy SMART na serwerze proxy FHIR.

Aby włączyć serwer proxy SMART on FHIR w ustawieniach uwierzytelniania dla wystąpienia usługi Azure API for FHIR, zaznacz pole wyboru SMART on FHIR proxy .

Serwer proxy SMART on FHIR działa jako pośrednik między aplikacją SMART on FHIR i identyfikatorem Microsoft Entra. Odpowiedź uwierzytelniania (kod uwierzytelniania) musi przejść do serwera proxy SMART on FHIR zamiast samej aplikacji. Następnie serwer proxy przekazuje odpowiedź do aplikacji.

Ze względu na ten dwuetapowy przekaźnik kodu uwierzytelniania należy ustawić adres URL odpowiedzi (wywołanie zwrotne) dla aplikacji klienckiej Microsoft Entra na adres URL, który jest kombinacją adresu URL odpowiedzi dla serwera proxy SMART on FHIR i adresu URL odpowiedzi dla aplikacji SMART on FHIR. Połączony adres URL odpowiedzi ma następujący formularz.

https://MYFHIRAPI.azurehealthcareapis.com/AadSmartOnFhirProxy/callback/aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA

W odpowiedzi aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA jest bezpieczną pod adresem URL, zakodowaną w formacie base64 wersją adresu URL odpowiedzi dla aplikacji SMART on FHIR. W przypadku uruchamiania aplikacji SMART on FHIR, gdy aplikacja jest uruchomiona lokalnie, adres URL odpowiedzi to https://localhost:5001/sampleapp/index.html.

Możesz wygenerować połączony adres URL odpowiedzi przy użyciu skryptu podobnego do poniższego.

$replyUrl = "https://localhost:5001/sampleapp/index.html"
$fhirServerUrl = "https://MYFHIRAPI.azurewebsites.net"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($ReplyUrl)
$encodedText = [Convert]::ToBase64String($bytes)
$encodedText = $encodedText.TrimEnd('=');
$encodedText = $encodedText.Replace('/','_');
$encodedText = $encodedText.Replace('+','-');

$newReplyUrl = $FhirServerUrl.TrimEnd('/') + "/AadSmartOnFhirProxy/callback/" + $encodedText

Dodaj adres URL odpowiedzi do publicznej aplikacji klienckiej utworzonej wcześniej dla identyfikatora Entra firmy Microsoft.

Krok 3. Uzyskanie pacjenta testowego

Aby przetestować usługę Azure API for FHIR i serwer proxy SMART on FHIR, musisz mieć co najmniej jednego pacjenta w bazie danych. Jeśli jeszcze nie korzystasz z interfejsu API i nie masz danych w bazie danych, zobacz Access the FHIR service using Postman to load a patient (Uzyskiwanie dostępu do usługi FHIR przy użyciu narzędzia Postman w celu załadowania pacjenta). Zanotuj identyfikator określonego pacjenta.

Krok 4. Pobieranie aplikacji SMART on FHIR App Launcher

Serwer FHIR typu open source dla repozytorium platformy Azure zawiera prostą aplikację SMART on FHIR app launcher i przykładową aplikację SMART on FHIR. W tym samouczku użyj tej funkcji SMART on FHIR launcher lokalnie, aby przetestować konfigurację.

Repozytorium GitHub można sklonować i przejść do aplikacji przy użyciu następujących poleceń.

git clone https://github.com/Microsoft/fhir-server
cd fhir-server/samples/apps/SmartLauncher

Aplikacja wymaga kilku ustawień konfiguracji, które można ustawić w programie appsettings.json:

{
    "FhirServerUrl": "https://MYFHIRAPI.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

Zalecamy korzystanie z dotnet user-secrets tej funkcji.

dotnet user-secrets set FhirServerUrl https://MYFHIRAPI.azurehealthcareapis.com
dotnet user-secrets set ClientId <APP-ID>

Użyj tego polecenia, aby uruchomić aplikację.

dotnet run

Krok 5. Testowanie serwera proxy SMART na serwerze proxy FHIR

Po uruchomieniu aplikacji SMART w funkcji uruchamiania aplikacji FHIR możesz wskazać przeglądarkę na https://localhost:5001adres , gdzie powinien zostać wyświetlony poniższy ekran.

Po wprowadzeniu informacji o pacjentach, spotkaniach lub praktykach zwróć uwagę, że kontekst uruchamiania jest aktualizowany. Gdy używasz interfejsu API platformy Azure dla standardu FHIR, kontekst uruchamiania to po prostu dokument JSON zawierający informacje o pacjentach, praktykach i nie tylko. Ten kontekst uruchamiania jest zakodowany w formacie base64 i przekazywany do aplikacji SMART on FHIR jako launch parametr zapytania. Zgodnie ze specyfikacją SMART on FHIR ta zmienna jest nieprzezroczysta dla aplikacji SMART on FHIR i przekazywana do dostawcy tożsamości.

Serwer proxy SMART on FHIR używa tych informacji do wypełniania pól w odpowiedzi tokenu. Aplikacja SMART on FHIR może używać tych pól do kontrolowania, do którego pacjenta żąda danych i sposobu renderowania aplikacji na ekranie. Serwer proxy SMART on FHIR obsługuje następujące pola.

• patient
• encounter
• practitioner
• need_patient_banner
• smart_style_url

Te pola mają na celu przedstawienie wskazówek dla aplikacji, ale nie przekazują żadnych informacji o zabezpieczeniach. Aplikacja SMART on FHIR może je zignorować.

Zwróć uwagę, że uruchamianie aplikacji SMART on FHIR aktualizuje informacje o adresie URL uruchamiania w dolnej części strony.

Wybierz pozycję Uruchom , aby uruchomić przykładową aplikację.

Migrowanie z serwera proxy SMART on FHIR do funkcji SMART on FHIR (ulepszone)

Ważne

Serwer proxy SMART on FHIR przechodzi na emeryturę we wrześniu 2026 r., przechodząc do smart on FHIR (Enhanced) do tej daty. Od września 2026 r. aplikacje uzależnione od serwera proxy SMART na serwerze proxy FHIR będą zgłaszać błędy podczas uzyskiwania dostępu do usługi FHIR.

Smart on FHIR (Enhanced) zapewnia więcej możliwości w porównaniu z serwerem proxy SMART na FHIR. Smart on FHIR(Enhanced) można uznać za spełniające wymagania dotyczące standardowego interfejsu API SMART on FHIR Implementation Guide (wersja 1.0.0) i §170.315(g)(10) Standardized API dla kryterium usług pacjentów i populacji. W poniższej tabeli wymieniono różnicę między serwerem proxy SMART on FHIR i SMART on FHIR (Enhanced).

Możliwość	SMART na FHIR (ulepszone)	SMART na serwerze proxy FHIR
Obsługuje uruchamianie autonomiczne	Tak	Nie.
Obsługuje uruchamianie EHR	Tak	Tak
Obsługuje ograniczenia zakresu	Tak	Nie.
Opiera się na produktach platformy Azure innych firm	Tak, produkty platformy Azure, takie jak usługa Azure API Management (APIM), muszą być zintegrowane	Nie.
Pomoc techniczna firmy Microsoft	Obsługiwane w przypadku usługi FHIR. Przykładowa obsługa typu open source musi być zgłaszana i monitorowana za pośrednictwem usługi GitHub	Obsługiwane w przypadku usługi FHIR

Kroki migracji

• Krok 1. Konfigurowanie roli użytkownika FHIR SMART Wykonaj kroki opisane w sekcji Zarządzanie użytkownikami: Przypisywanie użytkowników do roli. Każdy użytkownik dodany do roli użytkownika SMART może uzyskać dostęp do usługi FHIR, jeśli ich żądania są zgodne z przewodnikiem implementacji SMART on FHIR.
• Krok 2. Wdrażanie przykładu SMART on FHIR w obszarze Azure Health Data and AI OSS Samples
• Krok 3. Aktualizowanie punktu końcowego adresu URL usługi FHIR na "{{BASEURL_FROM_APIM}}/smart".
• Krok 4. Usuń zaznaczenie ustawienia SMART on FHIR proxy w bloku Uwierzytelnianie dla usługi FHIR.

Jeśli masz pytania, odpowiedzi od ekspertów ze społeczności możesz uzyskać w witrynie Microsoft Q&A. Aby uzyskać pomoc techniczną, możesz również utworzyć wniosek o pomoc techniczną.

Następne kroki

Teraz, gdy wiesz już, jak włączyć funkcję SMART on 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.

Przykłady wyszukiwania FHIR

Uwaga

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