Notificaciones de Pub/Sub de FHIR

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

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

Información general

Puedes recibir notificaciones de Pub/Sub cuando se cree, actualice, elimine o se le aplique un parche a un recurso FHIR en un almacén FHIR. La API Cloud Healthcare no envía notificaciones cuando se importa un recurso FHIR desde Cloud Storage.

Para recibir notificaciones, debes crear un tema y una suscripción de Pub/Sub, y, a continuación, configurar el almacén FHIR para que envíe notificaciones al tema.

En el siguiente diagrama se muestra cómo se crean y se envían las notificaciones de Pub/Sub cuando se crea un recurso FHIR en un almacén FHIR mediante el método fhir.create. Los pasos son los mismos cuando se actualiza, se le aplica un parche o se elimina un recurso FHIR.

Imagen 1. Usar las notificaciones de Pub/Sub para los cambios en un almacén FHIR.

En la imagen 1 se muestran los siguientes pasos:

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

Configuración de notificaciones

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

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 incluye información sobre el evento clínico. El objeto message tiene un aspecto 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:

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

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

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

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

La información de los recursos de FHIR se almacena en el campo data como una cadena codificada en base 64.

Al incluir el contenido completo de un recurso FHIR, no es necesario consultar por separado Pub/Sub y la API Cloud Healthcare para obtener los detalles del recurso.

Obtener el nombre del recurso FHIR

Para incluir solo el nombre de un recurso FHIR al crear, actualizar o aplicar un parche al recurso, asigna el valor false a sendFullResource. Para incluir solo el nombre al eliminar un recurso FHIR, asigna el valor false a sendPreviousResourceOnDelete.

Cuando veas la notificación, el objeto message tendrá un aspecto 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 define como NameOnly para indicar lo siguiente sobre la solicitud:

  • En las operaciones de creación, actualización y parche, sendFullResource se define como false.
  • En las operaciones de eliminación, sendPreviousResourceOnDelete se define como false.

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

Obtener el contenido de recursos FHIR creados, actualizados o a los que se les ha aplicado un parche

Para incluir todo el contenido de un recurso FHIR al crear, actualizar o aplicar un parche al recurso, asigna el valor true a sendFullResource.

Este comportamiento no se aplica si eliminas un recurso FHIR. Si eliminas un recurso FHIR y sendFullResource está definido como true, pero sendPreviousResourceOnDelete está definido como false, la notificación es la misma que cuando solo recuperas el nombre del recurso FHIR. Para incluir el contenido de un recurso FHIR cuando se elimina, consulta Obtener el contenido de un recurso FHIR eliminado.

Cuando veas la notificación, el objeto message tendrá un aspecto 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 define como FullResource para indicar que sendFullResource se ha definido como true. El contenido completo del recurso FHIR se incluye en el campo data como una cadena codificada en Base64.
• El campo data contiene el contenido del recurso FHIR como una cadena codificada en Base64.

Obtener el contenido de un recurso FHIR eliminado

Para incluir todo el contenido de un recurso FHIR al eliminarlo, asigna el valor sendPreviousResourceOnDelete a true.

Cuando veas la notificación, el objeto message tendrá un aspecto 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 de los siguientes campos:

• payloadType se establece en FullResource aunque sendFullResource se haya establecido en false.

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

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

Configurar y ver notificaciones de FHIR

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

Antes de empezar

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

Consultar las cuotas de Pub/Sub

Familiarízate con las cuotas y los límites de Pub/Sub. Para obtener información sobre cómo ver las cuotas, solicitar valores más altos y qué ocurre si te quedas sin cuota, consulta la documentación de cuotas de Cloud.

Habilitar la API Pub/Sub

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

Activar la API

Configurar los permisos de Pub/Sub

Para permitir la publicación de mensajes de la API Cloud Healthcare en Pub/Sub, debes añadir el rol pubsub.publisher a la cuenta de servicio del agente de servicio de Cloud Healthcare de tu proyecto. Consulta Permisos de Pub/Sub para almacenes DICOM, FHIR y HL7v2 para ver los pasos que debes seguir para añadir el rol necesario.

Crear un tema de Pub/Sub

Para crear un tema, consulta Crear un tema.

Los almacenes de datos individuales pueden tener su propio tema de Pub/Sub, o bien varios almacenes de datos pueden compartir el mismo tema.

Utiliza el siguiente formato al especificar el tema de Pub/Sub:

projects/PROJECT_ID/topics/TOPIC_NAME

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

Crear una suscripción de Pub/Sub

Para recibir mensajes publicados en un tema, debes crear una suscripción de Pub/Sub. Cada tema de Pub/Sub debe tener 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 asociarla a un tema de Pub/Sub, consulta Crear suscripciones.

Crear o editar un almacén FHIR

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

En los ejemplos siguientes se muestra cómo editar un almacén FHIR que ya existe. Los campos sendFullResource y sendPreviousResourceOnDelete se definen como true, lo que significa que las notificaciones contienen el contenido completo del recurso FHIR cuando se crea, actualiza, se le aplica un parche o se elimina.

{
  "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
    }
  ]
}

Crear un recurso FHIR

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

Ver la notificación de Pub/Sub

Consulta el mensaje publicado en el tema de Pub/Sub. El siguiente mensaje se ha generado cuando se ha creado un recurso Patient en un almacén FHIR.

En la salida de ejemplo, el contenido del recurso FHIR se encuentra 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 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 FHIR es demasiado grande o el tráfico es elevado

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

Para verificar si una notificación de Pub/Sub contiene el recurso FHIR completo, consulta el campo payloadType de la respuesta al ver la notificación. Si payloadType tiene el valor nameOnly, significa que el campo attributes no ha rellenado por completo los datos del recurso FHIR. A continuación, debes obtener el contenido del recurso FHIR manualmente del almacén FHIR en lugar de hacerlo del mensaje de Pub/Sub.

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

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

Debes definir explícitamente 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 tu conjunto de datos y tu almacén FHIR de la API Cloud Healthcare 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 Configurar políticas de almacenamiento de mensajes.

Solucionar problemas de mensajes de Pub/Sub perdidos

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

Si la tasa de generación de errores supera un límite, los errores que excedan ese límite no se enviarán a Cloud Logging.

Ver 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 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:

Siguientes pasos

• Usa el control de flujo para gestionar los picos de tráfico de mensajes transitorios de Pub/Sub.
• Gestionar fallos de mensajes.
• Volver a reproducir y eliminar mensajes definitivamente.
• Consulta la información general de la arquitectura de Pub/Sub.