Toegang tot de FHIR-service met Postman

In dit artikel worden de stappen beschreven voor toegang tot de FHIR-service® in Azure Health Data Services met Postman.

Vereisten

• FHIR-service geïmplementeerd in Azure. Zie Een FHIR-service implementeren voor meer informatie.
• Postman is lokaal geïnstalleerd. Zie Aan de slag met Postman voor meer informatie.
• Beheerdersrol gebruikerstoegang voor roltoewijzingen in de FHIR-service.

Installatiestappen

Als u toegang wilt krijgen tot de FHIR-service vanuit de Postman-toepassing , raadpleegt u de stappen:

1. Registreer een clienttoepassing (App-registratie) in Microsoft Entra ID.

2. Wijs de rol FHIR-gegevensbijdrager toe onder de FHIR-service.

3. Postman instellen - Werkruimte, verzameling en omgeving maken

Een clienttoepassing registreren in Microsoft Entra ID

1. Selecteer in Azure Portal de tegel Microsoft Entra-id.

2. Selecteer App-registraties onder De sectie Beheren.

3. Selecteer + Nieuwe registraties.

4. Voer een naam in voor app-registratie. Selecteer onder Ondersteunde accounttypen alleen Accounts in deze organisatiemap. selecteer Registreren.

Toepassings-id (client-id)

Nadat u een nieuwe toepassing hebt geregistreerd, kunt u de toepassings-id (client) en map-id (tenant) vinden in de sectie Overzicht. Noteer deze waarden voor later gebruik, omdat u deze nodig hebt bij het configureren van uw Postman-omgeving.

Verificatie-instelling: vertrouwelijk versus openbaar

• Selecteer Verificatie om de instellingen te controleren. De standaardwaarde voor openbare clientstromen toestaan is Nee.

• Als u deze standaardwaarde behoudt, is de toepassingsregistratie een vertrouwelijke clienttoepassing en is een certificaat of geheim vereist.

• Als u de standaardwaarde wijzigt in Ja voor de optie Openbare clientstromen toestaan in de geavanceerde instelling, is de toepassingsregistratie een openbare clienttoepassing en is er geen certificaat of geheim vereist.
  

• De waarde Ja is handig als u de clienttoepassing in uw mobiele app of een JavaScript-app wilt gebruiken waar u geen geheimen wilt opslaan.

• Voor hulpprogramma's waarvoor een omleidings-URL is vereist, selecteert u Een platform toevoegen om het platform te configureren.

• Voor Postman selecteert u Mobiele toepassingen en bureaubladtoepassingen. Voer 'https://www.getpostman.com/oauth2/callback" in de sectie Aangepaste omleidings-URI's. Selecteer de knop Configureren om de instelling op te slaan.

Certificaten en geheimen

1. Klik op Certificaten en geheimen. Klik op +Nieuw clientgeheim.

2. Voer onder Een clientgeheim toevoegen een naam in voor het geheim in het veld Beschrijving. De richtlijnen zijn het instellen van 6 maanden voor het verlopen van geheimen. Klik op Toevoegen.

3. Het is belangrijk dat u de geheime waarde opslaat, niet de geheime id.

Notitie

Gebruik grant_type van client_credentials bij het verkrijgen van een toegangstoken voor de FHIR-service met behulp van hulpprogramma's zoals Postman of REST Client.

De rol FHIR-gegevensbijdrager toewijzen in de FHIR-service

In deze sectie ziet u de stappen voor het toewijzen van de rol FHIR-gegevensbijdrager aan een geregistreerde toepassing voor de FHIR-service® in Azure Health Data Services.

1. Navigeer in Azure Portal naar uw FHIR-service.

2. Selecteer in het linkermenu de blade Toegangsbeheer (IAM). Klik op + Toevoegen en selecteer vervolgens Roltoewijzing toevoegen. Als de optie voor het toevoegen van een roltoewijzing niet beschikbaar is, vraagt u uw Azure-beheerder om u toestemming te geven om deze stap uit te voeren.

3. Schuif in Roltoewijzing toevoegen onder het tabblad Rol omlaag in de lijst en selecteer FHIR-gegevensbijdrager. Klik op Volgende.

4. Klik op het tabblad Leden op +Leden selecteren. Typ de naam van uw Postman Service-client-app in het veld Selecteren aan de rechterkant. Selecteer de app.

5. Typ op dezelfde manier de naam van uw gebruikersnaam in de knop Selecteren. Selecteer uw gebruiker zodat deze wordt toegevoegd aan de lijst, samen met app-registratie en klik op Selecteren. Klik op Volgende.

6. Klik onder het tabblad Controleren + toewijzen op Controleren + toewijzen.

Postman instellen - Werkruimte, verzameling en omgeving maken.

Als u niet bekend bent met Postman, volgt u deze stappen om een werkruimte, verzameling en omgeving te maken.

Postman introduceert het werkruimteconcept waarmee u en uw team API's, verzamelingen, omgevingen en andere onderdelen kunnen delen. U kunt de standaardwerkruimte Mijn werkruimte of teamwerkruimte gebruiken of een nieuwe werkruimte voor u of uw team maken.

Maak vervolgens een nieuwe verzameling waarin u alle gerelateerde REST API-aanvragen kunt groeperen. Selecteer Verzamelingen maken in de werkruimte. U kunt de standaardnaam Nieuwe verzameling behouden of de naam ervan wijzigen. De wijziging wordt automatisch opgeslagen.

U kunt postman-verzamelingen ook importeren en exporteren. Zie de Postman-documentatie voor meer informatie.

Omgevingsvariabelen maken of bijwerken

Hoewel u de volledige URL in de aanvraag kunt gebruiken, raden we u aan de URL en andere gegevens op te slaan in variabelen.

Voor toegang tot de FHIR-service moet u deze variabelen maken of bijwerken:

Veranderlijk	Beschrijving	Opmerkingen
tenantid	Azure-tenant waar de FHIR-service wordt geïmplementeerd	Overzicht van toepassingsregistratie
sub-id	Azure-abonnement waarbij de FHIR-service wordt geïmplementeerd	Overzicht van de FHIR-service
clientid	Registratie-id van toepassingsclient
clientsecret	Registratiegeheim voor toepassingsclient
fhirurl	De volledige URL van de FHIR-service (bijvoorbeeld https://xxx.azurehealthcareapis.com)	Overzicht van de FHIR-service
bearerToken	Slaat het Microsoft Entra-toegangstoken op in het script	Leeg laten

Notitie

Zorg ervoor dat u de omleidings-URL https://www.getpostman.com/oauth2/callback hebt geconfigureerd in de registratie van de clienttoepassing.

De mogelijkheidsinstructie ophalen

Voer {{fhirurl}}/metadata de GET aanvraag in en kies Send. U ziet nu de mogelijkheidsinstructie van de FHIR-service.

Een Microsoft Entra-toegangstoken ophalen

Haal een Microsoft Entra-toegangstoken op door een service-principal of een Microsoft Entra-gebruikersaccount te kiezen.

Een service-principal gebruiken met een type clientreferentietoe kennen

De FHIR-service wordt beveiligd door Microsoft Entra ID. De standaardverificatie kan niet worden uitgeschakeld. Als u toegang wilt krijgen tot de FHIR-service, moet u eerst een Microsoft Entra-toegangstoken ophalen. Zie Toegangstokens voor Microsoft Identity Platform voor meer informatie.

Maak een nieuwe POST aanvraag:

1. Voer de aanvraagheader in: https://login.microsoftonline.com/{{tenantid}}/oauth2/token

2. Selecteer het tabblad Hoofdtekst en selecteer x-www-form-urlencoded. Voer de volgende waarden in de sleutel- en waardesectie in:

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

Notitie

In scenario's waarin de doelgroepparameter van de FHIR-service niet is toegewezen aan de URL van het FHIR-service-eindpunt, moet de waarde van de resourceparameter worden toegewezen aan de doelgroepwaarde in het deelvenster FHIR-serviceverificatie.

3. Selecteer het tabblad Testen en voer pm.environment.set("bearerToken", pm.response.json().access_token); de tekstsectie in. Als u de waarde beschikbaar wilt maken voor de verzameling, gebruikt u de methode pm.collectionVariables.set. Zie Variabelen gebruiken in scripts voor meer informatie over de ingestelde methode en het bereikniveau.
4. Selecteer Opslaan om de instellingen op te slaan.
5. Selecteer Verzenden. U ziet nu een antwoord met het Microsoft Entra-toegangstoken, dat automatisch wordt opgeslagen in de variabele bearerToken. U kunt deze vervolgens gebruiken in alle AANVRAGEN van de FHIR-service-API.

U kunt het toegangstoken onderzoeken met behulp van onlinehulpprogramma's zoals https://jwt.ms. Selecteer het tabblad Claims om gedetailleerde beschrijvingen voor elke claim in het token te bekijken.

Een gebruikersaccount gebruiken met het toekenningstype autorisatiecode

U kunt het Microsoft Entra-toegangstoken ophalen met de referenties van uw Microsoft Entra-account en de vermelde stappen volgen.

1. Controleer of u lid bent van de Microsoft Entra-tenant met de vereiste toegangsmachtigingen.

2. Zorg ervoor dat u de omleidings-URL https://oauth.pstmn.io/v1/callback voor het webplatform hebt geconfigureerd in de registratie van de clienttoepassing.

3. Voeg in de registratie van de clienttoepassing onder API-machtigingen de User_Impersonation gedelegeerde machtiging toe voor Azure Healthcare APIS van API's die mijn organisatie gebruikt.

4. Selecteer in Postman het tabblad Autorisatie van een verzameling of een specifieke REST-aanroep, selecteer Type als OAuth 2.0 en stel onder De sectie Nieuw token configureren de volgende waarden in:

   • Callback-URL: https://oauth.pstmn.io/v1/callback

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

   • URL van toegangstoken: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token

   • Client-id: registratie-id van toepassingsclient

   • Clientgeheim: registratiegeheim van toepassingsclient

   • Bereik: {{fhirurl}}/.default

   • Clientverificatie: clientreferenties verzenden in hoofdtekst

5. Kies Nieuw toegangstoken ophalen onder aan de pagina.

6. Geef gebruikersreferenties op voor aanmelding.

7. Zodra u het token hebt ontvangen, kiest u Token gebruiken.

8. Zorg ervoor dat het token zich in de autorisatieheader van de REST-aanroep bevindt.

Bekijk het toegangstoken met behulp van onlinehulpprogramma's zoals https://jwt.ms. Selecteer het tabblad Claims om gedetailleerde beschrijvingen voor elke claim in het token te bekijken.

Verbinding maken met de FHIR-server

Open Postman, selecteer de werkruimte, verzameling en omgeving die u wilt gebruiken. Selecteer het + pictogram om een nieuwe aanvraag te maken.

Als u een statuscontrole wilt uitvoeren op de FHIR-service, voert {{fhirurl}}/health/check u de GET-aanvraag in en kiest u Vervolgens Verzenden. U moet het Status of FHIR service - HTTP Status codeantwoord kunnen zien met 200 en OverallStatus als In orde in reactie, wat betekent dat uw statuscontrole is geslaagd.

De FHIR-resource ophalen

Nadat u een Microsoft Entra-toegangstoken hebt verkregen, hebt u toegang tot de FHIR-gegevens. Voer in een nieuwe GET aanvraag in {{fhirurl}}/Patient.

Selecteer Bearer-token als autorisatietype. Voer {{bearerToken}} in de sectie Token in. Selecteer Verzenden. Als reactie ziet u een lijst met patiënten in uw FHIR-resource.

De FHIR-resource maken of bijwerken

Nadat u een Microsoft Entra-toegangstoken hebt verkregen, kunt u de FHIR-gegevens maken of bijwerken. U kunt bijvoorbeeld een nieuwe patiënt maken of een bestaande patiënt bijwerken.

Maak een nieuwe aanvraag, wijzig de methode in Post en voer de waarde in de aanvraagsectie in.

{{fhirurl}}/Patient

Selecteer Bearer-token als autorisatietype. Voer {{bearerToken}} in de sectie Token in. Selecteer het tabblad Hoofdtekst . Selecteer de onbewerkte optie en JSON als hoofdtekstindeling. Kopieer en plak de volgende tekst in de hoofdtekstsectie.

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

Selecteer Verzenden. Als het goed is, ziet u een nieuwe patiënt in het JSON-antwoord.

FHIR-gegevens exporteren

Nadat u een Microsoft Entra-toegangstoken hebt verkregen, kunt u FHIR-gegevens exporteren naar een Azure-opslagaccount.

Als u exportinstellingen wilt configureren en een Data Lake Storage Gen2-account wilt maken, raadpleegt u Instellingen configureren voor export.

Maak een nieuwe GET aanvraag: {{fhirurl}}/$export?_container=export

Selecteer Bearer-token als autorisatietype. Voer {{bearerToken}} in de sectie Token in. Selecteer Kopteksten om twee nieuwe headers toe te voegen:

• Accepteren: application/fhir+json

• Liever: respond-async

Selecteer Verzenden. U ziet een 202 Accepted antwoord. Selecteer het tabblad Kopteksten van het antwoord en noteer de waarde in de inhoudslocatie. U kunt deze waarde gebruiken om een query uit te voeren op de status van de exporttaak.

Volgende stappen

Starterverzameling van Postman-voorbeeldquery's

Notitie

FHIR® is een geregistreerd handelsmerk van HL7 en wordt gebruikt met de machtiging HL7.