Configurar notificações DICOM do Pub/Sub

Esta página descreve como usar o Pub/Sub para receber notificações sobre eventos clínicos em uma loja DICOM. Você pode receber notificações do Pub/Sub quando uma nova instância DICOM é armazenada em um armazenamento DICOM ou importada do Cloud Storage.

As notificações do Pub/Sub podem ser usadas para várias finalidades, como acionar o processamento downstream ou analisar dados novos. Por exemplo, modelo de machine learning pode receber notificações quando novos dados estiverem disponíveis para treinamento insights para melhorar o atendimento aos pacientes.

A figura a seguir mostra como as notificações do Pub/Sub são geradas e publicados.

Figura 1. Receber notificações do Pub/Sub sobre eventos clínicos em um armazenamento DICOM.

A Figura 1 mostra as seguintes etapas:

1. Um autor da chamada faz uma solicitação para armazenar ou importar uma instância DICOM.
2. O repositório DICOM recebe a solicitação e cria um objeto Pub/Sub e a envia ao tópico do Pub/Sub configurado no repositório DICOM.
3. O Pub/Sub encaminha a mensagem para as assinaturas anexadas ao tópico.
4. Os assinantes recebem a mensagem da assinatura. Cada assinatura pode ter um ou mais assinantes para aumentar o paralelismo.

Antes de começar

1. Crie um tópico.
2. Crie uma assinatura de pull.

Adicionar permissões de editor do Pub/Sub

Para publicar mensagens da API Cloud Healthcare no Pub/Sub, você precisa adicionar o papel pubsub.publisher à conta de serviço do Agente de serviço do Cloud Healthcare do seu projeto. Para mais informações, consulte Permissões do Pub/Sub para armazenamento DICOM, FHIR e HL7v2.

Formato e conteúdo das notificações

Uma notificação do Pub/Sub contém um Message. que inclui informações sobre o evento clínico. As notificações DICOM do Pub/Sub não incluir um campo attributes. O objeto Message parece semelhante a:

{
  "message": {
    "data": "BASE_64_ENCODED_DATA",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

O valor no campo data é o seguinte identificador como uma string codificada em base 64: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID

Para mais informações sobre os campos incluídos em cada mensagem do Pub/Sub, consulte ReceivedMessage e PubsubMessage.

Configurar e conferir notificações

Nesta seção, descrevemos como ativar as notificações do Pub/Sub um repositório DICOM, armazena ou importa uma instância DICOM para publicar uma notificação e visualizar a notificação.

Configurar o armazenamento DICOM

Os exemplos a seguir mostram como ativar as notificações do Pub/Sub em um armazenamento DICOM quando uma nova instância DICOM é armazenada ou importada do Cloud Storage.

{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  }
}

cat > request.json << 'EOF'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "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/dicomStores/DICOM_STORE_ID?updateMask=notificationConfig"

@'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "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/dicomStores/DICOM_STORE_ID?updateMask=notificationConfig" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  },
}

gcloud healthcare dicom-stores update DICOM_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION \
  --pubsub-topic=projects/PROJECT_ID/topics/PUBSUB_TOPIC \
  --send-for-bulk-import

gcloud healthcare dicom-stores update DICOM_STORE_ID `
  --dataset=DATASET_ID `
  --location=LOCATION `
  --pubsub-topic=projects/PROJECT_ID/topics/PUBSUB_TOPIC `
  --send-for-bulk-import

gcloud healthcare dicom-stores update DICOM_STORE_ID ^
  --dataset=DATASET_ID ^
  --location=LOCATION ^
  --pubsub-topic=projects/PROJECT_ID/topics/PUBSUB_TOPIC ^
  --send-for-bulk-import

Updated dicomStore [DICOM_STORE_ID].
...
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID
notificationConfig:
  pubsubTopic: projects/PROJECT_ID/topics/PUBSUB_TOPIC
  sendForBulkImport: true

Armazenar ou importar uma instância DICOM e conferir a notificação do Pub/Sub

Para armazenar ou importar uma instância DICOM e extrair a mensagem do Pub/Sub gerada, siga estas etapas:

1. Armazene ou importe uma instância DICOM. A solicitação faz com que a API Cloud Healthcare publique um para o tópico configurado do Pub/Sub.

2. Receba a mensagem. Se você importar várias instâncias DICOM em uma única solicitação, uma mensagem será gerada para cada instância DICOM.

   Visualizar as permissões do Identity and Access Management necessárias para extrair Mensagens do Pub/Sub, consulte Controle de acesso do Pub/Sub.

   REST

   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. Ajuste esse valor de acordo com seu caso de uso.

   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 armazenamento DICOM

   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

   APIs Explorer

   Abra o página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

   Você receberá uma resposta JSON semelhante a esta:

   Resposta

   {
     "receivedMessages": [
       {
         "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
         "ackStatus": "SUCCESS",
         "message": {
           "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==",
           "messageId": "7586159156345265",
           "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
         }
       }
     ]
   }
   

   gcloud

   Execute o comando gcloud pubsub subscriptions pull.

   O exemplo usa as seguintes flags da CLI do Google Cloud:

   • --limit=10: retorna no máximo 10 mensagens. Ajuste esse valor de acordo com seu caso de uso.
   • --format=json: renderiza a saída como JSON.
   • --auto-ack: confirma automaticamente todas as mensagens extraídas.

   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 armazenamento DICOM

   Execute o seguinte comando:

   Linux, macOS ou Cloud Shell

   gcloud pubsub subscriptions pull \
       projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID \
       --limit=10 \
       --auto-ack \
       --format=json

   Windows (PowerShell)

   gcloud pubsub subscriptions pull `
       projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID `
       --limit=10 `
       --auto-ack `
       --format=json

   Windows (cmd.exe)

   gcloud pubsub subscriptions pull ^
       projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ^
       --limit=10 ^
       --auto-ack ^
       --format=json

   Você receberá uma resposta semelhante a esta:

   [
     {
       "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
       "ackStatus": "SUCCESS",
       "message": {
         "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==",
         "messageId": "7586159156345265",
         "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
       }
     }
   ]
   

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

A seguir

• Lidar com picos temporários com controle de fluxo
• Lidar com falhas de mensagens
• Repetir e limpar mensagens
• Visão geral da arquitetura do Pub/Sub