Uzyskiwanie dostępu do usługi FHIR przy użyciu narzędzia Postman

W tym artykule przedstawiono kroki uzyskiwania dostępu do usługi FHIR® w usługach Azure Health Data Services za pomocą narzędzia Postman.

Wymagania wstępne

• Usługa FHIR wdrożona na platformie Azure. Aby uzyskać więcej informacji, zobacz Wdrażanie usługi FHIR.
• Narzędzie Postman zainstalowane lokalnie. Aby uzyskać więcej informacji, zobacz Wprowadzenie do programu Postman.
• Rola administratora dostępu użytkowników dla przypisań ról w usłudze FHIR.

Kroki instalacji

Aby uzyskać dostęp do usługi FHIR z poziomu aplikacji Postman, zapoznaj się z krokami:

1. Zarejestruj aplikację kliencką (rejestrację aplikacji) w identyfikatorze Entra firmy Microsoft.

2. Przypisz rolę Współautor danych FHIR w usłudze FHIR.

3. Konfigurowanie narzędzia Postman — tworzenie obszaru roboczego, kolekcji i środowiska

Rejestrowanie aplikacji klienckiej w usłudze Microsoft Entra ID

1. W witrynie Azure Portal wybierz kafelek Microsoft Entra ID .

2. Wybierz pozycję Rejestracje aplikacji w sekcji Zarządzanie.

3. Wybierz pozycję + Nowe rejestracje.

4. Wprowadź nazwę rejestracji aplikacji. W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacji. wybierz pozycję Zarejestruj.

Identyfikator aplikacji (identyfikator klienta)

Po zarejestrowaniu nowej aplikacji można znaleźć identyfikator aplikacji (klienta) i identyfikator katalogu (dzierżawy) w sekcji Przegląd. Zanotuj te wartości do późniejszego użycia, ponieważ będą one potrzebne podczas konfigurowania środowiska Postman.

Ustawienie uwierzytelniania: poufne a publiczne

• Wybierz pozycję Uwierzytelnianie, aby przejrzeć ustawienia. Wartość domyślna zezwalania na przepływy klientów publicznych to "Nie".

• Jeśli zachowasz tę wartość domyślną, rejestracja aplikacji jest poufnej aplikacji klienckiej i wymagany jest certyfikat lub wpis tajny.

• Jeśli zmienisz wartość domyślną na "Tak" dla opcji "Zezwalaj na przepływy klientów publicznych" w ustawieniu zaawansowanym, rejestracja aplikacji jest publiczną aplikacją kliencką, a certyfikat lub wpis tajny nie jest wymagany.
  

• Wartość "Tak" jest przydatna, gdy chcesz użyć aplikacji klienckiej w aplikacji mobilnej lub aplikacji JavaScript, w której nie chcesz przechowywać żadnych wpisów tajnych.

• W przypadku narzędzi wymagających adresu URL przekierowania wybierz pozycję Dodaj platformę, aby skonfigurować platformę.

• W polu Postman wybierz pozycję Aplikacje mobilne i klasyczne. Wprowadź "https://www.getpostman.com/oauth2/callback" w sekcji Niestandardowe identyfikatory URI przekierowania. Wybierz przycisk Konfiguruj, aby zapisać ustawienie.

Certyfikaty i wpisy tajne

1. Kliknij pozycję Certyfikaty i wpisy tajne. Kliknij pozycję +Nowy klucz tajny klienta.

2. W obszarze Dodawanie wpisu tajnego klienta wprowadź nazwę wpisu tajnego w polu Opis . Wskazówki dotyczą ustawiania 6 miesięcy na wygaśnięcie wpisu tajnego. Kliknij przycisk Dodaj.

3. Ważne jest, aby zapisać wartość wpisu tajnego, a nie identyfikator wpisu tajnego.

Uwaga

Użyj grant_type client_credentials podczas próby uzyskania tokenu dostępu dla usługi FHIR przy użyciu narzędzi, takich jak Postman lub klient REST.

Przypisywanie roli Współautor danych FHIR w usłudze FHIR

W tej sekcji przedstawiono kroki przypisywania roli Współautor danych FHIR do zarejestrowanej aplikacji dla usługi FHIR® w usługach Azure Health Data Services.

1. W witrynie Azure Portal przejdź do usługi FHIR.

2. W menu po lewej stronie wybierz blok Kontrola dostępu (Zarządzanie dostępem i tożsamościami). Kliknij pozycję + Dodaj, a następnie wybierz pozycję Dodaj przypisanie roli. Jeśli opcja dodawania przypisania roli jest niedostępna, poproś administratora platformy Azure o przypisanie Ci uprawnień do wykonania tego kroku.

3. W obszarze Dodawanie przypisania roli na karcie Rola przewiń w dół listę i wybierz pozycję Współautor danych FHIR. Następnie kliknij Dalej.

4. Na karcie Członkowie kliknij pozycję +Wybierz członków. Wpisz nazwę aplikacji klienckiej usługi Postman w polu Wybierz po prawej stronie. Wybierz aplikację.

5. W ten sam sposób wpisz nazwę swojej nazwy użytkownika w obszarze Wybierz. Wybierz użytkownika, aby został dodany do listy wraz z rejestracją aplikacji, a następnie kliknij pozycję Wybierz. Następnie kliknij Dalej.

6. Na karcie Przeglądanie i przypisywanie kliknij pozycję Przejrzyj i przypisz.

Konfigurowanie narzędzia Postman — tworzenie obszaru roboczego, kolekcji i środowiska.

Jeśli dopiero zaczynasz korzystać z narzędzia Postman, wykonaj następujące kroki, aby utworzyć obszar roboczy, kolekcję i środowisko.

Narzędzie Postman wprowadza koncepcję obszaru roboczego, aby umożliwić Tobie i Twojemu zespołowi udostępnianie interfejsów API, kolekcji, środowisk i innych składników. Możesz użyć domyślnego obszaru Mój obszar roboczy lub Obszar roboczy zespołu albo utworzyć nowy obszar roboczy dla Ciebie lub twojego zespołu.

Następnie utwórz nową kolekcję, w której można grupować wszystkie powiązane żądania interfejsu API REST. W obszarze roboczym wybierz pozycję Utwórz kolekcje. Możesz zachować domyślną nazwę Nowa kolekcja lub zmienić jej nazwę. Zmiana jest zapisywana automatycznie.

Można również importować i eksportować kolekcje Postman. Aby uzyskać więcej informacji, zobacz dokumentację narzędzia Postman.

Tworzenie lub aktualizowanie zmiennych środowiskowych

Mimo że w żądaniu można użyć pełnego adresu URL, zalecamy przechowywanie adresu URL i innych danych w zmiennych.

Aby uzyskać dostęp do usługi FHIR, musisz utworzyć lub zaktualizować następujące zmienne:

Zmienna	Opis	Notatki
identyfikator dzierżawy	Dzierżawa platformy Azure, w której wdrożono usługę FHIR	Omówienie rejestracji aplikacji
identyfikator subid	Subskrypcja platformy Azure, w której wdrożono usługę FHIR	Omówienie usługi FHIR
clientid	Identyfikator rejestracji klienta aplikacji
clientsecret	Wpis tajny rejestracji klienta aplikacji
fhirurl	Pełny adres URL usługi FHIR (na przykład https://xxx.azurehealthcareapis.com)	Omówienie usługi FHIR
bearerToken	Przechowuje token dostępu firmy Microsoft Entra w skrypcie	Pozostaw puste.

Uwaga

Upewnij się, że skonfigurowano adres URL https://www.getpostman.com/oauth2/callback przekierowania w rejestracji aplikacji klienckiej.

Uzyskiwanie instrukcji capability

Wprowadź {{fhirurl}}/metadata w żądaniu GET , a następnie wybierz pozycję Send. Powinna zostać wyświetlona instrukcja możliwości usługi FHIR.

Uzyskiwanie tokenu dostępu Microsoft Entra

Uzyskaj token dostępu firmy Microsoft Entra, wybierając jednostkę usługi lub konto użytkownika Microsoft Entra.

Używanie jednostki usługi z typem udzielenia poświadczeń klienta

Usługa FHIR jest zabezpieczona przez identyfikator Firmy Microsoft Entra. Nie można wyłączyć domyślnego uwierzytelniania. Aby uzyskać dostęp do usługi FHIR, najpierw musisz uzyskać token dostępu firmy Microsoft Entra. Aby uzyskać więcej informacji, zobacz Platforma tożsamości Microsoft tokeny dostępu.

Utwórz nowe POST żądanie:

1. Wprowadź nagłówek żądania: https://login.microsoftonline.com/{{tenantid}}/oauth2/token

2. Wybierz kartę Treść i wybierz pozycję x-www-form-urlencoded. Wprowadź następujące wartości w sekcji klucz i wartość:

   • grant_type:Client_Credentials
   • client_id:{{clientid}}
   • client_secret:{{clientsecret}}
   • zasób: {{fhirurl}}

Uwaga

W scenariuszach, w których parametr odbiorców usługi FHIR nie jest mapowany na adres URL punktu końcowego usługi FHIR, wartość parametru zasobu powinna być mapowana na wartość odbiorców w okienku Uwierzytelnianie usługi FHIR.

3. Wybierz kartę Test i wprowadź ciąg pm.environment.set("bearerToken", pm.response.json().access_token); w sekcji tekstowej. Aby udostępnić wartość kolekcji, użyj metody pm.collectionVariables.set. Aby uzyskać więcej informacji na temat metody set i jej poziomu zakresu, zobacz Używanie zmiennych w skryptach.
4. Wybierz pozycję Zapisz, aby zapisać ustawienia.
5. Wybierz Wyślij. Powinna zostać wyświetlona odpowiedź z tokenem dostępu firmy Microsoft Entra, który jest automatycznie zapisywany w zmiennej bearerToken. Następnie można go używać we wszystkich żądaniach interfejsu API usługi FHIR.

Token dostępu można sprawdzić przy użyciu narzędzi online, takich jak https://jwt.ms. Wybierz kartę Oświadczenia, aby wyświetlić szczegółowe opisy dla każdego oświadczenia w tokenie.

Używanie konta użytkownika z typem udzielania kodu autoryzacji

Token dostępu microsoft Entra można uzyskać przy użyciu poświadczeń konta Microsoft Entra i wykonując wymienione kroki.

1. Sprawdź, czy jesteś członkiem dzierżawy firmy Microsoft Entra z wymaganymi uprawnieniami dostępu.

2. Upewnij się, że skonfigurowano adres URL https://oauth.pstmn.io/v1/callback przekierowania dla platformy internetowej w rejestracji aplikacji klienckiej.

3. W obszarze Rejestracja aplikacji klienckiej w obszarze Uprawnienia interfejsu API dodaj uprawnienia delegowane User_Impersonation dla interfejsów API usługi Azure Healthcare z interfejsów API używanych przez moją organizację.

4. W narzędziu Postman wybierz kartę Autoryzacja kolekcji lub określonego wywołania REST, wybierz pozycję Typ jako OAuth 2.0 i w sekcji Konfigurowanie nowego tokenu ustaw następujące wartości:

   • Adres URL wywołania zwrotnego: https://oauth.pstmn.io/v1/callback

   • Adres URL uwierzytelniania: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/authorize

   • Adres URL tokenu dostępu: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token

   • Identyfikator klienta: identyfikator rejestracji klienta aplikacji

   • Klucz tajny klienta: klucz tajny rejestracji klienta aplikacji

   • Zakres: {{fhirurl}}/.default

   • Uwierzytelnianie klienta: wysyłanie poświadczeń klienta w treści

5. Wybierz pozycję Pobierz nowy token dostępu w dolnej części strony.

6. Podaj poświadczenia użytkownika na potrzeby logowania.

7. Po otrzymaniu tokenu wybierz pozycję Użyj tokenu.

8. Upewnij się, że token znajduje się w nagłówku autoryzacji wywołania REST.

Sprawdź token dostępu przy użyciu narzędzi online, takich jak https://jwt.ms. Wybierz kartę Oświadczenia, aby wyświetlić szczegółowe opisy dla każdego oświadczenia w tokenie.

Nawiązywanie połączenia z serwerem FHIR

Otwórz narzędzie Postman, wybierz obszar roboczy, kolekcję i środowisko , którego chcesz użyć. Wybierz ikonę, + aby utworzyć nowe żądanie.

Aby przeprowadzić kontrolę kondycji w usłudze FHIR, wprowadź {{fhirurl}}/health/check w żądaniu GET, a następnie wybierz pozycję Wyślij. Powinna być widoczna Status of FHIR service - HTTP Status odpowiedź kodu z wartościami 200 i OverallStatus jako w dobrej kondycji w odpowiedzi, co oznacza, że sprawdzanie kondycji zakończy się pomyślnie.

Pobieranie zasobu FHIR

Po uzyskaniu tokenu dostępu firmy Microsoft Entra możesz uzyskać dostęp do danych FHIR. W nowym GET żądaniu wprowadź .{{fhirurl}}/Patient

Wybierz pozycję Token elementu nośnego jako typ autoryzacji. Wprowadź wartość {{bearerToken}} w sekcji Token (Token ). Wybierz Wyślij. W odpowiedzi powinna zostać wyświetlona lista pacjentów w zasobie FHIR.

Tworzenie lub aktualizowanie zasobu FHIR

Po uzyskaniu tokenu dostępu firmy Microsoft Entra możesz utworzyć lub zaktualizować dane FHIR. Można na przykład utworzyć nowego pacjenta lub zaktualizować istniejącego pacjenta.

Utwórz nowe żądanie, zmień metodę na Post i wprowadź wartość w sekcji żądania.

{{fhirurl}}/Patient

Wybierz pozycję Token elementu nośnego jako typ autoryzacji. Wprowadź wartość {{bearerToken}} w sekcji Token (Token ). Wybierz kartę Treść. Wybierz nieprzetworzoną opcję i format JSON jako format tekstu treści. Skopiuj i wklej następujący tekst do sekcji treści.

{
    "resourceType": "Patient",
    "active": true,
    "name": [
        {
            "use": "official",
            "family": "Kirk",
            "given": [
                "James",
                "Tiberious"
            ]
        },
        {
            "use": "usual",
            "given": [
                "Jim"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1960-12-25"
}

Wybierz Wyślij. W odpowiedzi JSON powinien zostać wyświetlony nowy pacjent.

Eksportowanie danych FHIR

Po uzyskaniu tokenu dostępu firmy Microsoft Entra możesz wyeksportować dane FHIR do konta usługi Azure Storage.

Aby skonfigurować ustawienia eksportu i utworzyć konto usługi Data Lake Storage Gen2, zobacz Konfigurowanie ustawień eksportu.

Utwórz nowe GET żądanie: {{fhirurl}}/$export?_container=export

Wybierz pozycję Token elementu nośnego jako typ autoryzacji. Wprowadź wartość {{bearerToken}} w sekcji Token (Token ). Wybierz pozycję Nagłówki , aby dodać dwa nowe nagłówki:

• Zaakceptuj: application/fhir+json

• Preferuj: respond-async

Wybierz Wyślij. Powinna zostać wyświetlona 202 Accepted odpowiedź. Wybierz kartę Nagłówki odpowiedzi i zanotuj wartość w polu Content-Location. Tej wartości można użyć do wykonywania zapytań dotyczących stanu zadania eksportu.

Następne kroki

Kolekcja początkowa przykładowych zapytań Postman

Uwaga

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