Zugreifen auf den FHIR-Dienst mithilfe von Postman

Artikel
10/28/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 lokale Postman-Installation. Weitere Informationen finden Sie unter Erste Schritte mit Postman.
Benutzerzugriffsadministrator Rolle für Rollenzuweisungen für den FHIR-Dienst.

Schritte zum Einrichten

Um von der Postman-Anwendung aus auf den FHIR-Dienst zuzugreifen, führen Sie die folgenden Schritte aus:

Registrieren Sie eine Client-Anwendung (App-Registrierung) in Microsoft Entra ID.
Weisen Sie die Rolle des FHIR-Datenlieferanten im Rahmen des FHIR-Dienstes zu.
Einrichten von Postman – Erstellen eines Arbeitsbereichs, einer Sammlung und einer Umgebung

Registrieren einer Client-Anwendung bei Microsoft Entra ID

Wählen Sie im Azure-Portal die Kachel Microsoft Entra ID aus.
Wählen Sie im Abschnitt Verwalten die Option App-Registrierungen aus.
Wählen Sie + Neue Registrierungen aus.
Geben Sie einen Namen für die App-Registrierung ein. Wählen Sie unter unterstützte Kontotypen nur Konten in diesem Organisationsverzeichnis aus. Wählen Sie Registrieren aus.

Anwendungs-ID (Client ID)

Nachdem Sie eine neue Anwendung registriert haben, finden Sie die Anwendungs- (Client-)ID und die Verzeichnis- (Mandanten-)ID im Abschnitt „Übersicht“. Notieren Sie sich diese Werte für die spätere Verwendung, da Sie sie bei der Konfiguration Ihrer Postman-Umgebung benötigen werden.

Authentifizierungseinstellung: vertraulich im Vergleich mit öffentlich

Wählen Sie Authentifizierung aus, um die Einstellungen zu überprüfen. Der Standardwert für Zulassen von öffentlichen Clientflüssen ist „Nein“.
Wenn Sie diesen Standardwert beibehalten, ist die Anwendungsregistrierung eine vertrauliche Clientanwendung und ein Zertifikat oder geheimer Schlüssel ist erforderlich.
Wenn Sie den Standardwert in „Ja“ für die Option „Öffentliche Clientflüsse zulassen“ in der erweiterten Einstellung ändern, ist die Anwendungsregistrierung eine öffentliche Clientanwendung und ein Zertifikat oder geheimer Schlüssel ist nicht erforderlich.
Der Wert „Ja“ ist nützlich, wenn Sie die Clientanwendung in Ihrer mobilen App oder einer JavaScript-App verwenden möchten, in der Sie keine geheimen Schlüssel speichern möchten.
Wählen Sie für Tools, die eine Umleitungs-URL erfordern, Plattform hinzufügen aus, um die Plattform zu konfigurieren.
Wählen Sie für Postman Mobile- und Desktopanwendungen aus. Geben Sie „https://www.getpostman.com/oauth2/callback"“ in den Abschnitt „Benutzerdefinierte Umleitungs-URIs“ ein. Wählen Sie die Schaltfläche Konfigurieren aus, um die Einstellung zu speichern.

Zertifikate und Geheimnisse

Wählen Sie Zertifikate und Geheimnisse aus Wählen Sie + Neuer geheimer Clientschlüssel aus.

Geben Sie unter Clientgeheimnis hinzufügen einen Namen für das Geheimnis in das Feld Beschreibung ein. Die Richtlinie sieht vor, dass das Geheimnis sechs Monate gültig ist. Klicken Sie auf Hinzufügen.

Es ist wichtig, dass Sie den Wert des Geheimnisses speichern, nicht die Geheimnis-ID.

Hinweis

Verwenden Sie grant_type von client_credentials, wenn Sie versuchen, ein Zugriffstoken für den FHIR-Dienst mithilfe von Tools wie Postman oder REST-Client abzurufen.

Weisen Sie die Rolle „FHIR Data Contributor“ im FHIR-Dienst zu.

In diesem Abschnitt werden die Schritte zur Zuweisung der Rolle FHIR Data Contributor zu einer registrierten Anwendung für den FHIR®-Dienst in Azure Health Data Services beschrieben.

Navigieren Sie im Azure-Portal zu Ihrem FHIR-Dienst.
Wählen Sie im Menü auf der linken Seite das Blatt Zugriffssteuerung (IAM) aus. Wählen Sie „+ Hinzufügen“ und dann „Rollenzuweisung hinzufügen“ aus. Wenn die Option zum Hinzufügen einer Rollenzuweisung nicht verfügbar ist, bitten Sie Ihren Azure-Administrator, Ihnen die Berechtigung zur Durchführung dieses Schritts zuzuweisen.
Scrollen Sie bei der Rollenzuweisung Hinzufügen auf der Registerkarte Rolle in der Liste nach unten und wählen Sie FHIR Data Contributor aus. Klicken Sie dann auf Weiter.
Wählen Sie auf der Registerkarte Mitglieder die Option Mitglieder auswählen aus. Geben Sie den Namen Ihrer Postman-Service-Client-App in das Feld Auswählen auf der rechten Seite ein. Wählen Sie die App aus.
Geben Sie auf die gleiche Weise den Namen Ihres Benutzernamens in das Feld Auswählen ein. Wählen Sie Ihr Benutzerkonto aus, damit es zusammen mit der App-Registrierung zur Liste hinzugefügt wird, und wählen Sie Auswählen aus. Klicken Sie dann auf Weiter.
Wählen Sie auf der Registerkarte Überprüfen + zuweisen die Option Überprüfen + zuweisen aus.

Einrichten von 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 ab, indem Sie einen Dienstprinzipal oder ein Microsoft Entra-Benutzerkonto auswählen.

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 pm.environment.set("bearerToken", pm.response.json().access_token); in den Textabschnitt ein. Verwenden Sie die pm.collectionVariables.set-Methode, um den Wert für die Sammlung 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 Variable 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 Microsoft 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 im 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.
Geben Sie für die Anmeldung Benutzeranmeldeinformationen ein.
Nachdem Sie das Token erhalten haben, 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 eine Integritätsüberprü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 folgenden 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.

Informationen zum Konfigurieren von Exporteinstellungen und zum Erstellen eines Data Lake Storage Gen2-Kontos finden Sie unter Konfigurieren von Einstellungen für den Export.

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 diesen 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.

Freigeben über

Zugreifen auf den FHIR-Dienst mithilfe von Postman

Voraussetzungen

Schritte zum Einrichten

Registrieren einer Client-Anwendung bei Microsoft Entra ID

Anwendungs-ID (Client ID)

Authentifizierungseinstellung: vertraulich im Vergleich mit öffentlich

Zertifikate und Geheimnisse

Weisen Sie die Rolle „FHIR Data Contributor“ im FHIR-Dienst zu.

Einrichten von Postman – 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

Feedback

Zusätzliche Ressourcen