Accedere al servizio FHIR usando Postman

Questo articolo illustra i passaggi per accedere al servizio FHIR® in Servizi dati di integrità di Azure con Postman.

Prerequisiti

• Servizio FHIR distribuito in Azure. Per altre informazioni, vedere Distribuire un servizio FHIR.
• Postman installato in locale. Per altre informazioni, vedere Introduzione a Postman.
• Ruolo Amministratore accesso utenti per le assegnazioni di ruolo nel servizio FHIR.

Passaggi di configurazione

Per accedere al servizio FHIR dall'applicazione Postman , esaminare i passaggi seguenti:

1. Registrare un'applicazione client (Registrazione app) in Microsoft Entra ID.

2. Assegnare il ruolo Collaboratore dati FHIR nel servizio FHIR.

3. Configurare Postman - Creare un'area di lavoro, una raccolta e un ambiente

Registrare un'applicazione client in Microsoft Entra ID

1. Nel portale di Azure selezionare il riquadro Microsoft Entra ID.

2. Selezionare Registrazioni app nella sezione Gestisci.

3. Selezionare + Nuove registrazioni.

4. Immettere un nome per la registrazione dell'app. In Tipi di account supportati selezionare Account solo in questa directory dell'organizzazione. selezionare Registra.

ID applicazione (ID client)

Dopo aver registrato una nuova applicazione, è possibile trovare l'ID applicazione (client) e l'ID directory (tenant) nella sezione Panoramica. Prendere nota di questi valori per usarli in un secondo momento, perché saranno necessari durante la configurazione dell'ambiente Postman.

Impostazione dell'autenticazione: riservata o pubblica

• Selezionare Autenticazione per esaminare le impostazioni. Il valore predefinito per Consenti i flussi client pubblici è "No".

• Se si mantiene questo valore predefinito, la registrazione dell'applicazione è un'applicazione client riservata ed è necessario un certificato o un segreto.

• Se si imposta il valore predefinito su "Sì" per l'opzione "Consenti i flussi client pubblici" nell'impostazione avanzata, la registrazione dell'applicazione è un'applicazione client pubblica e non è necessario un certificato o un segreto.
  

• Il valore "Sì" è utile quando si vuole usare l'applicazione client nella propria app per dispositivi mobili o in un'app JavaScript in cui non si desidera archiviare segreti.

• Per gli strumenti che richiedono un URL di reindirizzamento, selezionare Aggiungi una piattaforma per configurare la piattaforma.

• Per Postman, selezionare Applicazioni per dispositivi mobili e desktop. Immettere "https://www.getpostman.com/oauth2/callback" nella sezione URI di reindirizzamento personalizzati. Selezionare il pulsante Configura per salvare l'impostazione.

Certificati e segreti

1. Fare clic su Certificati e segreti. Fare clic su +Nuovo segreto client.

2. In Aggiungi un segreto client immettere un nome per il segreto nel campo Descrizione . Il materiale sussidiario prevede l'impostazione di 6 mesi per la scadenza dei segreti. Fare clic su Aggiungi.

3. È importante salvare il valore del segreto, non l'ID segreto.

Nota

Usare grant_type di client_credentials quando si tenta di ottenere un token di accesso per il servizio FHIR usando strumenti come Postman o il client REST.

Assegnare il ruolo Collaboratore dati FHIR nel servizio FHIR

Questa sezione illustra i passaggi per assegnare il ruolo Collaboratore dati FHIR a un'applicazione registrata per il servizio FHIR® in Servizi dati di integrità di Azure.

1. Nella portale di Azure passare al servizio FHIR.

2. Nel menu a sinistra selezionare il pannello Controllo di accesso (IAM). Fare clic su + Aggiungi e quindi selezionare Aggiungi assegnazione di ruolo. Se l'opzione per l'aggiunta di un'assegnazione di ruolo non è disponibile, chiedere all'amministratore di Azure di assegnare l'autorizzazione per eseguire questo passaggio.

3. In Aggiungi assegnazione di ruolo nella scheda Ruolo scorrere verso il basso nell'elenco e selezionare Collaboratore dati FHIR. Fare clic su Avanti.

4. Nella scheda Membri fare clic su +Seleziona membri. Digitare il nome dell'app client del servizio Postman nel campo Seleziona a destra. Seleziona l'app.

5. Allo stesso modo, digitare il nome del nome utente in Seleziona. Selezionare l'utente in modo che venga aggiunto all'elenco insieme alla registrazione dell'app e fare clic su Seleziona. Fare clic su Avanti.

6. Nella scheda Rivedi e assegna fare clic su Rivedi e assegna.

Configurare Postman: creare un'area di lavoro, una raccolta e un ambiente.

Se non si ha familiarità con Postman, seguire questa procedura per creare un'area di lavoro, una raccolta e un ambiente.

Postman introduce il concetto di area di lavoro per consentire all'utente e al team di condividere API, raccolte, ambienti e altri componenti. È possibile usare l’Area di lavoro personale o l’Area di lavoro del team predefinite oppure creare una nuova area di lavoro per l'utente o il team.

Creare quindi una nuova raccolta in cui è possibile raggruppare tutte le richieste API REST correlate. Nell'area di lavoro selezionare Crea raccolte. È possibile mantenere il nome predefinito Nuova raccolta o rinominarlo. La modifica viene salvata automaticamente.

È anche possibile importare ed esportare raccolte Postman. Per altre informazioni, vedere la documentazione di Postman.

Creare o aggiornare le variabili di ambiente

Sebbene sia possibile usare l'URL completo nella richiesta, è consigliabile archiviare l'URL e altri dati nelle variabili.

Per accedere al servizio FHIR, è necessario creare o aggiornare queste variabili:

Variabile	Descrizione	Note
tenantid	Tenant di Azure in cui viene distribuito il servizio FHIR	Informazioni generali sulla registrazione dell'applicazione
subid	Sottoscrizione di Azure in cui viene distribuito il servizio FHIR	Si trova nella panoramica dei servizi FHIR
clientid	ID registrazione client dell'applicazione
clientsecret	Segreto di registrazione client dell'applicazione
fhirurl	URL completo del servizio FHIR (ad esempio, https://xxx.azurehealthcareapis.com)	Si trova nella panoramica dei servizi FHIR
bearerToken	Archivia il token di accesso dDi Microsoft Entra nello script	Lasciare vuoto

Nota

Assicurarsi di aver configurato l'URL di reindirizzamento https://www.getpostman.com/oauth2/callback nella registrazione dell'applicazione client.

Ottenere la dichiarazione di funzionalità

Immettere {{fhirurl}}/metadata nella GETrichiesta, quindi scegliere Send. Verrà visualizzata l'istruzione funzionalità del servizio FHIR.

Ottenere un token di accesso di Microsoft Entra

Ottenere un token di accesso di Microsoft Entra scegliendo un'entità servizio o un account utente di Microsoft Entra.

Usare un'entità servizio con un tipo di concessione di credenziali client

Il servizio FHIR è protetto da Microsoft Entra ID. L'autenticazione predefinita non può essere disabilitata. Per accedere al servizio FHIR, è prima necessario ottenere un token di accesso di Microsoft Entra. Per altre informazioni, vedere Token di accesso di Microsoft Identity Platform.

Creare una nuova richiesta POST:

1. Immettere l'intestazione della richiesta: https://login.microsoftonline.com/{{tenantid}}/oauth2/token

2. Selezionare la scheda Corpo e selezionare x-www-form-urlencoded. Immettere i valori seguenti nella sezione chiave e valore:

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

Nota

Negli scenari in cui il parametro del gruppo di destinatari del servizio FHIR non è mappato all'URL dell'endpoint del servizio FHIR, il valore del parametro della risorsa deve essere mappato al valore del gruppo di destinatari nel riquadro Autenticazione del servizio FHIR.

3. Selezionare la scheda Test e immettere pm.environment.set("bearerToken", pm.response.json().access_token); nella sezione di testo. Per rendere disponibile il valore per la raccolta, usare il metodo pm.collectionVariables.set. Per altre informazioni sul metodo set e sul relativo livello di ambito, vedere Uso di variabili negli script.
4. Selezionare Salva per salvare le impostazioni.
5. Selezionare Invia. Verrà visualizzata una risposta con il token di accesso di Microsoft Entra, che viene salvato automaticamente nella variabile bearerToken. È quindi possibile usarlo in tutte le richieste api del servizio FHIR.

È possibile esaminare il token di accesso usando strumenti online, ad esempio https://jwt.ms. Selezionare la scheda Attestazioni per visualizzare descrizioni dettagliate per ogni attestazione nel token.

Usare un account utente con il tipo di concessione del codice di autorizzazione

È possibile ottenere il token di accesso di Microsoft Entra usando le credenziali dell'account di Microsoft Entra e seguendo i passaggi elencati.

1. Verificare di essere un membro del tenant di Microsoft Entra con le autorizzazioni di accesso necessarie.

2. Assicurarsi di aver configurato l'URL di reindirizzamento https://oauth.pstmn.io/v1/callback per la piattaforma Web nella registrazione dell'applicazione client.

3. Nella registrazione dell'applicazione client in Autorizzazioni API aggiungere l'autorizzazione delegata User_Impersonation per le API del settore sanitario di Azure dalle API usate dall'organizzazione.

4. In Postman selezionare la scheda Autorizzazione di una raccolta o una chiamata REST specifica, selezionare Tipo come OAuth 2.0 e nella sezione Configura nuovo token impostare questi valori:

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

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

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

   • ID client: ID registrazione client dell'applicazione

   • Segreto client: segreto di registrazione client dell'applicazione

   • Ambito: {{fhirurl}}/.default

   • Autenticazione client: inviare le credenziali client nel corpo

5. Scegliere Recupera nuovo token di accesso nella parte inferiore della pagina.

6. Specificare le credenziali utente per l'accesso.

7. Dopo aver ricevuto il token, scegliere Usa token.

8. Assicurarsi che il token si trova nell'intestazione di autorizzazione della chiamata REST.

Esaminare il token di accesso usando strumenti online, ad esempio https://jwt.ms. Selezionare la scheda Attestazioni per visualizzare descrizioni dettagliate per ogni attestazione nel token.

Connettersi al server FHIR

Aprire Postman, selezionare l'area di lavoro, la raccolta e l'ambiente da usare. Selezionare l'icona + per creare una nuova richiesta.

Per eseguire un controllo di integrità nel servizio FHIR, immettere {{fhirurl}}/health/check nella richiesta GET e quindi scegliere Invia. Dovrebbe essere possibile visualizzare la risposta al codice Status of FHIR service - HTTP Status con 200 e OverallStatus come integro in risposta, il che significa che il controllo integro ha esito positivo.

Ottenere la risorsa FHIR

Dopo aver ottenuto un token di accesso di Microsoft Entra, è possibile accedere ai dati FHIR. In una nuova richiesta GET, immettere {{fhirurl}}/Patient.

Selezionare Bearer Token (Token di connessione) come tipo di autorizzazione. Immettere {{bearerToken}} nella sezione Token. Selezionare Invia. Come risposta, dovrebbe essere visualizzato un elenco di pazienti nella risorsa FHIR.

Creare o aggiornare la risorsa FHIR

Dopo aver ottenuto un token di accesso di Microsoft Entra, è possibile creare o aggiornare i dati FHIR. Ad esempio, è possibile creare un nuovo paziente o aggiornare un paziente esistente.

Creare una nuova richiesta, modificare il metodo in Post e immettere il valore nella sezione della richiesta.

{{fhirurl}}/Patient

Selezionare Bearer Token (Token di connessione) come tipo di autorizzazione. Immettere {{bearerToken}} nella sezione Token. Selezionare la scheda Corpo. Selezionare l'opzione raw e JSON come formato di testo del corpo. Copiare e incollare il testo seguente nella sezione Corpo.

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

Selezionare Invia. Nella risposta JSON dovrebbe essere visualizzato un nuovo paziente.

Esportare i dati FHIR

Dopo aver ottenuto un token di accesso Microsoft Entra, è possibile esportare i dati FHIR in un account di archiviazione di Azure.

Per configurare le impostazioni di esportazione e creare un account Data Lake Storage Gen2, vedere Configurare le impostazioni per l'esportazione.

Creare una nuova richiesta GET: {{fhirurl}}/$export?_container=export

Selezionare Bearer Token (Token di connessione) come tipo di autorizzazione. Immettere {{bearerToken}} nella sezione Token. Selezionare Intestazioni per aggiungere due nuove intestazioni:

• Accetta: application/fhir+json

• Preferisci: respond-async

Selezionare Invia. Si noterà una risposta 202 Accepted. Selezionare la scheda Intestazioni della risposta e prendere nota del valore in Content-Location. È possibile usare questo valore per eseguire una query sullo stato del processo di esportazione.

Passaggi successivi

Raccolta iniziale di query di esempio Postman

Nota

FHIR® è un marchio registrato di HL7 ed è usato con l'autorizzazione di HL7.