Notificações FHIR Pub/Sub

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

Pode usar as notificações do Pub/Sub para vários exemplos de utilização, incluindo o acionamento do tratamento ou da análise a jusante de novos dados. Por exemplo, um modelo de aprendizagem automática pode receber notificações quando estiverem disponíveis novos dados para preparação e gerar estatísticas ou previsões para melhorar os cuidados ao paciente.

Vista geral

Pode receber notificações do Pub/Sub quando um recurso FHIR é criado, atualizado, corrigido ou eliminado numa loja FHIR. A API Cloud Healthcare não envia notificações quando um recurso FHIR é importado do Cloud Storage.

Para receber notificações, tem de criar um tópico e uma subscrição do Pub/Sub e, em seguida, configurar o FHIR store para enviar notificações para o tópico.

O diagrama seguinte mostra como as notificações do Pub/Sub são criadas e entregues quando um recurso FHIR é criado numa loja FHIR através do método fhir.create. Os passos são os mesmos quando um recurso FHIR é atualizado, corrigido ou eliminado.

Notificações do FHIR Pub/Sub.

Figura 1. Usar notificações do Pub/Sub para alterações numa loja FHIR.

A Figura 1 mostra os seguintes passos:

  1. Um autor da chamada faz um pedido fhirStores.fhir.create para criar um recurso FHIR.
  2. O FHIR store recebe o pedido, cria uma mensagem do Pub/Sub e envia-a para o tópico do Pub/Sub configurado no FHIR store.
  3. O Pub/Sub encaminha a mensagem para as subscrições anexadas ao tópico.
  4. Os subscritores recebem uma notificação, sob a forma de uma mensagem Pub/Sub, da respetiva subscrição. Cada subscrição pode ter um ou mais subscritores para aumentar o paralelismo.

Configuração de notificações

Pode configurar as notificações do Pub/Sub e o respetivo comportamento num FhirNotificationConfig objeto numa loja FHIR. Cada FHIR store pode ter vários FhirNotificationConfig configurados.

A tabela seguinte descreve os campos no objeto FhirNotificationConfig

Campo Descrição Exemplo
pubsubTopic O tópico Pub/Sub a anexar ao FHIR store. As notificações são enviadas para o tópico especificado. projects/my-project/topics/my-topic
sendFullResource Se deve incluir o conteúdo completo de um recurso FHIR criado, atualizado ou corrigido numa notificação. Este campo não tem efeito nas notificações enviadas quando os recursos FHIR são eliminados. Para incluir o conteúdo completo de um recurso eliminado, defina sendPreviousResourceOnDelete como true. true
sendPreviousResourceOnDelete Se deve incluir o conteúdo completo de um recurso FHIR eliminado numa notificação. Este 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 tem um aspeto 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 os campos adicionais incluídos em cada mensagem do Pub/Sub, consulte ReceivedMessage e PubsubMessage.

A tabela seguinte descreve cada campo no objeto attributes:

Atributo Descrição Exemplo
action A ação que ocorreu num 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 suportado na Cloud Healthcare API. Patient
payloadType O tipo de payload da mensagem, um de NameOnly ou FullResource. FullResource
storeName O nome completo do recurso da loja FHIR onde ocorreu a ação. projects/my-project/locations/us/datasets/my-dataset/fhirStores/my-fhir-store
lastUpdatedTime Uma 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 no qual a ação ocorreu. Para mais informações sobre os IDs das versões, consulte o artigo Listar versões de recursos FHIR. MTY4MzA2MDQzOTI5NjIxMDAwMA

A tabela seguinte descreve os campos restantes no objeto message:

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

Especifique as informações a incluir nas notificações

As notificações do Pub/Sub, conforme detalhado no artigo Formato e conteúdo das notificações, incluem um conjunto padrão de campos. Pode incluir o recurso FHIR completo ou apenas o respetivo nome 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 de recursos FHIR são armazenadas no campo data como uma string codificada em base 64.

Ao incluir o conteúdo completo de um recurso FHIR, não precisa de consultar separadamente o Pub/Sub e a Cloud Healthcare API para obter detalhes dos recursos.

Obtenha o nome do recurso FHIR

Para incluir apenas o nome de um recurso FHIR quando criar, atualizar ou aplicar um patch ao recurso, defina sendFullResource como false. Para incluir apenas o nome quando elimina um recurso FHIR, defina sendPreviousResourceOnDelete como false.

Quando vê a notificação, o objeto message tem um aspeto semelhante ao 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"
  }
}

Tenha em atenção o seguinte na notificação:

  • O campo payloadType está definido como NameOnly para indicar o seguinte acerca do pedido:

    • Para operações de criação, atualização e aplicação de patches, sendFullResource está definido como false.
    • Para operações de eliminação, sendPreviousResourceOnDelete está definido como false.

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

Obtenha conteúdos de recursos FHIR criados, atualizados ou corrigidos

Para incluir o conteúdo completo de um recurso FHIR quando cria, atualiza ou aplica uma correção ao recurso, defina sendFullResource como true.

Este comportamento não se aplica se eliminar um recurso FHIR. Se eliminar um recurso FHIR e sendFullResource estiver definido como true, mas sendPreviousResourceOnDelete estiver definido como false, a notificação é igual à que recebe quando apenas obtém o nome do recurso FHIR. Para incluir o conteúdo do recurso FHIR quando um recurso FHIR é eliminado, consulte o artigo Obtenha o conteúdo do recurso FHIR eliminado.

Quando vê a notificação, o objeto message tem um aspeto semelhante ao 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"
  }
}

Tenha em atenção o seguinte na notificação:

  • payloadType está definido como FullResource para indicar que sendFullResource está definido como true. O conteúdo completo do recurso FHIR está 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 base 64.

Obtenha conteúdos de recursos FHIR eliminados

Para incluir o conteúdo completo de um recurso FHIR quando o elimina, defina sendPreviousResourceOnDelete como true.

Quando vê a notificação, o objeto message tem um aspeto semelhante ao 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"
  }
}

Tome nota dos valores nos seguintes campos:

  • A definição de payloadType é FullResource, mesmo que sendFullResource esteja definido como false.

    O conteúdo completo do recurso FHIR está 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 base 64 antes de o recurso ser eliminado.

Configure e veja notificações FHIR

Os exemplos seguintes mostram como ver a notificação do Pub/Sub gerada quando um recurso FHIR é criado num arquivo FHIR.

Antes de começar

Antes de configurar e usar as notificações do Pub/Sub, conclua as seguintes secções:

Reveja as quotas do Pub/Sub

Familiarize-se com as quotas e os limites do Pub/Sub. Para ver informações sobre como ver quotas, pedir valores de quota mais elevados e o que acontece se ficar sem quota, consulte a documentação sobre quotas do Google Cloud.

Ative a API Pub/Sub

Na Google Cloud consola, ative a API Pub/Sub:

Ative a API

Configure autorizações do Pub/Sub

Para permitir a publicação de mensagens da Cloud Healthcare API no Pub/Sub, tem de adicionar a função pubsub.publisher à conta de serviço do agente do serviço Cloud Healthcare do seu projeto. Consulte as autorizações do Pub/Sub da loja DICOM, FHIR e HL7v2 para ver os passos para adicionar a função necessária.

Crie um tópico do Pub/Sub

Para criar um tópico, consulte o artigo Crie um tópico.

Os arquivos de dados individuais podem ter o seu próprio tópico do Pub/Sub, ou vários arquivos de dados podem partilhar o mesmo tópico.

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

projects/PROJECT_ID/topics/TOPIC_NAME

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

Crie uma subscrição do Pub/Sub

Para receber mensagens publicadas num tópico, tem de criar uma subscrição do Pub/Sub. Cada tópico do Pub/Sub precisa de, pelo menos, uma subscrição do Pub/Sub. A subscrição associa o tópico a uma aplicação subscritora que recebe e processa mensagens publicadas no tópico.

Para criar uma subscrição e anexá-la a um tópico do Pub/Sub, consulte o artigo Criar subscrições.

Crie ou edite uma loja FHIR

Crie ou edite uma loja FHIR com um objeto FhirNotificationConfig configurado.

Os exemplos seguintes mostram como editar uma loja FHIR existente. Os campos sendFullResource e sendPreviousResourceOnDelete estã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 eliminado.

REST

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

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • LOCATION: a localização do conjunto de dados
  • DATASET_ID: o conjunto de dados principal do FHIR store
  • FHIR_STORE_ID: o ID da loja FHIR
  • PUBSUB_TOPIC_ID: o ID do tópico do Pub/Sub

Corpo JSON do pedido: 

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Deve receber uma resposta JSON semelhante à seguinte:

Crie um recurso FHIR

Crie um recurso FHIR na loja FHIR. O pedido faz com que a Cloud Healthcare API publique uma mensagem no tópico do Pub/Sub configurado.

Veja a notificação do Pub/Sub

Veja a mensagem publicada no tópico Pub/Sub. A seguinte mensagem foi gerada quando um recurso de paciente foi criado numa loja FHIR.

Na saída de exemplo, o conteúdo do recurso FHIR está numa string codificada em base64 no campo data. Tem de descodificar o valor codificado em base64 para obter o conteúdo. A maioria das plataformas e sistemas operativos tem ferramentas para descodificar texto base64.

REST

Para ver a mensagem publicada no tópico do Pub/Sub, use o método projects.subscriptions.pull. O exemplo seguinte usa o parâmetro de consulta ?maxMessages=10 para especificar o número máximo de mensagens a devolver no pedido. Pode ajustar o valor de acordo com as suas necessidades.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • PUBSUB_SUBSCRIPTION_ID: o ID da subscrição anexada ao tópico do Pub/Sub configurado no FHIR store

Para enviar o seu pedido, 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

Deve receber uma resposta JSON semelhante à seguinte:

gcloud

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

O exemplo usa as seguintes flags da Google Cloud CLI:

  • --format=json: renderiza a saída como JSON.
  • --auto-ack: reconheça automaticamente todas as mensagens extraídas.

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • PUBSUB_SUBSCRIPTION_ID: o ID da subscrição anexada ao tópico do Pub/Sub configurado no FHIR store

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

Deve receber uma resposta semelhante à seguinte:

[
  {
    "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 é demasiado grande ou o tráfego é elevado

Se a dimensão de um recurso FHIR for demasiado grande ou os servidores da Cloud Healthcare API estiverem a registar um volume elevado de tráfego, o campo attributes pode conter apenas o nome do recurso em vez do conteúdo completo do recurso. Este 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, verifique o campo payloadType na resposta ao ver a notificação. Se payloadType estiver definido como nameOnly, significa que o campo attributes não preencheu totalmente os dados dos recursos FHIR. Em seguida, tem de obter manualmente o conteúdo do recurso FHIR na loja FHIR, em vez de o obter na mensagem do Pub/Sub.

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

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

Tem de 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 permanecem na mesma região. Por exemplo, se o conjunto de dados da Cloud Healthcare API e o FHIR store estiverem em us-central1, a política de armazenamento de mensagens só pode permitir a região us-central1.

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

Resolva problemas de mensagens do Pub/Sub em falta

Se não for possível publicar uma notificação no Pub/Sub, é registado um erro no Cloud Logging. Para mais informações, consulte o artigo Ver registos de erros nos Registos na nuvem.

Se a taxa de geração de erros exceder um limite, os erros que excedam o limite não são enviados para o Cloud Logging.

Veja notificações FHIR através da configuração NotificationConfig (descontinuada)

O recurso FhirStore contém um objeto NotificationConfig onde pode especificar um tópico do Pub/Sub. As alterações aos recursos FHIR contêm sempre o seguinte identificador no campo data da mensagem Pub/Sub:

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

O seguinte conjunto de pares 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 O tipo de evento que acabou de ocorrer.
resourceType Qualquer tipo de recurso FHIR. Patient O tipo de recurso que foi modificado.

O que se segue?