Notificações do Pub/Sub do FHIR

Esta página explica como usar o Pub/Sub para receber notificações quando um evento clínico ocorre em uma loja FHIR.

É possível usar as notificações do Pub/Sub para vários casos de uso, incluindo o acionamento do processamento downstream ou a análise de novos dados. Por exemplo, um modelo de aprendizado de máquina pode receber notificações quando novos dados estiverem 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 um patch ou é excluído em uma loja 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 a loja 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 um patch ou é excluído.

Notificações do Pub/Sub do FHIR.

Figura 1. Usar notificações do Pub/Sub para mudanças em uma loja FHIR.

A Figura 1 mostra as seguintes etapas:

  1. Um autor da chamada faz uma solicitação fhirStores.fhir.create para criar um recurso FHIR.
  2. A loja FHIR recebe a solicitação, cria uma mensagem do Pub/Sub e a envia para o tópico do Pub/Sub configurado na loja 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 uma loja FHIR. Cada armazenamento do FHIR pode ter um FhirNotificationConfig configurado.

A tabela a seguir descreve os campos do objeto FhirNotificationConfig.

Campo Descrição Exemplo
pubsubTopic O tópico do Pub/Sub a ser anexado ao armazenamento FHIR. As notificações são enviadas para o tópico especificado. projects/my-project/topics/my-topic
sendFullResource Incluir o conteúdo completo de um recurso FHIR criado, atualizado ou corrigido em uma notificação. Esse campo não tem efeito nas notificações enviadas quando os recursos FHIR são excluídos. Para incluir o conteúdo completo de um recurso excluído, defina sendPreviousResourceOnDelete como true. true
sendPreviousResourceOnDelete Incluir o conteúdo completo de um recurso FHIR excluído em uma notificação. Esse campo não tem efeito nas notificações enviadas quando os recursos FHIR são criados, atualizados ou corrigidos. true

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:

Atributo Descrição Exemplo
action A ação que ocorreu em um recurso FHIR. Os valores possíveis incluem:
  • CreateResource
  • PatchResource
  • UpdateResource
  • DeleteResource
CreateResource
resourceType O tipo de recurso FHIR que foi modificado. Os valores possíveis incluem qualquer tipo de recurso FHIR com suporte na API Cloud Healthcare. Patient
payloadType O tipo de payload da mensagem, NameOnly ou FullResource. FullResource
storeName O nome completo do recurso da loja FHIR em que a ação ocorreu. projects/my-project/locations/us/datasets/my-dataset/fhirStores/my-fhir-store
lastUpdatedTime Um carimbo de data/hora da última vez em que o recurso FHIR foi modificado. O carimbo de data/hora usa o formato RFC 1123. Mon, 01 Jan 2020 00:00:00 UTC
versionId O ID da versão mais recente do recurso FHIR em que a ação ocorreu. Para mais informações sobre IDs de versão, consulte Como listar versões de recursos FHIR. MTY4MzA2MDQzOTI5NjIxMDAwMA

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

Campo Descrição Exemplo
data Uma string codificada em base 64 do nome ou do conteúdo do recurso FHIR, dependendo dos valores especificados em FhirNotificationConfig.
messageId Um identificador para a mensagem do Pub/Sub.
publishTime A hora em que o servidor do Pub/Sub publicou a mensagem.

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 do recurso 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 o conteúdo completo de um recurso FHIR, você não precisa consultar separadamente o Pub/Sub e a API Cloud Healthcare para saber os detalhes do recurso.

Conseguir o nome do recurso FHIR

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

Quando você vê 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.

Acessar conteúdo de recursos FHIR criado, atualizado ou corrigido

Para incluir todo o conteúdo de um recurso FHIR ao criar, atualizar ou corrigir o 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 que quando você recupera apenas o nome do recurso FHIR. Para incluir o conteúdo do recurso FHIR quando um recurso FHIR for excluído, consulte Acessar o conteúdo do recurso FHIR excluído.

Quando você vê 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 está definido como true. O conteúdo completo do recurso FHIR é incluído no campo data como uma string codificada em base64.
  • O campo data contém o conteúdo do recurso FHIR como uma string codificada em base64.

Acessar o conteúdo do recurso FHIR excluído

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

Quando você vê 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 seja definida como false.

    O conteúdo completo do recurso FHIR é incluído no campo data como uma string codificada em base64.

  • O campo data contém o conteúdo do recurso FHIR como uma string codificada em base64 antes que o recurso fosse excluído.

Configurar e consultar notificações do FHIR

Os exemplos a seguir mostram como visualizar a notificação do Pub/Sub gerada 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 seguintes seções:

Analisar a cota do Pub/Sub

Conheça as cotas e os limites do Pub/Sub. Para informações sobre como conferir sua cota, solicitar mais cota e o que acontece se você ficar sem cota, consulte Como trabalhar com cotas.

Habilitar a API Pub/Sub

No console do 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 projeto do 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 repositório de 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 o conteúdo completo do recurso FHIR quando um recurso é criado, atualizado, corrigido ou excluído.

REST

Para editar o armazenamento FHIR, use o método projects.locations.datasets.fhirStores.patch.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud;
  • LOCATION: o local do conjunto de dados;
  • DATASET_ID: o conjunto de dados pai do armazenamento de FHIR
  • FHIR_STORE_ID: o ID de armazenamento de FHIR
  • PUBSUB_TOPIC_ID: o ID do tópico do Pub/Sub

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

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

Depois execute o comando a seguir para enviar a solicitação 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

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

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

Depois execute o comando a seguir para enviar a solicitação 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

Você receberá uma resposta JSON semelhante a esta:

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.

Conferir a notificação do Pub/Sub

Confira a mensagem publicada no tópico do Pub/Sub. A mensagem a seguir foi gerada quando um recurso de 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 acessar o conteúdo. A maioria das plataformas e dos sistemas operacionais tem ferramentas para decodificar texto em base64.

REST

Para conferir a mensagem publicada no tópico do Pub/Sub, use o método projects.subscriptions.pull. O exemplo a seguir usa o parâmetro de consulta ?maxMessages=10 para especificar o número máximo de mensagens a serem retornadas na solicitação. É possível ajustar o valor de acordo com suas necessidades.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud;
  • PUBSUB_SUBSCRIPTION_ID: o ID da assinatura anexada ao tópico do Pub/Sub configurado na loja FHIR

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte 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

execute o seguinte 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

Você receberá uma resposta JSON semelhante a esta:

gcloud

Para conferir a mensagem publicada no tópico do Pub/Sub, execute o comando gcloud pubsub subscriptions pull.

O exemplo usa as seguintes flags da Google Cloud CLI:

Antes de usar os dados do comando abaixo, faça estas substituições:

  • PROJECT_ID: o ID do seu projeto do Google Cloud;
  • PUBSUB_SUBSCRIPTION_ID: o ID da assinatura anexada ao tópico do Pub/Sub configurado na loja FHIR

Execute o seguinte comando:

Linux, macOS ou 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

Você receberá uma resposta semelhante a esta:

[
  {
    "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 intenso, o campo attributes poderá conter apenas o nome do recurso em vez do conteúdo completo. Esse comportamento ocorre mesmo se sendFullResource e sendPreviousResourceOnDelete forem definidos como true.

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

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

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

É necessário 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 da API Cloud Healthcare e o armazenamento FHIR 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 Como 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.

Conferir 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 alterações 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:

Nome do atributo Valores possíveis Exemplo Descrição
action
  • CreateResource
  • PatchResource
  • UpdateResource
  • DeleteResource
CreateResource Tipo de evento que acabou de ocorrer.
resourceType Qualquer tipo de recurso FHIR. Patient O tipo de recurso que foi modificado.

A seguir