Mengonfigurasi notifikasi Pub/Sub DICOM

Halaman ini menjelaskan cara menggunakan Pub/Sub untuk mendapatkan notifikasi tentang peristiwa klinis di toko DICOM. Anda dapat menerima notifikasi Pub/Sub saat instance DICOM baru disimpan di penyimpanan DICOM atau diimpor dari Cloud Storage.

Anda dapat menggunakan notifikasi Pub/Sub untuk berbagai tujuan, seperti memicu pemrosesan downstream atau menganalisis data baru. Misalnya, model machine learning dapat menerima notifikasi saat data baru tersedia untuk pelatihan dan menghasilkan insight guna meningkatkan kualitas perawatan pasien.

Gambar berikut menunjukkan cara notifikasi Pub/Sub dihasilkan dan dipublikasikan.

Gambar 1. Menerima notifikasi Pub/Sub tentang peristiwa klinis di toko DICOM.

Gambar 1 menunjukkan langkah-langkah berikut:

1. Pemanggil membuat permintaan untuk menyimpan atau mengimpor instance DICOM.
2. Penyimpanan DICOM menerima permintaan, membuat pesan Pub/Sub, dan mengirimkannya ke topik Pub/Sub yang dikonfigurasi di penyimpanan DICOM.
3. Pub/Sub meneruskan pesan ke langganan yang dilampirkan ke topik.
4. Pelanggan akan menerima pesan dari langganannya. Setiap langganan dapat memiliki satu atau beberapa pelanggan agar paralelisme dapat meningkat.

Sebelum memulai

1. Buat topik.
2. Membuat langganan pull.

Menambahkan izin penayang Pub/Sub

Untuk memublikasikan pesan dari Cloud Healthcare API ke Pub/Sub, Anda harus menambahkan peran pubsub.publisher ke akun layanan Cloud Healthcare Service Agent project Anda. Untuk mengetahui informasi selengkapnya, lihat izin Pub/Sub toko DICOM, FHIR, dan HL7v2.

Format dan konten notifikasi

Notifikasi Pub/Sub berisi objek Message yang menyertakan informasi tentang peristiwa klinis. Notifikasi Pub/Sub DICOM tidak menyertakan kolom attributes. Objek Message terlihat mirip dengan contoh berikut:

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

Nilai di kolom data adalah ID berikut sebagai string berenkode base 64: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID

Untuk mengetahui informasi selengkapnya tentang kolom yang disertakan dalam setiap pesan Pub/Sub, lihat ReceivedMessage dan PubsubMessage.

Mengonfigurasi dan melihat notifikasi

Bagian ini menjelaskan cara mengaktifkan notifikasi Pub/Sub di penyimpanan DICOM, menyimpan, atau mengimpor instance DICOM untuk memublikasikan notifikasi dan melihat notifikasi.

Mengonfigurasi penyimpanan DICOM

Izin yang diperlukan untuk langkah ini

Untuk melakukan tugas ini, Anda harus diberi izin berikut atau peran Identity and Access Management (IAM) berikut:

Izin

• healthcare.dicomStores.update

Peran

• Administrator Toko DICOM Layanan Kesehatan (roles/healthcare.dicomStoreAdmin)

Contoh berikut menunjukkan cara mengaktifkan notifikasi Pub/Sub di penyimpanan DICOM saat instance DICOM baru disimpan atau diimpor dari Cloud Storage.

REST

Gunakan metode projects.locations.datasets.dicomStores.patch.

Nilai NotificationConfig.sendForBulkImport adalah true, sehingga notifikasi dikirim saat mengimpor data dari Cloud Storage.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• PROJECT_ID: ID project Google Cloud Anda
• LOCATION: lokasi set data
• DATASET_ID: set data induk penyimpanan DICOM
• DICOM_STORE_ID: ID penyimpanan DICOM
• PUBSUB_TOPIC: topik Pub/Sub tempat pesan dipublikasikan saat terjadi peristiwa di penyimpanan data

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

cat > request.json << 'EOF'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  }
}
EOF

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda:

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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

@'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Kemudian jalankan perintah berikut untuk mengirim permintaan REST Anda:

$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

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom wajib lainnya, lalu klik Jalankan.

Anda akan menerima respons seperti berikut.

Jika Anda mengonfigurasi kolom apa pun di resource DicomStore, kolom tersebut juga akan muncul dalam respons.

Respons

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

gcloud

Jalankan perintah gcloud healthcare dicom-stores update

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

• PROJECT_ID: ID project Google Cloud Anda
• LOCATION: lokasi set data
• DATASET_ID: set data induk penyimpanan DICOM
• DICOM_STORE_ID: ID penyimpanan DICOM
• PUBSUB_TOPIC: topik Pub/Sub tempat pesan dipublikasikan saat terjadi peristiwa di penyimpanan data

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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)

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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)

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI melalui autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

Anda akan melihat respons seperti berikut:

Respons

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

Menyimpan atau mengimpor instance DICOM dan melihat notifikasi Pub/Sub

Izin yang diperlukan untuk langkah ini

Untuk melakukan tugas ini, Anda harus diberi izin berikut atau peran Identity and Access Management (IAM) berikut:

Izin

• healthcare.dicomStores.dicomWebWrite untuk menyimpan instance DICOM di penyimpanan DICOM yang diminta.
• healthcare.dicomStores.import untuk mengimpor instance DICOM ke penyimpanan DICOM yang diminta.

Peran

• Healthcare DICOM Editor (roles/healthcare.dicomEditor)

Untuk menyimpan atau mengimpor instance DICOM dan menarik pesan Pub/Sub yang dihasilkan, selesaikan langkah-langkah berikut:

1. Menyimpan atau import instance DICOM. Permintaan tersebut menyebabkan Cloud Healthcare API memublikasikan pesan ke topik Pub/Sub yang dikonfigurasi.

2. Tarik pesannya. Jika Anda mengimpor beberapa instance DICOM dalam satu permintaan, pesan akan dibuat untuk setiap instance DICOM.

   Untuk melihat izin Identity and Access Management yang diperlukan untuk menarik pesan Pub/Sub, lihat Kontrol akses untuk Pub/Sub.

   REST

   Gunakan metode projects.subscriptions.pull. Contoh berikut menggunakan parameter kueri ?maxMessages=10 untuk menentukan jumlah maksimum pesan yang akan ditampilkan dalam permintaan. Sesuaikan nilai ini dengan kasus penggunaan Anda.

   Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

   • PROJECT_ID: ID project Google Cloud Anda
   • PUBSUB_SUBSCRIPTION_ID: ID langganan yang dilampirkan ke topik Pub/Sub yang dikonfigurasi di toko DICOM

   Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

   curl

   Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

   Jalankan perintah berikut:

   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

   Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

   Jalankan perintah berikut:

   $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

   Buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Lengkapi kolom yang wajib diisi, lalu klik Jalankan.

   Anda akan melihat respons JSON seperti berikut:

   Respons

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

   gcloud

   Jalankan perintah gcloud pubsub subscriptions pull.

   Contoh ini menggunakan flag Google Cloud CLI berikut:

   • --limit=10: Menampilkan maksimum 10 pesan. Sesuaikan nilai ini dengan kasus penggunaan Anda.
   • --format=json: Merender output sebagai JSON.
   • --auto-ack: Otomatis mengonfirmasi setiap pesan yang ditarik.

   Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

   • PROJECT_ID: ID project Google Cloud Anda
   • PUBSUB_SUBSCRIPTION_ID: ID langganan yang dilampirkan ke topik Pub/Sub yang dikonfigurasi di toko DICOM

   Jalankan perintah berikut:

   Linux, macOS, atau Cloud Shell

   Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

   Windows (PowerShell)

   Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

   Windows (cmd.exe)

   Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI melalui autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

   Anda akan melihat respons seperti berikut:

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

Kebijakan penyimpanan pesan Cloud Healthcare API dan Pub/Sub

Untuk memastikan bahwa data Cloud Healthcare API dan data terkait dalam pesan Pub/Sub berada di region yang sama, Anda harus menetapkan kebijakan penyimpanan pesan Pub/Sub.

Anda harus secara eksplisit menetapkan kebijakan penyimpanan pesan pada topik Pub/Sub yang dikonfigurasi di penyimpanan data untuk memastikan bahwa data tetap berada di region yang sama. Misalnya, jika set data Cloud Healthcare API dan penyimpanan FHIR Anda berada di us-central1, kebijakan penyimpanan pesan hanya boleh mengizinkan region us-central1.

Untuk mengonfigurasi kebijakan penyimpanan pesan, lihat Mengonfigurasi kebijakan penyimpanan pesan.

Memecahkan masalah pesan Pub/Sub yang terlewat

Jika notifikasi tidak dapat dipublikasikan ke Pub/Sub, error akan dicatat ke Cloud Logging. Untuk mengetahui informasi lebih lanjut, baca bagian Melihat log error di Cloud Logging.

Jika tingkat pembuatan error melebihi batas, error yang melebihi batas tidak akan dikirimkan ke Cloud Logging.

Langkah selanjutnya

• Menangani lonjakan sementara dengan kontrol alur
• Menangani kegagalan pesan
• Memutar ulang dan menghapus pesan
• Ringkasan arsitektur Pub/Sub