Notificações FHIR do Pub/Sub

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

É possível usar as notificações do Pub/Sub para vários casos de uso, incluindo acionar o processamento downstream ou a análise de novos dados. Por exemplo, modelo de machine learning pode receber notificações quando novos dados estiverem disponíveis para treinamento 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 criados, atualizados, corrigidos ou excluídos em um repositório FHIR. A API Cloud Healthcare não enviar notificações quando um recurso FHIR for importado do Cloud Storage.

Para receber notificações, você precisa criar um tópico do Pub/Sub e assinatura e configure o repositório 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 repositório FHIR usando o 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 repositório 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 e cria um objeto 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 FhirNotificationConfig em um repositório FHIR. Cada repositório FHIR pode ter um FhirNotificationConfig configurada.

A tabela a seguir descreve os campos no FhirNotificationConfig objeto.

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 message. um objeto que contém informações sobre o evento clínico. O objeto message parece semelhante a:

{
  "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 nos Formato e conteúdo de notificação: inclua um conjunto padrão de campos. É possível incluir o recurso FHIR completo ou apenas pelo 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 de recursos FHIR são armazenadas no data campo como uma string codificada de base 64.

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

Receber o nome do recurso FHIR

Incluir apenas o nome de um recurso FHIR ao criar, atualizar ou aplique o patch no recurso, defina sendFullResource como false. Para incluir o nome apenas quando você excluir um recurso FHIR, defina sendPreviousResourceOnDelete para 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 é codificada 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 aplique o patch no 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 está 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 recurso FHIR quando um recurso FHIR é 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 é Defina como true. O conteúdo completo do recurso FHIR está incluído no campo data como uma string de base 64 codificada.
  • 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 quando ele for excluído, 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 seja Defina como false.

    O conteúdo completo do recurso FHIR está incluído no campo data como uma string de base 64 codificada.

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

Configurar e visualizar notificações FHIR

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

Antes de começar

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

Revisar a cota do Pub/Sub

Conheça as cotas e limites do Pub/Sub. Para informações sobre como visualizar sua cota, solicitar mais cota e o que acontece Se ela atingir a 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. 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. Todas O tópico do Pub/Sub precisa de pelo menos um Pub/Sub assinatura. 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 Crie assinaturas.

Criar ou editar um repositório FHIR

Criar ou editar um repositório FHIR com um objeto FhirNotificationConfig configurado.

Os exemplos a seguir mostram como editar um armazenamento FHIR atual. Os campos sendFullResource e sendPreviousResourceOnDelete estã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 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 um para o tópico configurado do Pub/Sub.

Veja a notificação do Pub/Sub

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

Na saída de amostra, o conteúdo do recurso FHIR está em um formato codificado em base64 string no campo data. Você deve decodificar o valor codificado em base64 para obter 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 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 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 gcloud pubsub subscriptions pull kubectl.

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 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 a API Cloud Healthcare servidores estão com tráfego intenso, o campo attributes poderá ter apenas o nome do recurso, e não todo o conteúdo dele. Esse comportamento vai ocorrer mesmo se sendFullResource e sendPreviousResourceOnDelete foram definidas como true.

Para verificar se uma notificação do Pub/Sub contém o recurso FHIR completo, confira ao campo payloadType na resposta da visualização da notificação. Se payloadType for definido como nameOnly, o O campo attributes não preencheu totalmente os dados do recurso FHIR. Em seguida, você deve receba o conteúdo do recurso FHIR manualmente do repositório FHIR em vez disso. 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 no Pub/Sub mensagens residam na mesma região, é preciso configurar uma política de armazenamento de mensagens.

Defina explicitamente a política de armazenamento de mensagens no Pub/Sub configurado no repositório de dados para garantir que os dados permaneçam no mesmo na mesma região. Por exemplo, se o conjunto de dados da API Cloud Healthcare e o armazenamento FHIR estiverem no us-central1, a política de armazenamento de mensagens precisa 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 que ultrapassarem o limite não sã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 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