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, lo que incluye lo que desencadena el procesamiento posterior o el análisis de nuevos datos. Por ejemplo, un de aprendizaje automático pueden recibir notificaciones cuando haya nuevos datos disponibles para el entrenamiento y generar ideas o predicciones para mejorar la atención al paciente.

Descripción general

Puedes recibir notificaciones de Pub/Sub cuando un recurso de FHIR crear, actualizar, aplicar parches o borrar en un almacén de FHIR. La API de Cloud Healthcare no enviar notificaciones cuando un recurso de FHIR se importa desde Cloud Storage.

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

En el siguiente diagrama, se muestra cómo se crean las notificaciones de Pub/Sub y se entrega cuando se crea un recurso de FHIR en un almacén de FHIR con fhir.create . Los pasos son los mismos cuando se actualiza, se aplica un parche o se borra un recurso de FHIR.

Notificaciones de Pub/Sub 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 emisor realiza una solicitud fhirStores.fhir.create para crear un recurso de FHIR.
  2. El almacén de FHIR recibe la solicitud, crea 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 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 de FhirNotificationConfig .

Campo Descripción Ejemplo
pubsubTopic El tema de Pub/Sub para adjuntar al almacén de FHIR. Las notificaciones se envían al tema especificado. projects/my-project/topics/my-topic
sendFullResource Determina si se debe incluir el contenido completo de un recurso de FHIR creado, actualizado o al que se le aplicó el parche 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 todo el contenido de un recurso borrado, establece sendPreviousResourceOnDelete en true. true
sendPreviousResourceOnDelete Determina si se incluye todo el contenido 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, actualizan o aplican parches a los recursos de FHIR. true

Formato y contenido de las notificaciones

Cada notificación de Pub/Sub contiene un message. objeto que contiene información importante sobre el acontecimiento 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 incluidos en cada mensaje de Pub/Sub, consulta consulta ReceivedMessage y PubsubMessage.

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

Atributo Descripción Ejemplo
action La acción que se produjo 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 de FHIR admitido en la API de Cloud Healthcare. Patient
payloadType El tipo de carga útil del mensaje: 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 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 los 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 su contenido, según los valores especificados en FhirNotificationConfig.
messageId Es 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: un conjunto estándar de campos. Puedes incluir el recurso de FHIR completo 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 de los recursos de FHIR se almacena en el data como una cadena codificada en base 64.

Cuando incluyes todo el contenido de un recurso de FHIR, no es necesario consultar Pub/Sub y la API de Cloud Healthcare por separado para obtener más detalles.

Obtener el nombre del recurso de FHIR

Para incluir solo el nombre de un recurso de FHIR cuando lo creas, actualizas o aplicar parches al recurso, establece sendFullResource en false. Para incluir solo el nombre cuando borras un recurso de FHIR, establece De sendPreviousResourceOnDelete a 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 establece en NameOnly para indicar lo siguiente: 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 se incluye el nombre del recurso de FHIR en el campo data. El nombre es como una cadena codificada en base 64.

Obtener contenidos de recursos de FHIR creados, actualizados o a los que se les aplican parches

Para incluir todo el contenido de un recurso de FHIR cuando creas, actualizas o aplicar parches al recurso, establece sendFullResource en true.

Este comportamiento no se aplica si borras un recurso de FHIR. Si borras un elemento Recurso de FHIR, y sendFullResource está configurado como true, pero sendPreviousResourceOnDelete esté establecido en false, la notificación será la misma que cuando solo recuperes Nombre del recurso de FHIR. Para incluir el recurso de FHIR cuando se borra un recurso de FHIR, consulta Obtén contenidos de 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 establece en FullResource para indicar que sendFullResource es se define 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 de FHIR como una string codificada en base 64.

Obtener contenidos de recursos de FHIR borrados

Para incluir todo el contenido de un recurso de FHIR cuando lo borras, haz lo siguiente: 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"
  }
}

Observa los valores en los siguientes campos:

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

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

  • El campo data incluye el contenido del recurso de 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 el archivo de Pub/Sub generado notificación 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 los 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.

Crea 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 y el ID del proyecto de Google Cloud. 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 El tema de Pub/Sub necesita al menos un archivo Pub/Sub suscripción. 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 Crea suscripciones.

Crea o edita un almacén de FHIR

Crear o editar 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. Se configuraron los campos sendFullResource y sendPreviousResourceOnDelete a true, lo que significa que las notificaciones contienen todo el contenido de los recursos de FHIR Cuando un recurso se crea, actualiza, aplica parches o borra.

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 al tema de Pub/Sub configurado.

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 de FHIR está codificado en base64 en el campo data. Debes decodificar el valor codificado en base64 para obtener los contenidos. 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 projects.subscriptions.pull . En el siguiente ejemplo, se usa el parámetro de consulta ?maxMessages=10 para especifica la cantidad máxima de mensajes que se mostrarán en la solicitud. Puedes ajustar el valor según 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 siguiente comando: gcloud pubsub subscriptions pull kubectl.

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

Antes de usar cualquiera de los datos de comando 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

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 la API de Cloud Healthcare servidores reciben mucho tráfico, es posible que el campo attributes Solo contiene el nombre del recurso, en lugar de todo el contenido del recurso. Este comportamiento ocurre incluso si sendFullResource y sendPreviousResourceOnDelete se establecieron en true.

Para verificar si una notificación de Pub/Sub contiene el recurso de FHIR completo, verifica el campo payloadType de la respuesta a partir de la visualización de la notificación. Si payloadType se establece en nameOnly, entonces El campo attributes no propagó por completo los datos del recurso de FHIR. Luego, debes obtener el contenido del recurso de FHIR manualmente desde el almacén de FHIR 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 forma explícita la política de almacenamiento de mensajes en Pub/Sub tema configurado en el almacén de datos para garantizar que los datos permanezcan 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 excede un límite, los errores que superen el límite no se envían a Cloud Logging.

Ver notificaciones de FHIR con la configuración 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 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?