Notificaciones de FHIR de Pub/Sub

En esta página, se explica cómo usar Pub/Sub para recibir notificaciones cuando se produce un evento clínico en un almacén de FHIR.

Puedes usar las notificaciones de Pub/Sub para varios casos prácticos, incluida la activación del procesamiento posterior o el análisis de datos nuevos. Por ejemplo, un modelo de aprendizaje automático puede recibir notificaciones cuando hay nuevos datos disponibles para entrenamiento y generar estadísticas o predicciones para mejorar la atención al paciente.

Descripción general

Puedes recibir notificaciones de Pub/Sub cuando se crea, actualiza, aplica parches o borra un recurso de FHIR en un almacén de FHIR. La API de Cloud Healthcare no envía notificaciones cuando un recurso de FHIR se importa desde Cloud Storage.

Para recibir notificaciones, debes crear un tema y una suscripción de Pub/Sub y, luego, configurar el almacén de FHIR para enviar notificaciones al tema.

En el siguiente diagrama, se muestra cómo se crean y entregan las notificaciones de Pub/Sub cuando se crea un recurso de FHIR en un almacén de FHIR mediante el método fhir.create. Los pasos son los mismos cuando se actualiza, se les aplican parches o se borra un recurso de FHIR.

Notificaciones de Pub/Sub de FHIR.

Figura 1. Usa notificaciones de Pub/Sub para los cambios en un almacén de FHIR.

En la Figura 1, se muestran los siguientes pasos:

  1. Un llamador realiza una solicitud fhirStores.fhir.create para crear un recurso de FHIR.
  2. El almacén de FHIR recibe la solicitud, crea un mensaje de Pub/Sub y lo envía al tema de Pub/Sub configurado en el almacén de FHIR.
  3. Pub/Sub reenvía el mensaje a las suscripciones adjuntas al tema.
  4. Los suscriptores reciben una notificación en forma de mensaje de Pub/Sub, desde su suscripción. Cada suscripción puede tener uno o más suscriptores para aumentar el paralelismo.

Configuración de notificaciones

Puedes configurar las notificaciones de Pub/Sub y su comportamiento en un objeto FhirNotificationConfig en un almacén de FHIR. Cada almacén de FHIR puede tener configurado un FhirNotificationConfig.

En la siguiente tabla, se describen los campos del objeto FhirNotificationConfig.

Campo Descripción Ejemplo
pubsubTopic El tema de Pub/Sub que se debe adjuntar al almacén de FHIR. Las notificaciones se envían al tema especificado. projects/my-project/topics/my-topic
sendFullResource Indica si se debe incluir el contenido completo de un recurso de FHIR creado, actualizado o con parches en una notificación. Este campo no tiene efecto en las notificaciones que se envían cuando se borran los recursos de FHIR. Para incluir el contenido completo de un recurso borrado, establece sendPreviousResourceOnDelete en true. true
sendPreviousResourceOnDelete Indica si se debe incluir el contenido completo de un recurso de FHIR borrado en una notificación. Este campo no tiene efecto en las notificaciones que se envían cuando se crean o actualizan recursos de FHIR, o se les aplican parches. true

Formato y contenido de las notificaciones

Cada notificación de Pub/Sub contiene un objeto message con información sobre el evento clínico. El objeto message es similar al siguiente:

{
  "message": {
    "attributes": {
      "action": "ACTION",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "PAYLOAD_TYPE",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE_64_ENCODED_DATA",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

Para obtener información sobre los campos adicionales incluidos en cada mensaje de Pub/Sub, consulta ReceivedMessage y PubsubMessage.

En la siguiente tabla, se describe cada campo del objeto attributes:

Atributo Descripción Ejemplo
action La acción que ocurrió en un recurso de FHIR. Entre los valores posibles, se incluyen los siguientes:
  • CreateResource
  • PatchResource
  • UpdateResource
  • DeleteResource
CreateResource
resourceType El tipo de recurso de FHIR que se modificó. Los valores posibles incluyen cualquier tipo de recurso FHIR compatible con la API de Cloud Healthcare. Patient
payloadType El tipo de carga útil del mensaje, que puede ser NameOnly o FullResource. FullResource
storeName El nombre completo del recurso del almacén de FHIR en el que se produjo la acción. projects/my-project/locations/us/datasets/my-dataset/fhirStores/my-fhir-store
lastUpdatedTime Una marca de tiempo de la hora más reciente en que se modificó el recurso de FHIR. La marca de tiempo usa el formato RFC 1123. Mon, 01 Jan 2020 00:00:00 UTC
versionId El ID de la versión más reciente del recurso de FHIR en el que se produjo la acción. Para obtener más información sobre los IDs de versión, consulta Enumera las versiones de recursos de FHIR. MTY4MzA2MDQzOTI5NjIxMDAwMA

En la siguiente tabla, se describen los campos restantes del objeto message:

Campo Descripción Ejemplo
data Una string codificada en base 64 del nombre del recurso de FHIR o del contenido del recurso de FHIR, según los valores especificados en FhirNotificationConfig.
messageId Un identificador para el mensaje de Pub/Sub.
publishTime La hora a la que el servidor de Pub/Sub publicó el mensaje.

Especifica la información que se incluirá en las notificaciones

Las notificaciones de Pub/Sub, como se detalla en Formato y contenido de la notificación, incluyen un conjunto estándar de campos. Puedes incluir el recurso de FHIR completo o solo su nombre en cada notificación. El nombre del recurso contiene la ruta de acceso completa al recurso y el ID del recurso en este formato:

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID

La información del recurso de FHIR se almacena en el campo data como una string codificada en base 64.

Cuando incluyes el contenido completo de un recurso de FHIR, no necesitas consultar por separado a Pub/Sub y la API de Cloud Healthcare para obtener los detalles de los recursos.

Obtén el nombre del recurso de FHIR

Para incluir solo el nombre de un recurso de FHIR cuando lo creas, actualizas o le aplicas un parche, establece sendFullResource en false. Para incluir solo el nombre cuando borres un recurso de FHIR, establece sendPreviousResourceOnDelete en false.

Cuando ves la notificación, el objeto message es similar al siguiente:

{
  "message": {
    "attributes": {
      "action": "{CreateResource|PatchResource|UpdateResource|DeleteResource}",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "NameOnly",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE64_ENCODED_FHIR_RESOURCE_NAME",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

Ten en cuenta lo siguiente en la notificación:

  • El campo payloadType se configura como NameOnly para indicar lo siguiente sobre la solicitud:

    • Para las operaciones de creación, actualización y aplicación de parches, sendFullResource se configura como false.
    • Para las operaciones de eliminación, sendPreviousResourceOnDelete se configura como false.
  • Solo se incluye el nombre del recurso de FHIR en el campo data. El nombre está codificado como una string codificada en base 64.

Obtén el contenido de los recursos de FHIR creados, actualizados o con parches

Para incluir el contenido completo de un recurso de FHIR cuando lo creas, actualizas o le aplicas un parche, establece sendFullResource en true.

Este comportamiento no se aplica si borras un recurso de FHIR. Si borras un recurso de FHIR y sendFullResource se establece en true, pero sendPreviousResourceOnDelete se establece en false, la notificación será la misma que cuando solo recuperas el nombre del recurso de FHIR. Para incluir el contenido de los recursos de FHIR cuando se borra un recurso de FHIR, consulta cómo obtener el contenido de los recursos de FHIR borrados.

Cuando ves la notificación, el objeto message es similar al siguiente:

{
  "message": {
    "attributes": {
      "action": "{CreateResource|PatchResource|UpdateResource}",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "FullResource",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE64_ENCODED_FHIR_RESOURCE_CONTENTS",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

Ten en cuenta lo siguiente en la notificación:

  • payloadType se configura como FullResource para indicar que sendFullResource se estableció en true. El contenido completo del recurso de FHIR se incluye en el campo data como una string codificada en base 64.
  • El campo data incluye el contenido de los recursos de FHIR como una string codificada en base 64.

Obtén el contenido de los recursos de FHIR borrados

Para incluir todo el contenido de un recurso de FHIR cuando lo borras, establece sendPreviousResourceOnDelete en true.

Cuando ves la notificación, el objeto message es similar al siguiente:

{
  "message": {
    "attributes": {
      "action": "DeleteResource",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "FullResource",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE64_ENCODED_FHIR_RESOURCE_CONTENTS",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

Anota los valores en los siguientes campos:

  • payloadType se establece en FullResource incluso si sendFullResource se establece en false.

    El contenido completo del recurso de FHIR se incluye en el campo data como una string codificada en base 64.

  • El campo data incluye el contenido del recurso de FHIR como una string codificada en base 64 antes de que se borre el recurso.

Configura y visualiza notificaciones de FHIR

En los siguientes ejemplos, se muestra cómo ver la notificación de Pub/Sub generada cuando se crea un recurso de FHIR en un almacén de FHIR.

Antes de comenzar

Antes de configurar y usar las notificaciones de Pub/Sub, completa las siguientes secciones:

Revisa la cuota de Pub/Sub

Familiarízate con las cuotas y los límites de Pub/Sub. Si quieres obtener información para ver tu cuota, solicitar más cuota y qué sucede si te quedas sin cuota, consulta Trabaja con cuotas.

Habilita la API de Pub/Sub

En la consola de Google Cloud, habilita la API de Pub/Sub:

Habilitar la API

Configura los permisos de Pub/Sub

Para permitir que los mensajes se publiquen desde la API de Cloud Healthcare en Pub/Sub, debes agregar la función pubsub.publisher a la cuenta de servicio del agente de servicios de Cloud Healthcare de tu proyecto. Consulta los permisos de Pub/Sub para los almacenes de DICOM, FHIR y HL7v2 y sigue los pasos para agregar la función necesaria.

Crear un tema de Pub/Sub

Para crear un tema, consulta Cómo crear un tema.

Los almacenes de datos individuales pueden tener su propio tema de Pub/Sub, o múltiples almacenes de datos pueden compartir el mismo tema.

Usa el siguiente formato cuando especifiques el tema de Pub/Sub:

projects/PROJECT_ID/topics/TOPIC_NAME

PROJECT_ID es el ID del proyecto de Google Cloud y TOPIC_NAME es el nombre del tema de Pub/Sub.

Crea una suscripción a Pub/Sub

Para recibir mensajes publicados en un tema, debes crear una suscripción a Pub/Sub. Cada tema de Pub/Sub necesita al menos una suscripción de Pub/Sub. La suscripción conecta el tema a una aplicación de suscriptor que recibe y procesa los mensajes publicados en el tema.

Para crear una suscripción y adjuntarla a un tema de Pub/Sub, consulta Cómo crear suscripciones.

Crea o edita un almacén de FHIR

Crea o edita un almacén de FHIR con un objeto FhirNotificationConfig configurado.

En los siguientes ejemplos, se muestra cómo editar un almacén de FHIR existente. Los campos sendFullResource y sendPreviousResourceOnDelete se configuran como true, lo que significa que las notificaciones contienen el contenido completo de los recursos de FHIR cuando se crea, se actualiza, se aplica parches o se borra un recurso.

REST

Para editar el almacén de FHIR, usa el método projects.locations.datasets.fhirStores.patch.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_IDEl ID de tu proyecto de Google Cloud.
  • LOCATION: La ubicación del conjunto de datos
  • DATASET_ID es el conjunto de datos superior del almacén de FHIR
  • FHIR_STORE_ID: El ID del almacén de FHIR.
  • PUBSUB_TOPIC_ID: el ID del tema de Pub/Sub.

Cuerpo JSON de la solicitud:

{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

cat > request.json << 'EOF'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}
EOF

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=notificationConfigs"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

@'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=notificationConfigs" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Crea un recurso de FHIR

Crea un recurso de FHIR en el almacén de FHIR. La solicitud hace que la API de Cloud Healthcare publique un mensaje en el tema de Pub/Sub configurado.

Visualiza la notificación de Pub/Sub

Visualiza el mensaje publicado en el tema de Pub/Sub. El siguiente mensaje se generó cuando se creó un recurso de paciente en un almacén de FHIR.

En el resultado de muestra, el contenido del recurso de FHIR está en una string codificada en base64 en el campo data. Debes decodificar el valor codificado en base64 para obtener el contenido. La mayoría de las plataformas y sistemas operativos tienen herramientas para decodificar texto base64.

REST

Para ver el mensaje publicado en el tema de Pub/Sub, usa el método projects.subscriptions.pull. En el siguiente ejemplo, se usa el parámetro de consulta ?maxMessages=10 para especificar la cantidad máxima de mensajes que se pueden mostrar en la solicitud. Puedes ajustar el valor para que se adapte a tus necesidades.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_IDEl ID de tu proyecto de Google Cloud.
  • PUBSUB_SUBSCRIPTION_ID: El ID de la suscripción adjunta al tema de Pub/Sub configurado en el almacén de FHIR

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
"https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=10"

PowerShell

Ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=10" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

gcloud

Para ver el mensaje publicado en el tema de Pub/Sub, ejecuta el comando gcloud pubsub subscriptions pull.

En la muestra, se usan las siguientes marcas de Google Cloud CLI:

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • PROJECT_IDEl ID de tu proyecto de Google Cloud.
  • PUBSUB_SUBSCRIPTION_ID: El ID de la suscripción adjunta al tema de Pub/Sub configurado en el almacén de FHIR

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud pubsub subscriptions pull \
    projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID \
    --auto-ack \
    --format=json

Windows (PowerShell)

gcloud pubsub subscriptions pull `
    projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID `
    --auto-ack `
    --format=json

Windows (cmd.exe)

gcloud pubsub subscriptions pull ^
    projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ^
    --auto-ack ^
    --format=json

Deberías recibir una respuesta similar a la que figura a continuación:

[
  {
    "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
    "ackStatus": "SUCCESS",
    "message": {
      "attributes": {
        "action": "CreateResource",
        "lastUpdatedTime": "Mon, 01 Jan 2020 00:00:00 UTC",
        "payloadType": "FullResource",
        "resourceType": "Patient",
        "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
        "versionId": "MTY4MzA2MDQzOTI5NjIxMDAwMA"
      },
      "data": "wogICJiaXJ0aERhdGUiOiAiMTk3MC0wMS0wMSIsCiAgImdlbmRlciI6ICJmZW1hbGUiLAogICJpZCI6ICIyYmMwODg4Yi00MGRmLTQwYzctOWRhYi0wMzc4YTFiZWE0MGIiLAogICJtZXRhIjogewogICAgImxhc3RVcGRhdGVkIjogIjIwMjMtMDUtMDJUMjA6NDc6MTkuMjk2MjEwKzAwOjAwIiwKICAgICJ2ZXJzaW9uSWQiOiAiTVRZNE16QTJNRFF6T1RJNU5qSXhNREF3TUEiCiAgfSwKICAibmFtZSI6IFsKICAgIHsKICAgICAgImZhbWlseSI6ICJTbWl0aCIsCiAgICAgICJnaXZlbiI6IFsKICAgICAgICAiRGFyY3kiCiAgICAgIF0sCiAgICAgICJ1c2UiOiAib2ZmaWNpYWwiCiAgICB9CiAgXSwKICAicmVzb3VyY2VUeXBlIjogIlBhdGllbnQiCn0=",
      "messageId": "7586159156345265",
      "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
    }
  }
]

Comportamiento cuando un recurso de FHIR es demasiado grande o el tráfico es alto

Si el tamaño de un recurso de FHIR es demasiado grande o los servidores de la API de Cloud Healthcare tienen mucho tráfico, es posible que el campo attributes solo contenga el nombre del recurso en lugar de todo el contenido del recurso. Este comportamiento ocurre incluso si sendFullResource y sendPreviousResourceOnDelete se configuran como true.

Para verificar si una notificación de Pub/Sub contiene el recurso de FHIR completo, verifica el campo payloadType en la respuesta de la visualización de la notificación. Si payloadType se establece como nameOnly, el campo attributes no propagaba por completo los datos del recurso de FHIR. Luego, debes obtener el contenido del recurso de FHIR de forma manual desde el almacén de FHIR, en lugar del mensaje de Pub/Sub.

Política de almacenamiento de mensajes de Pub/Sub y API de Cloud Healthcare

Para asegurarte de que tus datos de la API de Cloud Healthcare y los datos asociados en los mensajes de Pub/Sub residan en la misma región, debes establecer una política de almacenamiento de mensajes de Pub/Sub.

Debes configurar de forma explícita la política de almacenamiento de mensajes en el tema de Pub/Sub configurado en el almacén de datos para asegurarte de que los datos permanezcan en la misma región. Por ejemplo, si el conjunto de datos de la API de Cloud Healthcare y el almacén de FHIR están en us-central1, la política de almacenamiento de mensajes solo debe permitir la región us-central1.

Para configurar una política de almacenamiento de mensajes, consulta Configura políticas de almacenamiento de mensajes.

Soluciona problemas de mensajes perdidos de Pub/Sub

Si no se puede publicar una notificación en Pub/Sub, se registra un error en Cloud Logging. Para obtener más información, consulta Visualiza los registros de errores en Cloud Logging.

Si la tasa de generación de errores excede un límite, los errores que superen el límite no se enviarán a Cloud Logging.

Visualiza notificaciones de FHIR con la configuración NotificationConfig (obsoleta)

El recurso FhirStore contiene un objeto NotificationConfig en el que puedes especificar un tema de Pub/Sub. Los cambios en los recursos de FHIR siempre contienen el siguiente identificador en el campo data del mensaje de Pub/Sub:

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID

El siguiente conjunto de pares clave-valor siempre se incluye en el campo attributes del mensaje:

Nombre del atributo Valores posibles Ejemplo Descripción
action
  • CreateResource
  • PatchResource
  • UpdateResource
  • DeleteResource
CreateResource El tipo de evento que acaba de ocurrir.
resourceType Cualquier tipo de recurso de FHIR. Patient El tipo de recurso que se modificó.

¿Qué sigue?