Notifikasi Pub/Sub FHIR

Halaman ini menjelaskan cara menggunakan Pub/Sub untuk mendapatkan notifikasi saat peristiwa klinis terjadi di penyimpanan FHIR.

Anda dapat menggunakan notifikasi Pub/Sub untuk beberapa kasus penggunaan, termasuk memicu pemrosesan atau analisis data baru di hilir. Misalnya, model machine learning dapat menerima notifikasi saat data baru tersedia untuk pelatihan dan menghasilkan insight atau prediksi untuk meningkatkan kualitas perawatan pasien.

Ringkasan

Anda dapat menerima notifikasi Pub/Sub saat resource FHIR dibuat, diupdate, di-patch, atau dihapus di penyimpanan FHIR. Cloud Healthcare API tidak mengirim notifikasi saat resource FHIR diimpor dari Cloud Storage.

Untuk menerima notifikasi, Anda harus membuat topik dan langganan Pub/Sub, lalu mengonfigurasi penyimpanan FHIR untuk mengirim notifikasi ke topik tersebut.

Diagram berikut menunjukkan cara pembuatan dan pengiriman notifikasi Pub/Sub saat resource FHIR dibuat di penyimpanan FHIR menggunakan metode fhir.create. Langkah-langkahnya sama saat resource FHIR diupdate, di-patch, atau dihapus.

Gambar 1. Menggunakan notifikasi Pub/Sub untuk perubahan di penyimpanan FHIR.

Gambar 1 menunjukkan langkah-langkah berikut:

1. Pemanggil membuat permintaan fhirStores.fhir.create untuk membuat resource FHIR.
2. Penyimpanan FHIR menerima permintaan, membuat pesan Pub/Sub, dan mengirimkannya ke topik Pub/Sub yang dikonfigurasi di penyimpanan FHIR.
3. Pub/Sub meneruskan pesan ke langganan yang terlampir ke topik.
4. Pelanggan menerima notifikasi, dalam bentuk pesan Pub/Sub, dari langganan mereka. Setiap langganan dapat memiliki satu atau beberapa pelanggan untuk meningkatkan paralelisme.

Konfigurasi notifikasi

Anda dapat mengonfigurasi notifikasi Pub/Sub dan perilakunya dalam objek FhirNotificationConfig di penyimpanan FHIR. Setiap penyimpanan FHIR dapat memiliki beberapa FhirNotificationConfig yang dikonfigurasi.

Tabel berikut menjelaskan kolom dalam objek FhirNotificationConfig.

Format dan konten notifikasi

Setiap notifikasi Pub/Sub berisi objek message yang menyimpan informasi tentang peristiwa klinis. Objek message akan terlihat mirip dengan berikut:

{
  "message": {
    "attributes": {
      "action": "ACTION",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "PAYLOAD_TYPE",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE_64_ENCODED_DATA",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

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

Tabel berikut menjelaskan setiap kolom dalam objek attributes:

Tabel berikut menjelaskan kolom yang tersisa dalam objek message:

Menentukan informasi yang akan disertakan dalam notifikasi

Notifikasi Pub/Sub, seperti yang dijelaskan dalam Format dan konten notifikasi, mencakup kumpulan kolom standar. Anda dapat menyertakan resource FHIR lengkap atau hanya namanya di setiap notifikasi. Nama resource berisi jalur lengkap ke resource dan ID resource dalam format ini:

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID

Informasi resource FHIR disimpan di kolom data sebagai string berenkode base64.

Dengan menyertakan seluruh konten resource FHIR, Anda tidak perlu mengirim kueri secara terpisah ke Pub/Sub dan Cloud Healthcare API untuk mendapatkan detail resource.

Mendapatkan nama resource FHIR

Untuk hanya menyertakan nama resource FHIR saat Anda membuat, memperbarui, atau membuat patch resource, tetapkan sendFullResource ke false. Untuk hanya menyertakan nama saat Anda menghapus resource FHIR, tetapkan sendPreviousResourceOnDelete ke false.

Saat Anda melihat notifikasi, objek message akan terlihat seperti berikut:

{
  "message": {
    "attributes": {
      "action": "{CreateResource|PatchResource|UpdateResource|DeleteResource}",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "NameOnly",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE64_ENCODED_FHIR_RESOURCE_NAME",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

Perhatikan hal berikut dalam notifikasi:

• Kolom payloadType ditetapkan ke NameOnly untuk menunjukkan hal berikut tentang permintaan:

  • Untuk operasi pembuatan, pembaruan, dan patch, sendFullResource disetel ke false.
  • Untuk operasi penghapusan, sendPreviousResourceOnDelete disetel ke false.

• Hanya nama resource FHIR yang disertakan dalam kolom data. Nama dienkode sebagai string berenkode base64.

Mendapatkan konten resource FHIR yang dibuat, diupdate, atau di-patch

Untuk menyertakan seluruh konten resource FHIR saat Anda membuat, mengupdate, atau membuat patch resource, tetapkan sendFullResource ke true.

Perilaku ini tidak berlaku jika Anda menghapus resource FHIR. Jika Anda menghapus resource FHIR, dan sendFullResource disetel ke true, tetapi sendPreviousResourceOnDelete disetel ke false, notifikasi akan sama seperti saat Anda hanya mengambil nama resource FHIR. Untuk menyertakan konten resource FHIR saat resource FHIR dihapus, lihat Mendapatkan konten resource FHIR yang dihapus.

Saat Anda melihat notifikasi, objek message akan terlihat seperti berikut:

{
  "message": {
    "attributes": {
      "action": "{CreateResource|PatchResource|UpdateResource}",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "FullResource",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE64_ENCODED_FHIR_RESOURCE_CONTENTS",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

Perhatikan hal berikut dalam notifikasi:

• payloadType disetel ke FullResource untuk menunjukkan bahwa sendFullResource disetel ke true. Seluruh konten resource FHIR disertakan dalam kolom data sebagai string berenkode base64.
• Kolom data berisi konten resource FHIR sebagai string berenkode base64.

Mendapatkan konten resource FHIR yang dihapus

Untuk menyertakan seluruh konten resource FHIR saat Anda menghapusnya, tetapkan sendPreviousResourceOnDelete ke true.

Saat Anda melihat notifikasi, objek message akan terlihat seperti berikut:

{
  "message": {
    "attributes": {
      "action": "DeleteResource",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "FullResource",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE64_ENCODED_FHIR_RESOURCE_CONTENTS",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

Catat nilai di kolom berikut:

• payloadType disetel ke FullResource meskipun sendFullResource disetel ke false.

  Seluruh konten resource FHIR disertakan dalam kolom data sebagai string berenkode base64.

• Kolom data berisi konten resource FHIR sebagai string berenkode base64 sebelum resource dihapus.

Mengonfigurasi dan melihat notifikasi FHIR

Contoh berikut menunjukkan cara melihat notifikasi Pub/Sub yang dibuat saat resource FHIR dibuat di penyimpanan FHIR.

Sebelum memulai

Sebelum mengonfigurasi dan menggunakan notifikasi Pub/Sub, selesaikan bagian berikut:

Meninjau kuota Pub/Sub

Pahami kuota dan batas Pub/Sub. Untuk mengetahui informasi tentang cara melihat kuota, meminta lebih banyak kuota, dan apa yang terjadi jika kuota Anda habis, lihat Menangani kuota.

Aktifkan Pub/Sub API

Di konsol Google Cloud , aktifkan Pub/Sub API:

Mengaktifkan API

Mengonfigurasi izin Pub/Sub

Agar pesan dapat dipublikasikan dari Cloud Healthcare API ke Pub/Sub, Anda harus menambahkan peran pubsub.publisher ke akun layanan Agen Layanan Cloud Healthcare project Anda. Lihat Izin Pub/Sub penyimpanan DICOM, FHIR, dan HL7v2 untuk mengetahui langkah-langkah menambahkan peran yang diperlukan.

Membuat topik Pub/Sub

Untuk membuat topik, lihat Membuat topik.

Setiap penyimpanan data dapat memiliki topik Pub/Sub sendiri, atau beberapa penyimpanan data dapat berbagi topik yang sama.

Gunakan format berikut saat menentukan topik Pub/Sub:

projects/PROJECT_ID/topics/TOPIC_NAME

PROJECT_ID adalah project ID Google Cloud Anda dan TOPIC_NAME adalah nama topik Pub/Sub.

Membuat langganan Pub/Sub

Untuk menerima pesan yang dipublikasikan ke suatu topik, Anda perlu membuat langganan Pub/Sub. Setiap topik Pub/Sub memerlukan setidaknya satu langganan Pub/Sub. Langganan menghubungkan topik ke aplikasi pelanggan yang menerima dan memproses pesan yang dipublikasikan ke topik.

Untuk membuat langganan dan melampirkannya ke topik Pub/Sub, lihat Membuat langganan.

Membuat atau mengedit penyimpanan FHIR

Buat atau edit penyimpanan FHIR dengan objek FhirNotificationConfig yang dikonfigurasi.

Contoh berikut menunjukkan cara mengedit penyimpanan FHIR yang ada. Kolom sendFullResource dan sendPreviousResourceOnDelete disetel ke true, yang berarti bahwa notifikasi berisi konten resource FHIR lengkap saat resource dibuat, diperbarui, di-patch, atau dihapus.

{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}

cat > request.json << 'EOF'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": 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/fhirStores/FHIR_STORE_ID?updateMask=notificationConfigs"

@'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": 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/fhirStores/FHIR_STORE_ID?updateMask=notificationConfigs" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "R4",
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}

Membuat resource FHIR

Buat resource FHIR di penyimpanan FHIR. Permintaan ini menyebabkan Cloud Healthcare API memublikasikan pesan ke topik Pub/Sub yang dikonfigurasi.

Melihat notifikasi Pub/Sub

Lihat pesan yang dipublikasikan ke topik Pub/Sub. Pesan berikut dibuat saat resource Patient dibuat di penyimpanan FHIR.

Dalam contoh output, konten resource FHIR berada dalam string berenkode base64 di kolom data. Anda harus mendekode nilai berenkode base64 untuk mendapatkan kontennya. Sebagian besar platform dan sistem operasi memiliki alat untuk mendekode teks base64.

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"

$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

{
  "receivedMessages": [
    {
      "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
      "message": {
        "data": "wogICJiaXJ0aERhdGUiOiAiMTk3MC0wMS0wMSIsCiAgImdlbmRlciI6ICJmZW1hbGUiLAogICJpZCI6ICIyYmMwODg4Yi00MGRmLTQwYzctOWRhYi0wMzc4YTFiZWE0MGIiLAogICJtZXRhIjogewogICAgImxhc3RVcGRhdGVkIjogIjIwMjMtMDUtMDJUMjA6NDc6MTkuMjk2MjEwKzAwOjAwIiwKICAgICJ2ZXJzaW9uSWQiOiAiTVRZNE16QTJNRFF6T1RJNU5qSXhNREF3TUEiCiAgfSwKICAibmFtZSI6IFsKICAgIHsKICAgICAgImZhbWlseSI6ICJTbWl0aCIsCiAgICAgICJnaXZlbiI6IFsKICAgICAgICAiRGFyY3kiCiAgICAgIF0sCiAgICAgICJ1c2UiOiAib2ZmaWNpYWwiCiAgICB9CiAgXSwKICAicmVzb3VyY2VUeXBlIjogIlBhdGllbnQiCn0=",
        "attributes": {
          "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
          "action": "CreateResource",
          "versionId": "MTY4MzA2MDQzOTI5NjIxMDAwMA",
          "resourceType": "Patient",
          "lastUpdatedTime": "Mon, 01 Jan 2020 00:00:00 UTC",
          "payloadType": "FullResource"
        },
        "messageId": "7586159156345265",
        "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
      }
    }
  ]
}

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

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

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

[
  {
    "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
    "ackStatus": "SUCCESS",
    "message": {
      "attributes": {
        "action": "CreateResource",
        "lastUpdatedTime": "Mon, 01 Jan 2020 00:00:00 UTC",
        "payloadType": "FullResource",
        "resourceType": "Patient",
        "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
        "versionId": "MTY4MzA2MDQzOTI5NjIxMDAwMA"
      },
      "data": "wogICJiaXJ0aERhdGUiOiAiMTk3MC0wMS0wMSIsCiAgImdlbmRlciI6ICJmZW1hbGUiLAogICJpZCI6ICIyYmMwODg4Yi00MGRmLTQwYzctOWRhYi0wMzc4YTFiZWE0MGIiLAogICJtZXRhIjogewogICAgImxhc3RVcGRhdGVkIjogIjIwMjMtMDUtMDJUMjA6NDc6MTkuMjk2MjEwKzAwOjAwIiwKICAgICJ2ZXJzaW9uSWQiOiAiTVRZNE16QTJNRFF6T1RJNU5qSXhNREF3TUEiCiAgfSwKICAibmFtZSI6IFsKICAgIHsKICAgICAgImZhbWlseSI6ICJTbWl0aCIsCiAgICAgICJnaXZlbiI6IFsKICAgICAgICAiRGFyY3kiCiAgICAgIF0sCiAgICAgICJ1c2UiOiAib2ZmaWNpYWwiCiAgICB9CiAgXSwKICAicmVzb3VyY2VUeXBlIjogIlBhdGllbnQiCn0=",
      "messageId": "7586159156345265",
      "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
    }
  }
]

Perilaku saat resource FHIR terlalu besar atau traffic tinggi

Jika ukuran resource FHIR terlalu besar, atau server Cloud Healthcare API mengalami traffic tinggi, kolom attributes mungkin hanya berisi nama resource, bukan konten resource lengkap. Perilaku ini terjadi meskipun sendFullResource dan sendPreviousResourceOnDelete disetel ke true.

Untuk memverifikasi apakah notifikasi Pub/Sub berisi resource FHIR lengkap, periksa kolom payloadType dalam respons dari melihat notifikasi. Jika payloadType ditetapkan ke nameOnly, berarti kolom attributes tidak sepenuhnya mengisi data resource FHIR. Kemudian, Anda harus mendapatkan konten resource FHIR secara manual dari penyimpanan FHIR, bukan dari pesan Pub/Sub.

Kebijakan penyimpanan pesan Cloud Healthcare API dan Pub/Sub

Untuk memastikan bahwa data Cloud Healthcare API Anda 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 pada topik Pub/Sub yang dikonfigurasi di penyimpanan data untuk memastikan data tetap berada di region yang sama. Misalnya, jika set data dan penyimpanan FHIR Cloud Healthcare API 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 di Cloud Logging. Untuk mengetahui informasi selengkapnya, lihat artikel Melihat log error di Cloud Logging.

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

Melihat notifikasi FHIR menggunakan konfigurasi NotificationConfig (Tidak digunakan lagi)

Resource FhirStore berisi objek NotificationConfig tempat Anda dapat menentukan topik Pub/Sub. Perubahan pada resource FHIR selalu berisi ID berikut di kolom data pesan Pub/Sub:

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID

Serangkaian key:value pair berikut selalu disertakan dalam kolom attributes pesan:

Langkah berikutnya

• Gunakan kontrol alur untuk menangani lonjakan traffic pesan Pub/Sub sementara.
• Menangani kegagalan pesan.
• Memutar ulang dan menghapus permanen pesan.
• Lihat ringkasan arsitektur Pub/Sub.