Acceso al servicio FHIR con Postman

En este artículo se muestran los pasos para acceder al servicio FHIR® en Azure Health Data Services con Postman.

Requisitos previos

• Servicio FHIR implementado en Azure. Para obtener más información, consulte Implementación de un servicio FHIR.
• Postman se instaló de forma local. Para obtener más información, consulte Introducción a Postman.
• Rol administrador de acceso de usuario para las asignaciones de roles en el servicio FHIR.

Configurar pasos

Para acceder al servicio FHIR desde la aplicación Postman, revise los pasos:

1. Registre una aplicación cliente (Registro de aplicaciones) en el identificador de Microsoft Entra.

2. Asigne rol de colaborador de datos de FHIR en el servicio FHIR.

3. Configuración de Postman: creación de un área de trabajo, una colección y un entorno

Registro de una aplicación cliente en Microsoft Entra ID

1. En Azure Portal, seleccione el mosaico de Microsoft Entra ID.

2. Seleccione Registros de aplicaciones en la sección Administrar.

3. Seleccione + Nuevos registros.

4. Escriba un nombre para el registro de aplicaciones. En Tipos de cuenta admitidos, seleccione Cuentas en este directorio de la organización solo. Seleccione Register (Registrar).

Id. de aplicación (id. cliente)

Después de registrar una nueva aplicación, puede encontrar el identificador de aplicación (cliente) y el identificador de directorio (inquilino) en la sección Información general. Anote estos valores para su uso posterior, ya que los necesitará al configurar el entorno de Postman.

Configuración de la autenticación: confidencial frente a pública

• Seleccione Autenticación para revisar la configuración. El valor predeterminado para Permitir flujos de clientes públicos es "No".

• Si mantiene este valor predeterminado, el registro de la aplicación es una aplicación de cliente confidencial y se requiere un certificado o secreto.

• Si cambia el valor predeterminado a "Sí" para la opción "Permitir flujos de clientes públicos" en la configuración avanzada, el registro de la aplicación es una aplicación de cliente público y no se requiere un certificado o secreto.
  

• El valor "Sí" es útil cuando desea utilizar la aplicación cliente en su aplicación móvil o en una aplicación JavaScript en la que no desea almacenar ningún secreto.

• Para las herramientas que requieren una dirección URL de redireccionamiento, seleccione Añadir una plataforma para configurar la plataforma.

• Para Postman, seleccione Aplicaciones móviles y de escritorio. Escriba "https://www.getpostman.com/oauth2/callback" en la sección URI de redireccionamiento personalizado. Seleccione el botón Configurar para guardar la configuración.

Certificados y secretos

1. Haga clic en Certificados y secretos. Haga clic en +Nuevo secreto de cliente.

2. En Agregar un secreto de cliente, escriba un nombre para el secreto en el campo Descripción. La guía consiste en establecer 6 meses para la expiración del secreto. Haga clic en Agregar.

3. Es importante guardar el valor del secreto, no el identificador del secreto.

Asignación del rol colaborador de datos de FHIR en el servicio FHIR

En esta sección se muestran los pasos para asignar rol colaborador de datos de FHIR a una aplicación registrada para el servicio FHIR® en Azure Health Data Services.

1. En Azure Portal, vaya al servicio FHIR.

2. En el menú de la izquierda, seleccione la hoja Access Control (IAM). Haga clic en + Agregar y seleccione Agregar asignación de roles. Si la opción para agregar una asignación de roles no está disponible, pida al administrador de Azure que le asigne permiso para realizar este paso.

3. En Agregar asignación de roles en la pestaña Rol, desplácese hacia abajo en la lista y seleccione Colaborador de datos de FHIR. A continuación, haga clic en Siguiente.

4. En la pestaña Miembros, haga clic en +Seleccionar miembros. Escriba el nombre de la aplicación cliente del servicio Postman en el campo Seleccionar de la derecha. Selecciona la aplicación.

5. De la misma manera, escriba el nombre del nombre de usuario en Seleccionar. Seleccione el usuario para que se agregue a la lista junto con el registro de aplicaciones y haga clic en Seleccionar. A continuación, haga clic en Siguiente.

6. En la pestaña Revisar y asignar, haga clic en Revisar y asignar.

Configurar Postman: crear área de trabajo, colección y entorno.

Si no está familiarizado con Postman, siga estos pasos para crear un área de trabajo, una colección y un entorno.

Postman introduce el concepto de área de trabajo para permitir que usted y su equipo compartan API, colecciones, entornos y otros componentes. Puede usar Mi área de trabajo o Área de trabajo de equipo predeterminados o crear una nueva área de trabajo para usted o su equipo.

A continuación, cree una nueva colección en la que pueda agrupar todas las solicitudes de API de REST relacionadas. En el área de trabajo, seleccione Crear colecciones. Puede mantener el nombre predeterminado Nueva colección o cambiarle el nombre. El cambio se guarda automáticamente.

También puede importar y exportar colecciones de Postman. Para obtener más información, consulte la documentación de Postman.

Crear o actualizar variables de entorno

Aunque puede usar la dirección URL completa en la solicitud, se recomienda almacenar la dirección URL y otros datos en variables.

Para acceder al servicio FHIR, debe crear o actualizar estas variables:

Obtención de la instrucción de funcionalidad

Escriba {{fhirurl}}/metadata en la solicitud de GET y elija Send. Debería ver la instrucción de funcionalidad del servicio FHIR.

Obtener un token de acceso de Microsoft Entra

Obtenga un token de acceso de Microsoft Entra eligiendo una entidad de servicio o una cuenta de usuario de Microsoft Entra.

Uso de una entidad de servicio con un tipo de concesión de credenciales de cliente

El servicio FHIR está protegido por Microsoft Entra ID. No se puede deshabilitar la autenticación predeterminada. Para acceder al servicio FHIR, primero debe obtener un token de acceso de Microsoft Entra. Para más información, consulte Tokens de acceso de la plataforma de identidad de Microsoft.

Cree una nueva solicitud POST:

1. Escriba el encabezado de solicitud: https://login.microsoftonline.com/{{tenantid}}/oauth2/token

2. Seleccione la pestaña Cuerpo y seleccione x-www-form-urlencoded. Escriba los siguientes valores en la sección clave y valor:

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

3. Seleccione la pestaña Prueba y escriba pm.environment.set("bearerToken", pm.response.json().access_token); en la sección de texto. Para que el valor esté disponible para la colección, use el método pm.collectionVariables.set. Para obtener más información sobre el método set y su nivel de ámbito, consulte Uso de variables en scripts.
4. Haga clic en Save (Guardar) para guardar la configuración.
5. Seleccione Enviar. Debería ver una respuesta con el token de acceso de Microsoft Entra, que se guarda en la variable bearerToken automáticamente. Después, puede usarlo en todas las solicitudes de API del servicio FHIR.

Puede examinar el token de acceso mediante herramientas en línea, como https://jwt.ms. Seleccione la pestaña Notificaciones para ver descripciones detalladas de cada notificación del token.

Uso de una cuenta de usuario con el tipo de concesión de código de autorización

Puede obtener el token de acceso de Microsoft Entra mediante las credenciales de su cuenta de Microsoft Entra y siguiendo los pasos indicados.

1. Compruebe que es miembro del inquilino de Microsoft Entra con los permisos de acceso necesarios.

2. Asegúrese de configurar la dirección URL de redireccionamiento https://oauth.pstmn.io/v1/callback para la plataforma web en el registro de la aplicación cliente.

3. En el registro de la aplicación cliente, en Permisos de API, agregue el permiso delegado User_Impersonation para las API de Azure Healthcare que mi organización usa.

4. En Postman, seleccione la pestaña Autorización de una colección o de una llamada REST específica, seleccione Tipo como OAuth 2.0 y, en la sección Configurar nuevo token, establezca estos valores:

   • Dirección URL de devolución de llamada: https://oauth.pstmn.io/v1/callback

   • Dirección URL de autenticación: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/authorize

   • Dirección URL del token de acceso: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token

   • Id. de cliente: id. de registro de cliente de aplicación

   • Secreto de cliente: secreto de registro de cliente de aplicación

   • Ámbito: {{fhirurl}}/.default

   • Autenticación de cliente: enviar credenciales de cliente en el cuerpo

5. Elija Obtener nuevo token de acceso en la parte inferior de la página.

6. Proporcione las credenciales de usuario para el inicio de sesión.

7. Una vez que reciba el token, elija Usar token.

8. Asegúrese de que el token está en el encabezado de autorización de la llamada REST.

Examine el token de acceso mediante herramientas en línea, como https://jwt.ms. Seleccione la pestaña Notificaciones para ver descripciones detalladas de cada notificación del token.

Conexión al servidor FHIR

Abra Postman, seleccione el área de trabajo, la colección y el entorno que desea usar. Seleccione el icono + para crear una nueva solicitud.

Para realizar la comprobación de estado en el servicio FHIR, escriba {{fhirurl}}/health/check en la solicitud GET y elija Enviar. Debería poder ver la respuesta de código Status of FHIR service - HTTP Status con 200 y OverallStatus como Correcto en la respuesta, lo que significa que la comprobación de estado se ha realizado correctamente.

Obtención del recurso de FHIR

Después de obtener un token de acceso de Microsoft Entra, puede acceder a los datos de FHIR. En una nueva solicitud GET, escriba {{fhirurl}}/Patient.

Seleccione Token de portador como tipo de autorización. Escriba {{bearerToken}} en la sección Token. Seleccione Enviar. Como respuesta, debería ver una lista de pacientes en el recurso de FHIR.

Creación o actualización del recurso de FHIR

Después de obtener un token de acceso de Microsoft Entra, puede crear o actualizar los datos de FHIR. Por ejemplo, puede crear un nuevo paciente o actualizar un paciente existente.

Cree una nueva solicitud, cambie el método a Publicar y, a continuación, escriba el valor en la sección de solicitud.

{{fhirurl}}/Patient

Seleccione Token de portador como tipo de autorización. Escriba {{bearerToken}} en la sección Token. Seleccione la pestaña Cuerpo. Seleccione la opción sin formato y JSON como formato de texto del cuerpo. Copie y pegue el texto siguiente en la sección de cuerpo.

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

Seleccione Enviar. Debería ver un nuevo paciente en la respuesta JSON.

Exportación de datos de FHIR

Después de obtener un token de acceso de Microsoft Entra, puede exportar datos de FHIR a una cuenta de almacenamiento de Azure.

Para configurar las opciones de exportación y crear una cuenta de Data Lake Storage Gen2, consulte Configuración de las opciones de exportación.

Cree una nueva solicitud GET: {{fhirurl}}/$export?_container=export

Seleccione Token de portador como tipo de autorización. Escriba {{bearerToken}} en la sección Token. Seleccione Encabezados para agregar dos nuevos encabezados:

• Aceptar: application/fhir+json

• Preferir: respond-async

Seleccione Enviar. Debería observar una respuesta 202 Accepted. Seleccione la pestaña Encabezados de la respuesta y anote el valor de Content-Location. Puede usar este valor para consultar el estado del trabajo de exportación.

Pasos siguientes

Colección inicial de consultas de ejemplo de Postman