Configurare le notifiche Pub/Sub DICOM

Questa pagina descrive come utilizzare Pub/Sub per ricevere notifiche sugli eventi clinici in un archivio DICOM. Puoi ricevere notifiche Pub/Sub quando una nuova istanza DICOM viene memorizzata in un archivio DICOM o importata da Cloud Storage.

Puoi utilizzare le notifiche Pub/Sub per diversi scopi, ad esempio attivare l'elaborazione downstream o analizzare nuovi dati. Ad esempio, un modello di machine learning può ricevere notifiche quando sono disponibili nuovi dati per l'addestramento e generare approfondimenti per migliorare la cura dei pazienti.

La figura seguente mostra come vengono generate e pubblicate le notifiche Pub/Sub.

Figura 1. Ricezione di notifiche Pub/Sub relative a eventi clinici in un archivio DICOM.

La figura 1 mostra i seguenti passaggi:

1. Il chiamante effettua una richiesta per archiviare o importare un'istanza DICOM.
2. L'archivio DICOM riceve la richiesta, crea un messaggio Pub/Sub e lo invia all'argomento Pub/Sub configurato nell'archivio DICOM.
3. Pub/Sub inoltra il messaggio alle sottoscrizioni associate all'argomento.
4. I sottoscrittori ricevono il messaggio dalla loro sottoscrizione. Ogni abbonamento può avere uno o più abbonati per un maggiore parallelismo.

Prima di iniziare

1. Crea un argomento.
2. Crea una sottoscrizione pull.

Aggiungi autorizzazioni publisher Pub/Sub

Per pubblicare messaggi dall'API Cloud Healthcare a Pub/Sub, devi aggiungere il ruolo pubsub.publisher all'account di servizio dell'agente di servizio Cloud Healthcare del progetto. Per ulteriori informazioni, consulta Autorizzazioni Pub/Sub per archivi DICOM, FHIR e HL7v2.

Formato e contenuti delle notifiche

Una notifica Pub/Sub contiene un oggetto Message che include informazioni sull'evento clinico. L'oggetto Message è simile al seguente:

{
  "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"
  }
}

Per ulteriori informazioni sui campi inclusi in ogni messaggio Pub/Sub, vedi ReceivedMessage e PubsubMessage.

La tabella seguente descrive ogni campo dell'oggetto attributes:

La tabella seguente descrive i campi rimanenti nell'oggetto message:

Configurare e visualizzare le notifiche

Questa sezione descrive come attivare le notifiche Pub/Sub in un archivio DICOM, archiviare o importare un'istanza DICOM per pubblicare una notifica e visualizzare la notifica.

Configura l'archivio DICOM

Gli esempi riportati di seguito mostrano come attivare le notifiche Pub/Sub in un archivio DICOM quando una nuova istanza DICOM viene archiviata o importata da 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

Archivia o importa un'istanza DICOM e visualizza la notifica Pub/Sub

Per archiviare o importare un'istanza DICOM ed estrarre il messaggio Pub/Sub generato, completa i seguenti passaggi:

1. Archivia o importa un'istanza DICOM. La richiesta fa sì che l'API Cloud Healthcare pubblichi un messaggio nell'argomento Pub/Sub configurato.

2. Ritira il messaggio. Se importi più istanze DICOM in una singola richiesta, viene generato un messaggio per ogni istanza DICOM.

   Per visualizzare le autorizzazioni Identity and Access Management necessarie per estrarre i messaggi Pub/Sub, consulta la sezione Controllo dell'accesso per Pub/Sub.

   REST

   Utilizza il metodo projects.subscriptions.pull. Il seguente esempio utilizza il parametro di query ?maxMessages=10 per specificare il numero massimo di messaggi da restituire nella richiesta. Modifica questo valore in base al tuo caso d'uso.

   Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

   • PROJECT_ID: l'ID del tuo Google Cloud progetto
   • PUBSUB_SUBSCRIPTION_ID: l'ID della sottoscrizione collegata all'argomento Pub/Sub configurato nell'archivio DICOM

   Per inviare la richiesta, scegli una di queste opzioni:

   curl

   Esegui questo 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

   Esegui questo 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

   Explorer API

   Apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Completa i campi obbligatori e fai clic su Esegui.

   Dovresti ricevere una risposta JSON simile alla seguente:

   Risposta

   {
     "receivedMessages": [
       {
         "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"
         }
       }
     ]
   }
   

   gcloud

   Esegui il comando gcloud pubsub subscriptions pull.

   L'esempio utilizza i seguenti flag di Google Cloud CLI:

   • --limit=10: restituisce un massimo di 10 messaggi. Modifica questo valore in base al tuo caso d'uso.
   • --format=json: esegue il rendering dell'output come JSON.
   • --auto-ack: riconosce automaticamente ogni messaggio estratto.

   Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

   • PROJECT_ID: l'ID del tuo Google Cloud progetto
   • PUBSUB_SUBSCRIPTION_ID: l'ID della sottoscrizione collegata all'argomento Pub/Sub configurato nell'archivio DICOM

   Esegui questo comando:

   Linux, macOS o 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

   Dovresti ricevere una risposta simile alla seguente:

   [
     {
       "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"
       }
     }
   ]
   

API Cloud Healthcare e criteri di archiviazione dei messaggi Pub/Sub

Per garantire che i dati dell'API Cloud Healthcare e i dati associati nei messaggi Pub/Sub si trovino nella stessa regione, devi impostare un criterio di archiviazione dei messaggi Pub/Sub.

Devi impostare esplicitamente il criterio di archiviazione dei messaggi nell'argomento Pub/Sub configurato nell'datastore per assicurarti che i dati rimangano nella stessa regione. Ad esempio, se il set di dati e l'archivio FHIR dell'API Cloud Healthcare si trovano in us-central1, il criterio di archiviazione dei messaggi deve consentire solo la regione us-central1.

Per configurare una policy di archiviazione dei messaggi, consulta Configurazione delle policy di archiviazione dei messaggi.

Risolvere i problemi relativi ai messaggi Pub/Sub mancanti

Se una notifica non può essere pubblicata su Pub/Sub, viene registrato un errore in Cloud Logging. Per ulteriori informazioni, consulta Visualizzazione dei log degli errori su Cloud Logging.

Se la frequenza di generazione degli errori supera un limite, gli errori in eccesso rispetto al limite non vengono inviati a Cloud Logging.

Passaggi successivi

• Gestire i picchi transitori con il controllo del flusso
• Gestire gli errori relativi ai messaggi
• Riprodurre ed eliminare i messaggi
• Panoramica dell'architettura di Pub/Sub