Configure notificações DICOM Pub/Sub

Esta página descreve como usar o Pub/Sub para receber notificações sobre eventos clínicos num arquivo DICOM. Pode receber notificações do Pub/Sub quando uma nova instância DICOM é armazenada, importada do Cloud Storage, atualizada ou eliminada num arquivo DICOM.

Pode usar as notificações do Pub/Sub para vários fins, como acionar o tratamento a jusante ou analisar novos dados. Por exemplo, um modelo de aprendizagem automática pode receber notificações quando novos dados estão disponíveis para preparação e gerar estatísticas para melhorar os cuidados aos pacientes.

A figura seguinte mostra como as notificações do Pub/Sub são geradas e publicadas.

Notificações DICOM Pub/Sub.

Figura 1. Receber notificações do Pub/Sub sobre eventos clínicos num arquivo DICOM.

A Figura 1 mostra os seguintes passos:

  1. Um autor da chamada faz um pedido para armazenar ou importar uma instância DICOM.
  2. O arquivo DICOM recebe o pedido, cria uma mensagem do Pub/Sub e envia-a para o tópico do Pub/Sub configurado no arquivo DICOM.
  3. O Pub/Sub encaminha a mensagem para as subscrições anexadas ao tópico.
  4. Os subscritores recebem a mensagem da subscrição. Cada subscrição pode ter um ou mais subscritores para aumentar o paralelismo.

Antes de começar

  1. Crie um tópico.
  2. Crie uma subscrição de obtenção.

Adicione autorizações de publicador do Pub/Sub

Para publicar 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. Para mais informações, consulte o artigo Autorizações do Pub/Sub para DICOM, FHIR e HL7v2 store.

Configuração de notificações

Pode configurar as notificações do Pub/Sub e o respetivo comportamento num DicomNotificationConfig objeto numa loja DICOM. Cada arquivo DICOM pode ter vários DicomNotificationConfig objetos configurados.

A tabela seguinte descreve os campos no objeto DicomNotificationConfig:

Campo Descrição Exemplo
pubsubTopic O tópico Pub/Sub a anexar ao arquivo DICOM. As notificações são enviadas para o tópico especificado. projects/my-project/topics/my-topic

Formato e conteúdo da notificação

Uma notificação do Pub/Sub contém um objeto Message que inclui informações sobre o evento clínico. O objeto Message é semelhante ao seguinte:

{
  "message": {
    "attributes": {
      "action": "ACTION",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
      "studyInstanceUID": "STUDY_UID",
      "seriesInstanceUID": "SERIES_UID",
      "sopInstanceUID": "INSTANCE_UID",
      "versionId": "VERSION_ID",
      "modality": "MODALITY",
      "storageClass": "STORAGE_CLASS",
      "previousStorageClass": "PREVIOUS_STORAGE_CLASS"
    },
    "data": "BASE_64_ENCODED_DATA",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

Para mais informações sobre os campos 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 DICOM. Os valores possíveis incluem:
  • StoreInstances
  • ImportDicomData
  • SetBlobSettings
  • DeleteInstances
 StoreInstances
lastUpdatedTime Uma data/hora da hora mais recente em que o recurso DICOM foi modificado. O carimbo de data/hora usa o formato RFC 1123. Mon, 01 Jan 2020 00:00:00 UTC
storeName O nome completo do recurso da loja DICOM onde ocorreu a ação. projects/my-project/locations/us/datasets/my-dataset/dicomStores/my-dicom-store
studyInstanceUID O identificador exclusivo universal (UID) da instância do estudo DICOM. 1.2.3.4.5.6
seriesInstanceUID O identificador exclusivo (UID) da instância da série DICOM. 1.2.3.4.5.6
sopInstanceUID O identificador exclusivo (UID) da instância SOP DICOM. 1.2.3.4.5.6
versionId O ID da versão mais recente do recurso DICOM no qual a ação ocorreu. MTY4MzA2MDQzOTI5NjIxMDAwMA
modality A etiqueta de modalidade do recurso DICOM. Os valores possíveis incluem, entre outros:
  • CT
  • MR
  • MG
 CT
storageClass A classe de armazenamento do recurso DICOM. Os valores possíveis incluem:
  • STANDARD
  • NEARLINE
  • COLDLINE
  • ARCHIVE
 STANDARD
previousStorageClass A classe de armazenamento anterior do recurso DICOM. Os valores possíveis incluem:
  • STANDARD
  • NEARLINE
  • COLDLINE
  • ARCHIVE
 NEARLINE

A tabela seguinte descreve os campos restantes no objeto message:

Campo Descrição
data Uma string codificada em base64 do seguinte identificador: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID
messageId Um identificador da mensagem do Pub/Sub.
publishTime A hora em que o servidor Pub/Sub publicou a mensagem.

Configure e veja notificações

Esta secção descreve como ativar as notificações do Pub/Sub numa loja DICOM, armazenar ou importar uma instância DICOM para publicar uma notificação e ver a notificação.

Configure o arquivo DICOM

Os exemplos seguintes mostram como ativar as notificações do Pub/Sub numa loja DICOM quando uma nova instância DICOM é armazenada ou importada do Cloud Storage.

REST

Use o método projects.locations.datasets.dicomStores.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 arquivo DICOM
  • DICOM_STORE_ID: o ID da loja DICOM
  • PUBSUB_TOPIC: um tópico do Pub/Sub para o qual as mensagens são publicadas quando ocorre um evento num repositório de dados

Corpo JSON do pedido: 

{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    }
  ]
}

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",
    }
  ]
}
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/dicomStores/DICOM_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",
    }
  ]
}
'@  | 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/dicomStores/DICOM_STORE_ID?updateMask=notificationConfigs" | Select-Object -Expand Content

Explorador de APIs

Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Deve receber uma resposta semelhante à seguinte.

Se configurou campos no recurso DicomStore, estes também aparecem na resposta.

gcloud

Execute o comando gcloud healthcare dicom-stores update.

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
  • LOCATION: a localização do conjunto de dados
  • DATASET_ID: o conjunto de dados principal do arquivo DICOM
  • DICOM_STORE_ID: o ID da loja DICOM
  • PUBSUB_TOPIC: um tópico do Pub/Sub para o qual as mensagens são publicadas quando ocorre um evento num 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

Deve receber uma resposta semelhante à seguinte:

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

Armazene ou importe uma instância DICOM e veja a notificação Pub/Sub

Para armazenar ou importar uma instância DICOM e extrair a mensagem Pub/Sub gerada, conclua os seguintes passos:

  1. Armazene ou importe uma instância DICOM. O pedido faz com que a Cloud Healthcare API publique uma mensagem no tópico do Pub/Sub configurado.

  2. Retire a mensagem. Se importar várias instâncias DICOM num único pedido, é gerada uma mensagem para cada instância DICOM.

    Para ver as autorizações de gestão de identidades e acessos necessárias para obter mensagens do Pub/Sub, consulte o artigo Controlo de acesso para o Pub/Sub.

    REST

    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. Ajuste este valor ao seu exemplo de utilização.

    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 Pub/Sub configurado no arquivo DICOM

    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

    Explorador de APIs

    Abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Preencha todos os campos obrigatórios e clique em Executar.

    Deve receber uma resposta JSON semelhante à seguinte:

    gcloud

    Execute o comando gcloud pubsub subscriptions pull.

    O exemplo usa as seguintes flags da Google Cloud CLI:

    • --limit=10: devolve um máximo de 10 mensagens. Ajuste este valor ao seu exemplo de utilização.
    • --format=json: renderiza a saída como JSON.
    • --auto-ack: reconhece 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 Pub/Sub configurado no arquivo 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

    Deve receber uma resposta semelhante à seguinte:

    [
  {
    "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
    "ackStatus": "SUCCESS",
    "message": {
      "attributes": {
        "action": "ImportDicomData",
        "lastUpdatedTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
        "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
        "studyInstanceUID": "1.3.6.1.4.1.1129.5.111396399361969898205364400549799252857604",
        "seriesInstanceUID": "1.3.6.1.4.1.1129.5.111396399361969898205364400549799252857605",
        "sopInstanceUID": "1.3.6.1.4.1.1129.5.111396399361969898205364400549799252857606",
        "versionId": "MTY4MzA2MDQzOTI5NjIxMDAwMA",
        "modality": "CT",
        "storageClass": "STANDARD",
      },
      "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==",
      "messageId": "7586159156345265",
      "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
    }
  }
]

Migre de notificationConfig para notificationConfigs

Para os utilizadores existentes do arquivo DICOM, se estiver a usar o campo notificationConfig para configurar o tópico do Pub/Sub, deve migrar para o campo notificationConfigs. Seguem-se as principais diferenças:

  1. O dicomStore.notificationConfig só suporta um subscritor, enquanto o dicomStore.notificationConfigs suporta vários subscritores.

  2. O dicomStore.notificationConfig usa NotificationConfig, que está a ser descontinuado e substituído por DicomNotificationConfig.

  3. dicomStore.notificationConfigs suporta o envio automático de notificações para todas as operações DICOM disponíveis, como ImportDicomData, DeleteInstances e outras. Consequentemente, o atributo NotificationConfig.sendForBulkImport já não é suportado.

  4. Se quiser escolher as mensagens que recebe ou filtrar mensagens indesejadas para um subscritor específico, pode usar a funcionalidade Filtrar mensagens de uma subscrição. Por exemplo, pode usar attributes.action != "ImportDicomData" para filtrar todas as mensagens enviadas a partir da operação ImportDicomData.

    REST

    Use o método dicomStores.patch e parta do princípio de que já tem um tópico definido na sua loja através de notificationConfig.

    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 arquivo DICOM
    • DICOM_STORE_ID: o ID da loja DICOM

    Corpo JSON do pedido: 

    {
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_SAMPLE_1",
    },
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_SAMPLE_2",
    }
  ]
}

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

    Explorador de APIs

    Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

    Deve receber uma resposta semelhante à seguinte.

    Se configurou campos no recurso DicomStore, estes também aparecem na resposta.

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.

O que se segue?