Notificações FHIR do Pub/Sub

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

Use as notificações do Pub/Sub para vários casos de uso, incluindo acionamento do processamento downstream ou análise de novos dados. Por exemplo, um modelo de machine learning pode receber notificações quando novos dados estiverem disponíveis para treinamento e gerar insights ou previsões para melhorar o atendimento aos pacientes.

Visão geral

É possível receber notificações do Pub/Sub quando um recurso FHIR é criado, atualizado, corrigido ou excluído em um repositório 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 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, corrigido ou excluído.

Notificações FHIR do Pub/Sub.

Figura 1. Como usar notificações do Pub/Sub para alterações em um armazenamento 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. O repositório de FHIR recebe a solicitação, cria uma mensagem do Pub/Sub e a envia para o tópico do Pub/Sub configurado no repositório 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ções

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

A tabela a seguir descreve os campos no objeto FhirNotificationConfig.

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

Formato e conteúdo das notificações

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 ao seguinte:

{
  "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 compatível na API Cloud Healthcare. Patient
payloadType O tipo de payload da mensagem, que pode ser NameOnly ou FullResource. FullResource
storeName O nome completo do recurso do repositório 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 hora mais recente 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. Inclua 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 de recursos FHIR são armazenadas no campo data como uma string codificada em base64.

Ao incluir todo o conteúdo de um recurso FHIR, você não precisa consultar separadamente o Pub/Sub e a API Cloud Healthcare para saber detalhes do recurso.

Receber 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 o nome apenas quando você excluir um recurso FHIR, defina sendPreviousResourceOnDelete como false.

Quando você visualiza a notificação, o objeto message se parece com o seguinte:

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

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

Receber, atualizar ou corrigir conteúdos do recurso FHIR

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 quando você exclui 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 ele for excluído, consulte Receber conteúdos do recurso FHIR excluídos.

Quando você visualiza a notificação, o objeto message se parece com o seguinte:

{
  "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. Todo o conteúdo do recurso FHIR está incluído no campo data como uma string codificada de base 64.
  • O campo data contém o conteúdo do recurso FHIR como uma string codificada em base 64.

Receber conteúdo excluído do recurso FHIR

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 se parece com o seguinte:

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

Observe os valores nos seguintes campos:

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

    Todo o conteúdo do recurso FHIR está incluído no campo data como uma string codificada de 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 visualizar notificações FHIR

Nos exemplos a seguir, mostramos como visualizar a notificação do Pub/Sub gerada quando um recurso FHIR é criado em um repositório de FHIR.

Antes de começar

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

Revisar a cota do Pub/Sub

Conheça as cotas e limites do Pub/Sub. Para mais informações sobre como visualizar sua cota, solicitar mais cota e o que acontece se ela 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 do 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 FHIR

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

Os exemplos a seguir mostram como editar um armazenamento FHIR atual. 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, corrigido ou excluído.

REST

Para editar o repositório FHIR, use o método projects.locations.datasets.fhirStores.patch.

Antes de usar os dados da solicitação, 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

Solicitar corpo JSON: 

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

Veja a notificação do Pub/Sub

Visualizar a mensagem publicada no tópico do Pub/Sub. A mensagem a seguir foi gerada quando um recurso "Paciente" foi criado em um repositório FHIR.

Na saída de amostra, o conteúdo do recurso FHIR está em uma string codificada em base64 no campo data. Você precisa decodificar o valor codificado em base64 para receber o conteúdo. A maioria das plataformas e dos sistemas operacionais tem ferramentas para decodificar texto base64.

REST

Para ver 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, 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 no repositório 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 ver a mensagem publicada no tópico do Pub/Sub, execute o comando gcloud pubsub subscriptions pull.

O exemplo usa as seguintes sinalizações 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 no repositório FHIR

Execute o comando a seguir:

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 os servidores da API Cloud Healthcare estiverem passando por alto tráfego, o campo attributes poderá conter apenas o nome do recurso em vez do conteúdo completo do recurso. Esse comportamento vai ocorrer mesmo que sendFullResource e sendPreviousResourceOnDelete estejam definidos como true.

Para verificar se uma notificação do Pub/Sub contém o recurso FHIR completo, verifique o campo payloadType na resposta da 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, você precisa receber o conteúdo do recurso FHIR manualmente do armazenamento FHIR em vez da mensagem do Pub/Sub.

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

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.

Defina 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 de FHIR estiverem em us-central1, a política de armazenamento de mensagens precisará permitir apenas 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 acima desse limite não serão enviados ao Cloud Logging.

Visualizar 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