Notificaciones de Pub/Sub de FHIR

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

Puedes usar las notificaciones de Pub/Sub para varios casos de uso, como activar el procesamiento descendente o el análisis de datos nuevos. Por ejemplo, un modelo de aprendizaje automático puede recibir notificaciones cuando hay datos nuevos disponibles para el entrenamiento y generar estadísticas o predicciones para mejorar la atención de los pacientes.

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 se importa un recurso de FHIR 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 que envíe 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 con el método fhir.create. Los pasos son los mismos cuando se actualiza, se aplica un parche o se borra un recurso de FHIR.

Figura 1. Usar 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 un FhirNotificationConfig configurado.

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

Formato y contenido de las notificaciones

Cada notificación de Pub/Sub contiene un objeto message que contiene información sobre el evento clínico. El objeto message se ve 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 que se incluyen en cada mensaje de Pub/Sub, consulta ReceivedMessage y PubsubMessage.

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

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

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

Las notificaciones de Pub/Sub, como se detalla en Formato y contenido de las notificaciones, 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 el siguiente 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 cadena codificada en base 64.

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

Obtén el nombre del recurso de FHIR

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

Cuando veas la notificación, el objeto message se verá de la siguiente manera:

{
  "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 establece en NameOnly para indicar lo siguiente sobre la solicitud:

  • Para las operaciones de creación, actualización y aplicación de parches, sendFullResource se establece en false.
  • Para las operaciones de eliminación, sendPreviousResourceOnDelete se establece en false.

• Solo el nombre del recurso de FHIR se incluye en el campo data. El nombre se codifica como una cadena codificada en base 64.

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

Para incluir todo el contenido de un recurso de FHIR cuando lo creas, lo actualizas o le aplicas parches, configura sendFullResource como 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 es la misma que cuando solo recuperas el nombre del recurso de FHIR. Para incluir el contenido del recurso de FHIR cuando se borra un recurso de FHIR, consulta Cómo obtener el contenido de los recursos de FHIR borrados.

Cuando veas la notificación, el objeto message se verá de la siguiente manera:

{
  "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 establece en FullResource para indicar que sendFullResource se establece en true. El contenido completo del recurso de FHIR se incluye en el campo data como una cadena codificada en base 64.
• El campo data contiene el contenido del recurso FHIR como una cadena codificada en base 64.

Obtén el contenido de los recursos de FHIR borrados

Para incluir el contenido completo de un recurso de FHIR cuando lo borres, configura sendPreviousResourceOnDelete como true.

Cuando veas la notificación, el objeto message se verá de la siguiente manera:

{
  "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 de los siguientes campos:

• payloadType se establece como FullResource, incluso si sendFullResource se configura como false.

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

• El campo data contiene el contenido del recurso FHIR como una cadena codificada en base 64 antes de que se borrara el recurso.

Configura y visualiza las 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 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.

Crea un tema de Pub/Sub

Para crear un tema, consulta Crea 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 de tu 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 a 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 establecen en true, lo que significa que las notificaciones contienen todo el contenido del recurso de FHIR cuando se crea, actualiza, aplica un parche o se borra un recurso.

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

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

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"

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

$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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "R4",
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}

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.

Cómo ver 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 FHIR está en una cadena 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 el texto en Base64.

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"

$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

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

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

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

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

[
  {
    "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 un tráfico alto, es posible que el campo attributes solo contenga el nombre del recurso en lugar del contenido completo del recurso. Este comportamiento ocurre incluso si sendFullResource y sendPreviousResourceOnDelete se establecen en 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 configura como nameOnly, el campo attributes no propagó 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 establecer de manera 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 de Pub/Sub perdidos

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 supera la cantidad máxima, los errores por los que se excedió este límite no se envían a Cloud Logging.

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

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:

¿Qué sigue?

• Usa el control de flujo para controlar los aumentos transitorios del tráfico de mensajes de Pub/Sub.
• Controla las fallas de los mensajes.
• Vuelve a reproducir y borra definitivamente los mensajes.
• Consulta la descripción general de la arquitectura de Pub/Sub.