This page describes how to use Pub/Sub to get notifications about clinical events in a DICOM store. You can receive Pub/Sub notifications when a new DICOM instance is stored in a DICOM store or imported from Cloud Storage.
You can use Pub/Sub notifications for multiple purposes, such as triggering downstream processing or analyzing new data. For example, a machine learning model can receive notifications when new data is available for training and generate insights to improve patient care.
The following figure shows how Pub/Sub notifications are generated and published.
Figure 1. Receiving Pub/Sub notifications about clinical events in a DICOM store.
Figure 1 shows the following steps:
- A caller makes a request to store or import a DICOM instance.
- The DICOM store receives the request, creates a Pub/Sub message, and sends it to the Pub/Sub topic configured on the DICOM store.
- Pub/Sub forwards the message to the subscriptions attached to the topic.
- The subscribers receive the message from their subscription. Each subscription can have one or more subscribers for increased parallelism.
Before you begin
Add Pub/Sub publisher permissions
To publish messages from the Cloud Healthcare API to Pub/Sub, you
must add the pubsub.publisher
role to
your project's Cloud Healthcare Service Agent service account.
For more information, see DICOM, FHIR, and HL7v2 store Pub/Sub permissions.
Notification format and content
A Pub/Sub notification contains a Message
object that includes
information about the clinical event. DICOM Pub/Sub notifications don't
include an attributes
field. The Message
object looks
similar to the following:
{ "message": { "data": "BASE_64_ENCODED_DATA ", "messageId": "MESSAGE_ID ", "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ " } }
The value in the data
field is the following identifier as a base 64-encoded string: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID
For more information about the fields included in each Pub/Sub message,
see ReceivedMessage
and PubsubMessage
.
Configure and view notifications
This section describes how to enable Pub/Sub notifications on a DICOM store, store or import a DICOM instance to publish a notification, and view the notification.
Configure the DICOM store
Permissions required for this task
To perform this task, you must have been granted the following permissions or the following Identity and Access Management (IAM) roles:
Permissions
healthcare.dicomStores.update
Roles
You can ask your administrator to grant you these Identity and Access Management roles. For instructions on granting roles, see Manage access or Control access to Cloud Healthcare API resources. You might also be able to get the required permissions through custom roles or other predefined roles.
The following samples show how to enable Pub/Sub notifications on a DICOM store when a new DICOM instance is stored or imported from Cloud Storage.
Use the projects.locations.datasets.dicomStores.patch
method.
The
NotificationConfig.sendForBulkImport
value is true
, so notifications are sent when importing data from Cloud Storage.
Before using any of the request data, make the following replacements:
: the ID of your Google Cloud projectPROJECT_ID
: the dataset locationLOCATION
: the DICOM store's parent datasetDATASET_ID
: the DICOM store IDDICOM_STORE_ID
: a Pub/Sub topic to which messages are published when an event occurs in a data storePUBSUB_TOPIC
Request JSON body:
{ "notificationConfig": { "pubsubTopic": "projects/PROJECT_ID /topics/PUBSUB_TOPIC ", "sendForBulkImport": "true" } }
To send your request, choose one of these options:
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
cat > request.json << 'EOF' { "notificationConfig": { "pubsubTopic": "projects/PROJECT_ID /topics/PUBSUB_TOPIC ", "sendForBulkImport": "true" } } EOF
Then execute the following command to send your REST request:
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"
Save the request body in a file named request.json
.
Run the following command in the terminal to create or overwrite
this file in the current directory:
@' { "notificationConfig": { "pubsubTopic": "projects/PROJECT_ID /topics/PUBSUB_TOPIC ", "sendForBulkImport": "true" } } '@ | Out-File -FilePath request.json -Encoding utf8
Then execute the following command to send your REST request:
$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
Copy the request body and open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.
You should receive a response similar to the following.
If you configured any fields in the DicomStore
resource, they also appear in the response.
Response
{ "name": "projects/PROJECT_ID /locations/LOCATION /datasets/DATASET_ID /dicomStores/DICOM_STORE_ID ", "notificationConfig": { "pubsubTopic": "projects/PROJECT_ID /topics/PUBSUB_TOPIC ", "sendForBulkImport": "true" }, }
Run the gcloud healthcare dicom-stores update
command.
Before using any of the command data below, make the following replacements:
: the ID of your Google Cloud projectPROJECT_ID
: the dataset locationLOCATION
: the DICOM store's parent datasetDATASET_ID
: the DICOM store IDDICOM_STORE_ID
: a Pub/Sub topic to which messages are published when an event occurs in a data storePUBSUB_TOPIC
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud healthcare dicom-stores updateDICOM_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 updateDICOM_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 updateDICOM_STORE_ID ^ --dataset=DATASET_ID ^ --location=LOCATION ^ --pubsub-topic=projects/PROJECT_ID /topics/PUBSUB_TOPIC ^ --send-for-bulk-import
You should receive a response similar to the following:
Response
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
Store or import a DICOM instance and view the Pub/Sub notification
Permissions required for this task
To perform this task, you must have been granted the following permissions or the following Identity and Access Management (IAM) roles:
Permissions
healthcare.dicomStores.dicomWebWrite
to store DICOM instances in the requested DICOM store.healthcare.dicomStores.import
to import DICOM instances into the requested DICOM store.
Roles
You can ask your administrator to grant you these Identity and Access Management roles. For instructions on granting roles, see Manage access or Control access to Cloud Healthcare API resources. You might also be able to get the required permissions through custom roles or other predefined roles.
To store or import a DICOM instance and pull the generated Pub/Sub message, complete the following steps:
Store or import a DICOM instance. The request causes the Cloud Healthcare API to publish a message to the configured Pub/Sub topic.
Pull the message. If you import multiple DICOM instances in a single request, a message is generated for each DICOM instance.
To view the Identity and Access Management permissions needed to pull Pub/Sub messages, see Access control for Pub/Sub.
Use the
projects.subscriptions.pull
method. The following sample uses the?maxMessages=10
query parameter to specify the maximum number of messages to return in the request. Adjust this value to your use case.Before using any of the request data, make the following replacements:
: the ID of your Google Cloud projectPROJECT_ID
: the ID of the subscription attached to the Pub/Sub topic configured on the DICOM storePUBSUB_SUBSCRIPTION_ID
To send your request, choose one of these options:
Execute the following command:
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"Execute the following command:
$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 ContentOpen the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.
You should receive a JSON response similar to the following:
Response
{ "receivedMessages": [ { "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR", "ackStatus": "SUCCESS", "message": { "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==", "messageId": "7586159156345265", "publishTime": "
YYYY-MM-DDTHH:MM:SS+ZZ:ZZ " } } ] }Run the
gcloud pubsub subscriptions pull
command.The sample uses the following Google Cloud CLI flags:
--limit=10
: Returns a maximum of 10 messages. Adjust this value to your use case.--format=json
: Renders the output as JSON.--auto-ack
: Automatically acknowledges every message pulled.
Before using any of the command data below, make the following replacements:
: the ID of your Google Cloud projectPROJECT_ID
: the ID of the subscription attached to the Pub/Sub topic configured on the DICOM storePUBSUB_SUBSCRIPTION_ID
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud pubsub subscriptions pull \ projects/
PROJECT_ID /subscriptions/PUBSUB_SUBSCRIPTION_ID \ --limit=10 \ --auto-ack \ --format=jsonWindows (PowerShell)
gcloud pubsub subscriptions pull ` projects/
PROJECT_ID /subscriptions/PUBSUB_SUBSCRIPTION_ID ` --limit=10 ` --auto-ack ` --format=jsonWindows (cmd.exe)
gcloud pubsub subscriptions pull ^ projects/
PROJECT_ID /subscriptions/PUBSUB_SUBSCRIPTION_ID ^ --limit=10 ^ --auto-ack ^ --format=jsonYou should receive a response similar to the following:
[ { "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR", "ackStatus": "SUCCESS", "message": { "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==", "messageId": "7586159156345265", "publishTime": "
YYYY-MM-DDTHH:MM:SS+ZZ:ZZ " } } ]
Cloud Healthcare API and Pub/Sub message storage policy
To ensure that your Cloud Healthcare API data and the associated data in Pub/Sub messages reside in the same region, you must set a Pub/Sub message storage policy.
You must explicitly set the message storage policy on the Pub/Sub
topic configured on the data store to ensure that the data stays in the same
region. For example, if your Cloud Healthcare API dataset and FHIR store are in
us-central1
, the message storage policy must only allow the us-central1
region.
To configure a message storage policy, see Configuring message store policies.
Troubleshoot missed Pub/Sub messages
If a notification can't be published to Pub/Sub, an error is logged to Cloud Logging. For more information, see Viewing error logs in Cloud Logging.
If the rate of error generation exceeds a limit, errors in excess of the limit aren't submitted to Cloud Logging.
What's next
- Handle transient spikes with flow control
- Handle message failures
- Replay and purge messages
- Architectural overview of Pub/Sub