Zugreifen auf den FHIR-Dienst mithilfe von Postman

Artikel
04/24/2024

In diesem Artikel werden die Schritte für den Zugriff auf den FHIR®-Dienst in Azure Health Data Services mit Postman beschrieben.

Voraussetzungen

FHIR-Dienst in Azure bereitgestellt. Weitere Informationen finden Sie unter Bereitstellen eines FHIR-Diensts.
Eine registrierte Clientanwendung, mit der Sie auf den FHIR-Dienst zugreifen. Weitere Informationen finden Sie unter Registrieren einer Dienstclientanwendung in Microsoft Entra ID.
Berechtigungen für FHIR-Datenmitwirkende, die der Clientanwendung und Ihrem Benutzerkonto erteilt wurden.
Eine lokale Postman-Installation. Weitere Informationen finden Sie unter Erste Schritte mit Postman.

Erstellen eines Arbeitsbereichs, einer Sammlung und einer Umgebung

Wenn Sie noch nicht mit Postman arbeiten, führen Sie die folgenden Schritte aus, um einen Arbeitsbereich, eine Sammlung und eine Umgebung zu erstellen.

Postman führt das Arbeitsbereichskonzept ein, mit dem Sie und Ihr Team APIs, Sammlungen, Umgebungen und andere Komponenten freigeben können. Sie können Mein Arbeitsbereich oder Teamarbeitsbereich standardmäßig verwenden oder einen neuen Arbeitsbereich für Sie oder Ihr Team erstellen.

Erstellen Sie als Nächstes eine neue Sammlung, in der Sie alle zugehörigen REST-API-Anforderungen gruppieren können. Wählen Sie im Arbeitsbereich Pipeline erstellen aus. Sie können den Standardnamen Neue Sammlung beibehalten oder umbenennen. Die Änderung wird automatisch gespeichert.

Sie können Postman-Sammlungen auch importieren und exportieren. Weitere Informationen finden Sie in der Postman-Dokumentation.

Erstellen oder Aktualisieren von Umgebungsvariablen

Obwohl Sie die vollständige URL in der Anforderung verwenden können, empfehlen wir, die URL und andere Daten in Variablen zu speichern.

Um auf den FHIR-Dienst zuzugreifen, müssen Sie diese Variablen erstellen oder aktualisieren:

Variable	Beschreibung	Hinweise
tenantid	Azure-Mandant, in dem der FHIR-Dienst bereitgestellt wird	Befindet sich in der Übersicht über die Anwendungsregistrierung
subid	Azure-Abonnement, in dem der FHIR-Dienst bereitgestellt wird	Befindet sich in der Übersicht über den FHIR-Dienst
clientid	Registrierungs-ID des Anwendungsclient	-
clientsecret	Registrierungsgeheinmis des Anwendungsclient	-
fhirurl	Vollständige URL des FHIR-Diensts (z. B. `https://xxx.azurehealthcareapis.com`)	Befindet sich in der Übersicht über den FHIR-Dienst
bearerToken	Speichert den Microsoft Entra-Zugriffstoken im Skript	Nicht ausfüllen

Hinweis

Stellen Sie sicher, dass Sie die Umleitungs-URL https://www.getpostman.com/oauth2/callback in der Clientanwendungsregistrierung konfiguriert haben.

Abrufen der Funktionsbestätigung

Geben Sie {{fhirurl}}/metadata in die GET-Anforderung ein, und wählen Sie dann Send aus. Die Funktionsbestätigung des FHIR-Diensts sollte angezeigt werden.

Erhalten eines Microsoft Entra-Zugriffstokens

Rufen Sie ein Microsoft Entra-Zugriffstoken mithilfe eines Dienstprinzipals oder eines Microsoft Entra-Benutzerkontos ab. Wählen Sie eine der beiden Methoden aus.

Verwenden eines Dienstprinzipals mit einem Clientanmeldeinformationserteilungstyp:

Der FHIR-Dienst wird durch Microsoft Entra ID gesichert. Die Standardauthentifizierung kann nicht deaktiviert werden. Um auf den FHIR-Dienst zuzugreifen, müssen Sie zuerst ein Microsoft Entra-Zugriffstoken abrufen. Weitere Informationen finden Sie unter Microsoft Identity Platform-Zugriffstoken.

Erstellen Sie eine neue POST-Anforderung:

Geben Sie den Anforderungsheader ein: https://login.microsoftonline.com/{{tenantid}}/oauth2/token
Wählen Sie die Registerkarte Textkörper aus, und wählen Sie x-www-form-urlencoded aus. Geben Sie im Schlüssel- und Wertabschnitt die folgenden Werte ein:
- grant_type: Client_Credentials
- client_id: {{clientid}}
- client_secret: {{clientsecret}}
- resource: {{fhirurl}}

Hinweis

In Szenarien, in denen der Parameter für die Benutzergruppengruppe des FHIR-Diensts nicht der FHIR-Dienstendpunkt-URL zugeordnet ist, sollte der Wert des Ressourcenparameters dem Zielgruppenwert im Bereich Authentifizierung des FHIR-Diensts zugeordnet werden.

Wählen Sie die Registerkarte Test aus, und geben Sie in den Textabschnitt ein: pm.environment.set("bearerToken", pm.response.json().access_token);. Verwenden Sie die pm.collectionVariables.set-Methode, um den Wert für die Auflistung verfügbar zu machen. Weitere Informationen zur Set-Methode und deren Bereichsebene finden Sie unter Verwenden von Variablen in Skripts.
Klicken Sie auf Speichern, um die Einstellungen zu speichern.
Wählen Sie Send (Senden) aus. Sie sollten eine Antwort mit dem Microsoft Entra-Zugriffstoken sehen, das automatisch in der Variablen bearerToken gespeichert wird. Sie können sie dann in allen FHIR-Dienst-API-Anforderungen verwenden.

Sie können das Zugriffstoken mithilfe von Onlinetools wie https://jwt.ms untersuchen. Wählen Sie die Registerkarte Ansprüche aus, um detaillierte Beschreibungen für jeden Anspruch im Token anzuzeigen.

Verwenden eines Benutzerkontos mit dem Autorisierungscode-Erteilungstyp

Sie können das Microsoft Entra-Zugriffstoken mit Ihren Entra-Kontoanmeldeinformationen abrufen und die aufgeführten Schritte ausführen.

Stellen Sie sicher, dass Sie Mitglied des Microsoft Entra-Mandanten mit den erforderlichen Zugriffsberechtigungen sind.
Stellen Sie sicher, dass Sie die Umleitungs-URL https://oauth.pstmn.io/v1/callback für die Webplattform in der Clientanwendungsregistrierung konfiguriert haben.
Fügen Sie in der Clientanwendungsregistrierung unter API-Berechtigungen die delegierte Berechtigung User_Impersonation für Azure Healthcare APIs aus APIs, die meine Organisation verwendet hinzu.
Wählen Sie in Postman die Registerkarte Autorisierung einer Sammlung oder eines bestimmten REST-Aufrufs aus, wählen Sie Typ als OAuth 2.0 aus, und legen Sie unter dem Abschnitt Neues Token konfigurieren die folgenden Werte fest:
- Rückruf-URL: https://oauth.pstmn.io/v1/callback
- Authentifizierungs-URL: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/authorize
- Zugriffstoken-URL: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token
- Client-ID: Registrierungs-ID des Anwendungsclient
- Geheimer Clientschlüssel: Registrierungsgeheinmis des Anwendungsclient
- Bereich:{{fhirurl}}/.default
- Clientauthentifizierung: Clientanmeldeinformationen im Textkörper senden
Wählen Sie Neues Zugriffstoken abrufen unten auf der Seite aus.
Sie werden zur Anmeldung nach Benutzeranmeldeinformationen gefragt.
Sie erhalten den Token. Wählen Sie Token verwenden aus.
Stellen Sie sicher, dass sich das Token im Autorisierungsheader des REST-Aufrufs befindet.

Untersuchen Sie das Zugriffstoken mithilfe von Onlinetools wie https://jwt.ms. Wählen Sie die Registerkarte Ansprüche aus, um detaillierte Beschreibungen für jeden Anspruch im Token anzuzeigen.

Verbinden mit dem FHIR-Server

Öffnen Sie Postman, wählen Sie den Arbeitsbereich, die Sammlung und die Umgebung aus, die Sie verwenden möchten. Erstellen Sie über das Symbol + eine neue Anforderung.

Um die Integritätsprüfung für den FHIR-Dienst durchzuführen, geben Sie {{fhirurl}}/health/check in die GET-Anforderung ein, und wählen Sie dann Senden aus. Sie sollten in der Lage sein, die Status of FHIR service - HTTP Status Codeantwort mit 200 und den OverallStatus als fehlerfrei als Antwort anzuzeigen, was bedeutet, dass die Integritätsprüfung erfolgreich ist.

Abrufen der FHIR-Ressource

Nachdem Sie ein Microsoft Entra-Zugriffstoken abgerufen haben, können Sie auf die FHIR-Daten zugreifen. Geben Sie in einer neuen GET-Anforderung {{fhirurl}}/Patient ein.

Wählen Sie Bearertoken als Autorisierungstyp aus. Geben Sie {{bearerToken}} im Abschnitt Token ein. Wählen Sie Send (Senden) aus. Als Reaktion sollte eine Liste der Patienten in Ihrer FHIR-Ressource angezeigt werden.

Erstellen oder aktualisieren Sie die FHIR-Ressource.

Nachdem Sie ein Microsoft Entra-Zugriffstoken abgerufen haben, können Sie die FHIR-Daten erstellen oder aktualisieren. Sie können z. B. einen neuen Patienten erstellen oder einen vorhandenen Patienten aktualisieren.

Erstellen Sie eine neue Anforderung, ändern Sie die Methode in Post, und geben Sie dann den Wert im Anforderungsbereich ein.

{{fhirurl}}/Patient

Wählen Sie Bearertoken als Autorisierungstyp aus. Geben Sie {{bearerToken}} im Abschnitt Token ein. Wählen Sie die Registerkarte Body (Hauptteil) aus. Wählen Sie die Option raw aus, und JSON als Textkörperformat. Kopieren Sie den Text, und fügen Sie ihn in den Textabschnitt ein.

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

Wählen Sie Send (Senden) aus. In der JSON-Antwort sollte ein neuer Patient angezeigt werden.

Exportieren von FHIR-Daten

Nachdem Sie ein Microsoft Entra-Zugriffstoken abgerufen haben, können Sie FHIR-Daten in ein Azure-Speicherkonto exportieren.

Erstellen Sie eine neue GET-Anforderung: {{fhirurl}}/$export?_container=export

Wählen Sie Bearertoken als Autorisierungstyp aus. Geben Sie {{bearerToken}} im Abschnitt Token ein. Wählen Sie Kopfzeilen aus, um zwei neue Kopfzeilen hinzuzufügen:

Akzeptieren: application/fhir+json
Bevorzugen: respond-async

Wählen Sie Send (Senden) aus. Es sollte eine 202 Accepted-Antwort angezeigt werden. Wählen Sie die Registerkarte Kopfzeilen der Antwort aus, und notieren Sie sich den Wert in Content-Location. Sie können den Wert verwenden, um den Exportauftragsstatus abzufragen.

Nächste Schritte

Starter-Sammlung von Postman-Beispielabfragen

Hinweis

FHIR® ist eine eingetragene Marke von HL7 und wird mit Genehmigung von HL7 verwendet.

Zugreifen auf den FHIR-Dienst mithilfe von Postman

Voraussetzungen

Erstellen eines Arbeitsbereichs, einer Sammlung und einer Umgebung

Erstellen oder Aktualisieren von Umgebungsvariablen

Abrufen der Funktionsbestätigung

Erhalten eines Microsoft Entra-Zugriffstokens

Verwenden eines Dienstprinzipals mit einem Clientanmeldeinformationserteilungstyp:

Verwenden eines Benutzerkontos mit dem Autorisierungscode-Erteilungstyp

Verbinden mit dem FHIR-Server

Abrufen der FHIR-Ressource

Erstellen oder aktualisieren Sie die FHIR-Ressource.

Exportieren von FHIR-Daten

Nächste Schritte

Zusätzliche Ressourcen