Notificações do Pub/Sub do FHIR

Nesta página, explicamos como usar o Pub/Sub para receber notificações quando um evento clínico ocorre em um armazenamento FHIR.

É possível usar as notificações do Pub/Sub em vários casos de uso, incluindo o acionamento do processamento ou da análise downstream de novos dados. Por exemplo, um modelo de aprendizado de máquina pode receber notificações quando novos dados estão disponíveis para treinamento e gerar insights ou previsões para melhorar o atendimento ao paciente.

Visão geral

Você pode receber notificações do Pub/Sub quando um recurso FHIR é criado, atualizado, recebe patch ou é excluído em um armazenamento FHIR. A API Cloud Healthcare não envia notificações quando um recurso FHIR é importado do Cloud Storage.

Para receber notificações, crie um tópico e uma assinatura do Pub/Sub e configure o armazenamento de FHIR para enviar notificações ao tópico.

O diagrama a seguir mostra como as notificações do Pub/Sub são criadas e entregues quando um recurso FHIR é criado em um armazenamento FHIR usando o método fhir.create. As etapas são as mesmas quando um recurso FHIR é atualizado, recebe patch ou é excluído.

Figura 1. Como usar notificações do Pub/Sub para mudanças em um repositório FHIR.

A Figura 1 mostra as seguintes etapas:

1. Um caller faz uma solicitação fhirStores.fhir.create para criar um recurso FHIR.
2. O armazenamento FHIR recebe a solicitação, cria uma mensagem do Pub/Sub e a envia para o tópico do Pub/Sub configurado no armazenamento FHIR.
3. O Pub/Sub encaminha a mensagem para as assinaturas anexadas ao tópico.
4. Os assinantes recebem uma notificação da assinatura, na forma de uma mensagem do Pub/Sub. Cada assinatura pode ter um ou mais assinantes para aumentar o paralelismo.

Configuração de notificação

É possível configurar as notificações do Pub/Sub e o comportamento delas em um objeto FhirNotificationConfig em um armazenamento FHIR. Cada repositório do FHIR pode ter vários FhirNotificationConfig configurados.

A tabela a seguir descreve os campos no objeto FhirNotificationConfig.

Formato e conteúdo da notificação

Cada notificação do Pub/Sub contém um objeto message que contém informações sobre o evento clínico. O objeto message é semelhante a este:

{
  "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 informações sobre outros campos incluídos em cada mensagem do Pub/Sub, consulte ReceivedMessage e PubsubMessage.

A tabela a seguir descreve cada campo no objeto attributes:

A tabela a seguir descreve os campos restantes no objeto message:

Especificar as informações a serem incluídas nas notificações

As notificações do Pub/Sub, conforme detalhado em Formato e conteúdo da notificação, incluem um conjunto padrão de campos. É possível incluir o recurso FHIR completo ou apenas o nome dele em cada notificação. O nome do recurso contém o caminho completo para o recurso e o ID dele neste formato:

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

As informações do recurso FHIR são armazenadas no campo data como uma string codificada em base64.

Ao incluir todo o conteúdo de um recurso FHIR, não é necessário consultar separadamente o Pub/Sub e a API Cloud Healthcare para detalhes do recurso.

Acessar o nome do recurso FHIR

Para incluir apenas o nome de um recurso FHIR ao criar, atualizar ou adicionar um patch ao recurso, defina sendFullResource como false. Para incluir apenas o nome ao excluir um recurso do FHIR, defina sendPreviousResourceOnDelete como false.

Quando você visualiza a notificação, o objeto message tem uma aparência semelhante a esta:

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

Observe o seguinte na notificação:

• O campo payloadType é definido como NameOnly para indicar o seguinte sobre a solicitação:

  • Para operações de criação, atualização e patch, sendFullResource é definido como false.
  • Para operações de exclusão, sendPreviousResourceOnDelete é definido como false.

• Apenas o nome do recurso FHIR é incluído no campo data. O nome é codificado como uma string codificada em base64.

Receber conteúdo de recursos FHIR criados, atualizados ou corrigidos

Para incluir todo o conteúdo de um recurso FHIR ao criar, atualizar ou adicionar um patch ao recurso, defina sendFullResource como true.

Esse comportamento não se aplica se você excluir um recurso FHIR. Se você excluir um recurso FHIR e sendFullResource estiver definido como true, mas sendPreviousResourceOnDelete estiver definido como false, a notificação será a mesma de quando você recupera apenas o nome do recurso FHIR. Para incluir o conteúdo do recurso FHIR quando um recurso FHIR é excluído, consulte Receber o conteúdo de recursos FHIR excluídos.

Quando você visualiza a notificação, o objeto message tem uma aparência semelhante a esta:

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

Observe o seguinte na notificação:

• payloadType é definido como FullResource para indicar que sendFullResource é definido como true. Todo o conteúdo do recurso FHIR é incluído no campo data como uma string codificada em base 64.
• O campo data contém o conteúdo do recurso FHIR como uma string codificada em base 64.

Acessar o conteúdo de recursos FHIR excluídos

Para incluir todo o conteúdo de um recurso FHIR ao excluí-lo, defina sendPreviousResourceOnDelete como true.

Quando você visualiza a notificação, o objeto message tem uma aparência semelhante a esta:

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

Anote os valores nos seguintes campos:

• payloadType é definida como FullResource mesmo que sendFullResource esteja definida como false.

  Todo o conteúdo do recurso FHIR é incluído no campo data como uma string codificada em base 64.

• O campo data contém o conteúdo do recurso FHIR como uma string codificada em base 64 antes da exclusão do recurso.

Configurar e ver notificações do FHIR

Os exemplos a seguir mostram como visualizar a notificação gerada do Pub/Sub quando um recurso FHIR é criado em um armazenamento FHIR.

Antes de começar

Antes de configurar e usar as notificações do Pub/Sub, conclua as seções a seguir:

Analisar as cotas do Pub/Sub

Familiarize-se com as cotas e limites do Pub/Sub. Para informações sobre como ver cotas, solicitar valores mais altos e o que acontece se você ficar sem cota, consulte a documentação do Cloud Quotas.

Habilitar a API Pub/Sub

No console Google Cloud , ative a API Pub/Sub:

Ativar a API

Configurar permissões do Pub/Sub

Para permitir que mensagens sejam publicadas da API Cloud Healthcare no Pub/Sub, adicione o papel pubsub.publisher à conta de serviço do Agente de serviço do Cloud Healthcare . Consulte Permissões do Pub/Sub para armazenamentos DICOM, FHIR e HL7v2 para ver as etapas e adicionar o papel necessário.

Criar um tópico do Pub/Sub

Para criar um tópico, consulte Criar um tópico.

Os armazenamentos de dados individuais podem ter um tópico próprio do Pub/Sub ou vários armazenamentos de dados podem compartilhar o mesmo tópico.

Use o seguinte formato ao especificar o tópico do Pub/Sub:

projects/PROJECT_ID/topics/TOPIC_NAME

PROJECT_ID é o ID do seu projeto Google Cloud e TOPIC_NAME é o nome do tópico do Pub/Sub.

Criar uma assinatura no Pub/Sub

Para receber mensagens publicadas em um tópico, você precisa criar uma assinatura do Pub/Sub. Cada tópico do Pub/Sub precisa de pelo menos uma assinatura do Pub/Sub. A assinatura conecta um tópico a um aplicativo do assinante, que recebe e processa as mensagens publicadas no tópico.

Para criar uma assinatura e anexá-la a um tópico do Pub/Sub, consulte Criar assinaturas.

Criar ou editar um armazenamento FHIR

Crie ou edite um armazenamento FHIR com um objeto FhirNotificationConfig configurado.

Os exemplos a seguir mostram como editar um armazenamento FHIR. Os campos sendFullResource e sendPreviousResourceOnDelete são definidos como true, o que significa que as notificações contêm todo o conteúdo do recurso FHIR quando um recurso é criado, atualizado, recebe patch ou é excluído.

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

Criar um recurso FHIR

Crie um recurso FHIR no armazenamento FHIR. A solicitação faz com que a API Cloud Healthcare publique uma mensagem no tópico do Pub/Sub configurado.

Ver a notificação do Pub/Sub

Confira a mensagem publicada no tópico do Pub/Sub. A seguinte mensagem foi gerada quando um recurso "Paciente" foi criado em um armazenamento de FHIR.

Na saída de exemplo, o conteúdo do recurso FHIR está em uma string codificada em base64 no campo data. É necessário decodificar o valor codificado em base64 para receber o conteúdo. A maioria das plataformas e dos sistemas operacionais tem ferramentas para decodificar texto em 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"
    }
  }
]

Comportamento quando um recurso FHIR é muito grande ou o tráfego é alto

Se o tamanho de um recurso FHIR for muito grande ou se os servidores da API Cloud Healthcare estiverem com tráfego alto, o campo attributes poderá conter apenas o nome do recurso em vez do conteúdo completo. Esse comportamento ocorre mesmo que sendFullResource e sendPreviousResourceOnDelete estejam definidos como true.

Para verificar se uma notificação do Pub/Sub contém o recurso FHIR completo, confira o campo payloadType na resposta ao visualizar a notificação. Se payloadType estiver definido como nameOnly, o campo attributes não terá preenchido totalmente os dados do recurso FHIR. Em seguida, é necessário extrair manualmente o conteúdo do recurso FHIR do armazenamento FHIR em vez da mensagem do Pub/Sub.

Política de armazenamento de mensagens do Pub/Sub e da API Cloud Healthcare

Para garantir que os dados da API Cloud Healthcare e os dados associados nas mensagens do Pub/Sub residam na mesma região, defina uma política de armazenamento de mensagens do Pub/Sub.

Você precisa definir explicitamente a política de armazenamento de mensagens no tópico do Pub/Sub configurado no repositório de dados para garantir que os dados permaneçam na mesma região. Por exemplo, se o conjunto de dados e o armazenamento FHIR da API Cloud Healthcare estiverem em us-central1, a política de armazenamento de mensagens só poderá permitir a região us-central1.

Para configurar uma política de armazenamento de mensagens, consulte Configurar políticas de armazenamento de mensagens.

Resolver problemas de mensagens perdidas do Pub/Sub

Se não for possível publicar uma notificação no Pub/Sub, será registrado um erro no Cloud Logging. Para mais informações, consulte Como visualizar registros de erros no Cloud Logging.

Se a taxa de geração de erros exceder um limite, os erros que ultrapassarem esse limite não serão enviados ao Cloud Logging.

Ver notificações FHIR usando a configuração NotificationConfig (descontinuada)

O recurso FhirStore contém um objeto NotificationConfig em que é possível especificar um tópico do Pub/Sub. As mudanças nos recursos FHIR sempre contêm o seguinte identificador no campo data da mensagem do Pub/Sub:

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

O seguinte conjunto de pares de chave-valor é sempre incluído no campo attributes da mensagem:

A seguir

• Use o controle de fluxo para lidar com picos de tráfego de mensagens transitórios do Pub/Sub.
• Como corrigir falhas nas mensagens.
• Repetir e limpar mensagens.
• Consulte a visão geral da arquitetura do Pub/Sub.