Mengonfigurasi notifikasi Pub/Sub DICOM

Halaman ini menjelaskan cara menggunakan Pub/Sub untuk mendapatkan notifikasi tentang peristiwa klinis di penyimpanan 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 beberapa 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 untuk meningkatkan kualitas perawatan pasien.

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

Gambar 1. Menerima notifikasi Pub/Sub tentang peristiwa klinis di penyimpanan 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 menerima pesan dari langganan mereka. Setiap langganan dapat memiliki satu atau beberapa subscriber untuk meningkatkan paralelisme.

Sebelum memulai

1. Buat topik.
2. Buat 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 Agen Layanan Cloud Healthcare project Anda. Untuk mengetahui informasi selengkapnya, lihat Izin Pub/Sub penyimpanan 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 akan terlihat mirip dengan yang 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 yang dienkode 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 sudah diberi izin berikut atau peran Identity and Access Management (IAM) berikut:

Izin

• healthcare.dicomStores.update

Peran

• Healthcare DICOM Store Administrator (roles/healthcare.dicomStoreAdmin)

Anda dapat meminta administrator untuk memberikan peran Identity and Access Management ini kepada Anda. Untuk mengetahui petunjuk tentang cara memberikan peran, lihat Mengelola akses atau Mengontrol akses ke resource Cloud Healthcare API. Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Catatan: Jika Anda membuat Google Cloud project untuk panduan ini, sebagai pembuat project, Anda akan otomatis diberi peran IAM Pemilik (roles/owner), yang memiliki izin. Anda tidak perlu diberi peran IAM tambahan.

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 Google Cloud project 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 peristiwa terjadi 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 gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login , atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI . Anda dapat memeriksa akun yang saat ini aktif 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 gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login . Anda dapat memeriksa akun yang saat ini aktif 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 API Explorer terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom lainnya yang wajib diisi, lalu klik Jalankan.

Anda akan menerima respons yang mirip dengan yang berikut ini.

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 Google Cloud project 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 peristiwa terjadi 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 sudah 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)

Anda dapat meminta administrator untuk memberikan peran Identity and Access Management ini kepada Anda. Untuk mengetahui petunjuk tentang cara memberikan peran, lihat Mengelola akses atau Mengontrol akses ke resource Cloud Healthcare API. Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Catatan: Jika Anda membuat Google Cloud project untuk panduan ini, sebagai pembuat project, Anda akan otomatis diberi peran IAM Pemilik (roles/owner), yang memiliki izin. Anda tidak perlu diberi peran IAM tambahan.

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

1. Simpan atau impor instance DICOM. Permintaan ini menyebabkan Cloud Healthcare API memublikasikan pesan ke topik Pub/Sub yang dikonfigurasi.

2. Tarik pesan. 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 mengambil 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 Google Cloud project Anda
   • PUBSUB_SUBSCRIPTION_ID: ID langganan yang dilampirkan ke topik Pub/Sub yang dikonfigurasi di penyimpanan DICOM

   Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

   curl

   Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login , atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI . Anda dapat memeriksa akun yang saat ini aktif 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 gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login . Anda dapat memeriksa akun yang saat ini aktif 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 API Explorer 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: Secara otomatis mengonfirmasi setiap pesan yang diambil.

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

   • PROJECT_ID: ID Google Cloud project Anda
   • PUBSUB_SUBSCRIPTION_ID: ID langganan yang dilampirkan ke topik Pub/Sub yang dikonfigurasi di penyimpanan 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 menetapkan kebijakan penyimpanan pesan secara eksplisit di topik Pub/Sub yang dikonfigurasi di penyimpanan data untuk memastikan 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 dalam log ke Cloud Logging. Untuk mengetahui informasi selengkapnya, lihat artikel Melihat log error di Cloud Logging.

Jika frekuensi pembuatan error melebihi batas, error yang melebihi batas tersebut tidak akan dikirim ke Cloud Logging.

Langkah selanjutnya

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