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

Creación de un área de trabajo, una colección y un 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 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 mediante una entidad de servicio o una cuenta de usuario de Microsoft Entra. Elija uno de los dos métodos.

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 en la sección de texto: pm.environment.set("bearerToken", pm.response.json().access_token); 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 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.

  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

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

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

  6. Se le pedirán las credenciales de usuario para el inicio de sesión.

  7. Recibirá 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.

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 en la sección 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.

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