Configurar notificações DICOM do Pub/Sub

Nesta página, descrevemos como usar o Pub/Sub para receber notificações sobre eventos clínicos em um armazenamento DICOM. É possível receber notificações do Pub/Sub quando uma nova instância DICOM é armazenada em um armazenamento DICOM ou importado do Cloud Storage.

É possível usar as notificações do Pub/Sub 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.

Notificações DICOM do Pub/Sub.

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 o armazenamento de 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 visualizar 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.

REST

Use o método projects.locations.datasets.dicomStores.patch.

A NotificationConfig.sendForBulkImport o valor é true. Portanto, as notificações são enviadas na importação de dados do Cloud Storage.

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 DICOM
  • DICOM_STORE_ID: o ID do repositório DICOM
  • PUBSUB_TOPIC: um tópico do Pub/Sub em que as mensagens são publicadas quando um evento ocorre em um repositório de dados.

Corpo JSON da solicitação:

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

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: 

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

APIs Explorer

Copie o corpo da solicitação e 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. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Você vai receber uma resposta semelhante a esta.

Se você configurou campos no recurso DicomStore, eles também vão aparecer na resposta.

gcloud

Execute o comando gcloud healthcare dicom-stores update .

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

  • 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 DICOM
  • DICOM_STORE_ID: o ID do repositório DICOM
  • PUBSUB_TOPIC: um tópico do Pub/Sub em que as mensagens são publicadas quando um evento ocorre em um repositório de dados.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

Você receberá uma resposta semelhante a esta:

Resposta

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 visualizar 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. Store ou importar 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ários instâncias DICOM em uma única solicitação, uma mensagem é 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:

    gcloud

    Execute o comando gcloud pubsub subscriptions pull.

    O exemplo usa as seguintes sinalizações da Google Cloud CLI:

    • --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"
    }
  }
]

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.

A seguir