Compartir a través de

Acceso al servicio FHIR con Postman

  • Artículo

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. Captura de pantalla que muestra la sección Microsoft Entra ID de Azure Portal.

  2. Seleccione Registros de aplicaciones en la sección Administrar. Captura de pantalla que muestra el menú Registros de aplicaciones en la sección Administrar de Microsoft Entra ID.

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

Captura de pantalla que muestra el formulario para escribir un nombre para el nuevo registro de la aplicación.

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. Captura de pantalla que muestra la página Información general de la aplicación registrada, en la que se muestra el identificador de aplicación (cliente) y el identificador de directorio (inquilino).

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. Captura de pantalla que muestra la configuración de autenticación donde

  • 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. Captura de pantalla que muestra la sección

  • 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. Captura de pantalla que muestra la sección

Certificados y secretos

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

Captura de pantalla que muestra el formulario para crear un nuevo secreto de cliente en la sección Certificados y secretos.

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

Captura de pantalla que muestra el formulario

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

Captura de pantalla que muestra el valor del secreto de cliente recién creado.

Nota:

Use grant_type de client_credentials al intentar obtener un token de acceso para el servicio FHIR mediante herramientas como Postman o Cliente de REST.

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. Captura de pantalla que muestra la hoja de control de acceso (IAM) del servicio FHIR del Azure Portal con la opción de agregar una asignación de rol.

  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. Captura de pantalla que muestra la ventana

  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. Captura de pantalla que muestra la pestaña

  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. Captura de pantalla que muestra la pestaña

  6. En la pestaña Revisar y asignar, haga clic en Revisar y asignar. Captura de pantalla que muestra la pestaña

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. Captura de pantalla que muestra la creación del área de trabajo.

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. Captura de pantalla que muestra la creación de una nueva colección.

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

Captura de pantalla que muestra la importación y exportación de colecciones.

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:

Variable Descripción Notas
tenantid Inquilino de Azure donde se implementa el servicio FHIR Información general sobre el registro de aplicaciones
subid Suscripción de Azure donde se implementa el servicio FHIR Información general sobre el servicio FHIR
clientid Identificador de registro de cliente de aplicación
clientsecret Secreto de registro de cliente de aplicación
fhirurl Dirección URL completa del servicio FHIR (por ejemplo, https://xxx.azurehealthcareapis.com) Información general sobre el servicio FHIR
bearerToken Almacena el token de acceso de Microsoft Entra en el script Déjelo en blanco

Nota:

Asegúrese de configurar la dirección URL de redireccionamiento https://www.getpostman.com/oauth2/callback en el registro de la aplicación cliente.

Captura de pantalla que muestra la variable de entorno.

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. Captura de pantalla que muestra los parámetros de la solicitud de funcionalidad.

Captura de pantalla que muestra una solicitud de guardado.

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}}

Nota:

En escenarios en los que el parámetro de audiencia del servicio FHIR no está asignado a la dirección URL del punto de conexión de servicio de FHIR, el valor del parámetro de recurso se debe asignar al valor de audiencia en el panel Autenticación del servicio FHIR.

  1. 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.
  2. Haga clic en Save (Guardar) para guardar la configuración.
  3. 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. Captura de pantalla que muestra el botón enviar.

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.

Captura de pantalla que muestra las notificaciones del token de acceso.

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. Captura de pantalla que muestra la dirección URL de devolución de llamada.

  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. Captura de pantalla que muestra los permisos de registro de aplicaciones.

Captura de pantalla que muestra la pantalla de permisos de registro de aplicaciones.

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

Captura de pantalla que muestra la pantalla de configuración.

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

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

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

  4. 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. Captura de pantalla que muestra la creación de 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. Captura de pantalla que muestra la selección del token de portador.

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. Captura de pantalla que muestra el botón Enviar para crear un nuevo paciente.

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. Captura de pantalla que muestra la respuesta aceptada de selección 202.

Pasos siguientes

Colección inicial de consultas de ejemplo de Postman

Nota:

FHIR® es una marca registrada de HL7 y se usa con su permiso.