Přístup ke službě FHIR pomocí nástroje Postman

Tento článek popisuje kroky pro přístup ke službě FHIR® ve službě Azure Health Data Services pomocí nástroje Postman.

Požadavky

• Služba FHIR nasazená v Azure Další informace najdete v tématu Nasazení služby FHIR.
• Postman je nainstalovaný místně. Další informace najdete v tématu Začínáme s nástrojem Postman.
• Role Správce uživatelských přístupů pro přiřazení rolí ve službě FHIR

Kroky instalace

Pokud chcete získat přístup ke službě FHIR z aplikace Postman , projděte si postup:

1. Zaregistrujte klientskou aplikaci (registraci aplikace) v Microsoft Entra ID.

2. Přiřaďte roli Přispěvatel dat FHIR ve službě FHIR.

3. Nastavení Nástroje Postman – Vytvoření pracovního prostoru, kolekce a prostředí

Registrace klientské aplikace v Microsoft Entra ID

1. Na webu Azure Portal vyberte dlaždici Microsoft Entra ID .

2. V části Spravovat vyberte Registrace aplikací.

3. Vyberte + Nové registrace.

4. Zadejte název registrace aplikace. V části Podporované typy účtů vyberte Pouze účty v tomto adresáři organizace. vyberte Zaregistrovat.

ID aplikace (ID klienta)

Po registraci nové aplikace najdete ID aplikace (klienta) a ID adresáře (tenanta) v části Přehled. Poznamenejte si tyto hodnoty pro pozdější použití, protože je budete potřebovat při konfiguraci prostředí Postman.

Nastavení ověřování: důvěrné a veřejné

• Výběrem možnosti Ověřování zkontrolujte nastavení. Výchozí hodnota pro Povolit toky veřejného klienta je Ne.

• Pokud tuto výchozí hodnotu zachováte, registrace aplikace je důvěrná klientská aplikace a vyžaduje se certifikát nebo tajný klíč.

• Pokud v rozšířeném nastavení změníte výchozí hodnotu na Ano pro možnost Povolit toky veřejného klienta, registrace aplikace je veřejná klientská aplikace a certifikát nebo tajný klíč se nevyžaduje.
  

• Hodnota Ano je užitečná, když chcete v mobilní aplikaci nebo javascriptové aplikaci používat klientskou aplikaci, do které nechcete ukládat žádné tajné kódy.

• Pro nástroje, které vyžadují adresu URL pro přesměrování, vyberte Přidat platformu pro konfiguraci platformy.

• Pro Postman vyberte Mobilní a desktopové aplikace. Zadejte "https://www.getpostman.com/oauth2/callback" v části Vlastní identifikátory URI přesměrování. Výběrem tlačítka Konfigurovat uložte nastavení.

Certifikáty a tajné kódy

1. Klikněte na Certifikáty a tajné kódy. Klikněte na +Nový tajný klíč klienta.

2. V části Přidat tajný klíč klienta zadejte název tajného kódu do pole Popis . Pokyny slouží k nastavení 6 měsíců pro vypršení platnosti tajného kódu. Klikněte na tlačítko Přidat.

3. Je důležité uložit hodnotu tajného kódu, nikoli ID tajného kódu.

Poznámka:

Při pokusu o získání přístupového tokenu pro službu FHIR pomocí nástrojů, jako je Postman nebo REST Client, použijte grant_type client_credentials.

Přiřazení role Přispěvatel dat FHIR ve službě FHIR

Tato část ukazuje postup přiřazení role Přispěvatel dat FHIR zaregistrované aplikaci pro službu FHIR® ve službě Azure Health Data Services.

1. Na webu Azure Portal přejděte ke službě FHIR.

2. V nabídce vlevo vyberte okno Řízení přístupu (IAM). Klikněte na + Přidat a pak vyberte Přidat přiřazení role. Pokud možnost přidání přiřazení role není k dispozici, požádejte správce Azure, aby vám přiřadil oprávnění k provedení tohoto kroku.

3. V části Přidat přiřazení role na kartě Role se posuňte v seznamu dolů a vyberte Přispěvatel dat FHIR. Pak klikněte na tlačítko Další.

4. Na kartě Členové klikněte na +Vybrat členy. Do pole Vybrat napravo zadejte název klientské aplikace služby Postman. Vyberte aplikaci.

5. Stejným způsobem zadejte do výběru název svého uživatelského jména. Vyberte uživatele, aby se přidal do seznamu spolu s registrací aplikace a klikněte na Vybrat. Pak klikněte na tlačítko Další.

6. Na kartě Revize a přiřazení klikněte na Revize a přiřazení.

Nastavení Nástroje Postman – Vytvoření pracovního prostoru, kolekce a prostředí

Pokud s Postmanem začínáte, vytvořte pracovní prostor, kolekci a prostředí pomocí následujícího postupu.

Postman představuje koncept pracovního prostoru, který vám a vašemu týmu umožní sdílet rozhraní API, kolekce, prostředí a další komponenty. Můžete použít výchozí pracovní prostor nebo pracovní prostor týmu nebo vytvořit nový pracovní prostor pro vás nebo váš tým.

Dále vytvořte novou kolekci, ve které můžete seskupit všechny související požadavky rozhraní REST API. V pracovním prostoru vyberte Vytvořit kolekce. Můžete ponechat výchozí název Nová kolekce nebo ji přejmenovat. Změna se automaticky uloží.

Můžete také importovat a exportovat kolekce Postman. Další informace najdete v dokumentaci k nástroji Postman.

Vytvoření nebo aktualizace proměnných prostředí

I když v požadavku můžete použít úplnou adresu URL, doporučujeme uložit adresu URL a další data do proměnných.

Pokud chcete získat přístup ke službě FHIR, musíte vytvořit nebo aktualizovat tyto proměnné:

Proměnná	Popis	Poznámky
tenantid	Tenant Azure, ve kterém je nasazená služba FHIR	Nachází se v přehledu registrace aplikace.
subid	Předplatné Azure, ve kterém je nasazená služba FHIR	Přehled služby FHIR
clientid	ID registrace klienta aplikace
clientsecret	Tajný klíč registrace klienta aplikace
fhirurl	Úplná adresa URL služby FHIR (například https://xxx.azurehealthcareapis.com)	Přehled služby FHIR
bearerToken	Uloží přístupový token Microsoft Entra ve skriptu.	Ponechte prázdné.

Poznámka:

Ujistěte se, že jste v registraci klientské aplikace nakonfigurovali adresu URL https://www.getpostman.com/oauth2/callback přesměrování.

Získání příkazu capability

Zadejte {{fhirurl}}/metadata požadavek GET a pak zvolte Send. Mělo by se zobrazit prohlášení o schopnostech služby FHIR.

Získání přístupového tokenu Microsoft Entra

Získejte přístupový token Microsoft Entra tak, že zvolíte instanční objekt nebo uživatelský účet Microsoft Entra.

Použití instančního objektu s typem udělení přihlašovacích údajů klienta

Služba FHIR je zabezpečená pomocí Microsoft Entra ID. Výchozí ověřování nejde zakázat. Pokud chcete získat přístup ke službě FHIR, musíte nejprve získat přístupový token Microsoft Entra. Další informace najdete v tématu Přístupové tokeny platformy Microsoft Identity Platform.

Vytvořte nový POST požadavek:

1. Zadejte hlavičku požadavku: https://login.microsoftonline.com/{{tenantid}}/oauth2/token

2. Vyberte kartu Text a vyberte x-www-form-urlencoded. Do oddílu klíč a hodnota zadejte následující hodnoty:

   • grant_type:Client_Credentials
   • client_id:{{clientid}}
   • client_secret:{{clientsecret}}
   • zdroj: {{fhirurl}}

Poznámka:

Ve scénářích, kdy parametr cílové skupiny služby FHIR není mapován na adresu URL koncového bodu služby FHIR, by se hodnota parametru prostředku měla namapovat na hodnotu cílové skupiny v podokně ověřování služby FHIR.

3. Vyberte kartu Test a zadejte pm.environment.set("bearerToken", pm.response.json().access_token); do textového oddílu. K zpřístupnění hodnoty pro kolekci použijte metodu pm.collectionVariables.set. Další informace o metodě set a jeho úrovni oboru naleznete v tématu Použití proměnných ve skriptech.
4. Vyberte Uložit a nastavení se uloží.
5. Vyberte Odeslat. Měla by se zobrazit odpověď s přístupovým tokenem Microsoft Entra, který se automaticky uloží do proměnné bearerToken. Pak ho můžete použít ve všech požadavcích rozhraní API služby FHIR.

Přístupový token můžete prozkoumat pomocí online nástrojů, jako https://jwt.msje . Výběrem karty Deklarace zobrazíte podrobné popisy jednotlivých deklarací identity v tokenu.

Použití uživatelského účtu s typem udělení autorizačního kódu

Přístupový token Microsoft Entra můžete získat pomocí přihlašovacích údajů účtu Microsoft Entra a podle uvedených kroků.

1. Ověřte, že jste členem tenanta Microsoft Entra s požadovanými přístupovými oprávněními.

2. Ujistěte se, že jste v registraci klientské aplikace nakonfigurovali adresu URL https://oauth.pstmn.io/v1/callback přesměrování pro webovou platformu.

3. V registraci klientské aplikace v části Oprávnění rozhraní API přidejte User_Impersonation delegovaná oprávnění pro Azure Healthcare APIS z rozhraní API, která používá moje organizace.

4. V nástroji Postman vyberte kartu Autorizace kolekce nebo konkrétního volání REST, vyberte Typ jako OAuth 2.0 a v části Konfigurace nového tokenu nastavte tyto hodnoty:

   • Adresa URL zpětného volání: https://oauth.pstmn.io/v1/callback

   • Adresa URL ověřování: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/authorize

   • Adresa URL přístupového tokenu: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token

   • ID klienta: ID registrace klienta aplikace

   • Tajný klíč klienta: Tajný kód registrace klienta aplikace

   • Rozsah: {{fhirurl}}/.default

   • Ověřování klienta: Odeslání přihlašovacích údajů klienta v textu

5. V dolní části stránky zvolte Získat nový přístupový token .

6. Zadejte přihlašovací údaje uživatele pro přihlášení.

7. Jakmile token obdržíte, zvolte Použít token.

8. Ujistěte se, že token je v autorizační hlavičce volání REST.

Prozkoumejte přístupový token pomocí online nástrojů, jako https://jwt.msje . Výběrem karty Deklarace zobrazíte podrobné popisy jednotlivých deklarací identity v tokenu.

Připojení k serveru FHIR

Otevřete Nástroj Postman, vyberte pracovní prostor, kolekci a prostředí , které chcete použít. + Výběrem ikony vytvořte novou žádost.

Pokud chcete provést kontrolu stavu služby FHIR, zadejte {{fhirurl}}/health/check požadavek GET a pak zvolte Odeslat. V odpovědi by se měla zobrazit Status of FHIR service - HTTP Status odpověď kódu s 200 a OverallStatus jako v pořádku, což znamená, že kontrola stavu je úspěšná.

Získání prostředku FHIR

Po získání přístupového tokenu Microsoft Entra můžete získat přístup k datům FHIR. Do nové GET žádosti zadejte {{fhirurl}}/Patient.

Jako typ autorizace vyberte nosný token . Zadejte {{bearerToken}} do oddílu Token . Vyberte Odeslat. Jako odpověď byste měli vidět seznam pacientů ve vašem prostředku FHIR.

Vytvoření nebo aktualizace prostředku FHIR

Po získání přístupového tokenu Microsoft Entra můžete vytvořit nebo aktualizovat data FHIR. Můžete například vytvořit nového pacienta nebo aktualizovat existujícího pacienta.

Vytvořte nový požadavek, změňte metodu na Post a zadejte hodnotu v oddílu požadavku.

{{fhirurl}}/Patient

Jako typ autorizace vyberte nosný token . Zadejte {{bearerToken}} do oddílu Token . Vyberte kartu Text. Vyberte nezpracovanou možnost a JSON jako základní text. Zkopírujte následující text a vložte ho do základního oddílu.

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

Vyberte Odeslat. V odpovědi JSON by se měl zobrazit nový pacient.

Export dat FHIR

Po získání přístupového tokenu Microsoft Entra můžete exportovat data FHIR do účtu úložiště Azure.

Informace o konfiguraci nastavení exportu a vytvoření účtu Data Lake Storage Gen2 najdete v tématu Konfigurace nastavení pro export.

Vytvořte nový GET požadavek: {{fhirurl}}/$export?_container=export

Jako typ autorizace vyberte nosný token . Zadejte {{bearerToken}} do oddílu Token . Pokud chcete přidat dvě nová záhlaví, vyberte záhlaví :

• Přijmout: application/fhir+json

• Preferovat: respond-async

Vyberte Odeslat. Měli byste si všimnout 202 Accepted odpovědi. Vyberte kartu Záhlaví odpovědi a poznamenejte si hodnotu v umístění obsahu. Tuto hodnotu můžete použít k dotazování stavu úlohy exportu.

Další kroky

Úvodní kolekce ukázkových dotazů Postman

Poznámka:

FHIR® je registrovaná ochranná známka HL7 a používá se s povolením HL7.