FHIR Pub/Sub 通知

本頁面說明如何使用 Pub/Sub，在 FHIR 存放區發生臨床事件時接收通知。

Pub/Sub 通知可用於多種用途，包括觸發新資料的下游處理或分析作業。舉例來說，當有新資料可供訓練時，機器學習模型可以接收通知，並生成洞察資料或預測結果，以改善病患照護。

總覽

當 FHIR 存放區中的 FHIR 資源建立、更新、修補或刪除時，您會收到 Pub/Sub 通知。從 Cloud Storage 匯入 FHIR 資源時，Cloud Healthcare API 不會傳送通知。

如要接收通知，您必須建立 Pub/Sub 主題和訂閱項目，然後設定 FHIR 存放區，將通知傳送至該主題。

下圖說明使用 fhir.create 方法在 FHIR 儲存庫中建立 FHIR 資源時，系統如何建立及傳送 Pub/Sub 通知。更新、修補或刪除 FHIR 資源時，操作步驟都相同。

圖 1. 使用 Pub/Sub 通知瞭解 FHIR 存放區的變更。

圖 1 顯示以下步驟：

1. 呼叫端發出 fhirStores.fhir.create 要求，建立 FHIR 資源。
2. FHIR 儲存庫會收到要求、建立 Pub/Sub 訊息，並傳送至 FHIR 儲存庫上設定的 Pub/Sub 主題。
3. Pub/Sub 會將訊息轉送至附加至主題的訂閱項目。
4. 訂閱者會收到訂閱內容的通知，通知形式為 Pub/Sub 訊息。每個訂閱項目可以有一或多個訂閱者，以提高平行處理能力。

通知設定

您可以在 FHIR 儲存庫的 FhirNotificationConfig 物件中設定 Pub/Sub 通知及其行為。每個 FHIR 儲存庫可設定多個。FhirNotificationConfig

下表說明 FhirNotificationConfig 物件中的欄位。

通知格式和內容

每個 Pub/Sub 通知都包含 message 物件，其中含有臨床事件的相關資訊。message 物件如下所示：

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

如要瞭解每則 Pub/Sub 訊息中包含的其他欄位，請參閱 ReceivedMessage 和 PubsubMessage。

下表說明 attributes 物件中的每個欄位：

下表說明 message 物件中的其餘欄位：

指定要在通知中顯示的資訊

如「通知格式和內容」一文所述，Pub/Sub 通知包含一組標準欄位。您可以在每則通知中加入完整的 FHIR 資源或僅加入其名稱。資源名稱包含資源的完整路徑和資源 ID，格式如下：

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

FHIR 資源資訊會以 base64 編碼字串的形式，儲存在 data 欄位中。

只要納入 FHIR 資源的完整內容，就不必分別查詢 Pub/Sub 和 Cloud Healthcare API，取得資源詳細資料。

取得 FHIR 資源名稱

如要在建立、更新或修補資源時只納入 FHIR 資源名稱，請將 sendFullResource 設為 false。如要在刪除 FHIR 資源時只納入名稱，請將 sendPreviousResourceOnDelete 設為 false。

查看通知時，message 物件看起來會類似下列內容：

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

請注意通知中的下列事項：

• payloadType 欄位設為 NameOnly，表示要求具有下列特性：

  • 如果是建立、更新和修補作業，sendFullResource 會設為 false。
  • 如果是刪除作業，sendPreviousResourceOnDelete 會設為 false。

• data 欄位只會包含 FHIR 資源名稱。名稱會編碼為 Base64 編碼字串。

取得已建立、更新或修補的 FHIR 資源內容

如要在建立、更新或修補資源時納入 FHIR 資源的完整內容，請將 sendFullResource 設為 true。

刪除 FHIR 資源時，不會發生這種情況。如果您刪除 FHIR 資源，且 sendFullResource 設為 true，但 sendPreviousResourceOnDelete 設為 false，則通知與只擷取 FHIR 資源名稱時相同。如要在刪除 FHIR 資源時一併納入 FHIR 資源內容，請參閱「取得已刪除的 FHIR 資源內容」。

查看通知時，message 物件看起來會類似下列內容：

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

請注意通知中的下列事項：

• payloadType 設為 FullResource，表示 sendFullResource 設為 true。FHIR 資源的完整內容會以 Base64 編碼字串的形式，納入 data 欄位。
• data 欄位包含 FHIR 資源內容，以 Base64 編碼字串的形式呈現。

取得已刪除的 FHIR 資源內容

如要在刪除 FHIR 資源時一併納入完整內容，請將 sendPreviousResourceOnDelete 設為 true。

查看通知時，message 物件看起來會類似下列內容：

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

請記下下列欄位中的值：

• 即使 sendFullResource 設為 false，payloadType 仍會設為 FullResource。

  FHIR 資源的完整內容會以 Base64 編碼字串的形式，納入 data 欄位。

• data 欄位包含 FHIR 資源的內容，以 Base64 編碼字串的形式呈現，這是資源刪除前的狀態。

設定及查看 FHIR 通知

下列範例說明如何在 FHIR 儲存庫中建立 FHIR 資源時，查看產生的 Pub/Sub 通知。

事前準備

設定及使用 Pub/Sub 通知前，請先完成下列章節：

查看 Pub/Sub 配額

熟悉 Pub/Sub 配額和限制。如要瞭解如何查看配額、要求更多配額，以及配額用盡時會發生什麼情況，請參閱「處理配額」。

啟用 Pub/Sub API

在 Google Cloud 控制台啟用 Pub/Sub API：

啟用 API

設定 Pub/Sub 權限

如要允許從 Cloud Healthcare API 將訊息發布至 Pub/Sub，您必須將 pubsub.publisher 角色新增至專案的 Cloud Healthcare 服務代理人 服務帳戶。 如要瞭解如何新增必要角色，請參閱「DICOM、FHIR 和 HL7v2 儲存庫的 Pub/Sub 權限」。

建立 Pub/Sub 主題

如要建立主題，請參閱「建立主題」。

個別資料儲存庫可以有自己的 Pub/Sub 主題，多個資料儲存庫也可以共用相同的主題。

指定 Pub/Sub 主題時，請使用下列格式：

projects/PROJECT_ID/topics/TOPIC_NAME

PROJECT_ID 是您的 Google Cloud 專案 ID，TOPIC_NAME 則是 Pub/Sub 主題的名稱。

建立 Pub/Sub 訂閱項目

如要接收發布至某項主題的訊息，您必須建立 Pub/Sub 訂閱項目。每個 Pub/Sub 主題至少需要一個 Pub/Sub 訂閱項目。訂閱項目會將主題連結至訂閱者應用程式，以便接收及處理發布至主題的訊息。

如要建立訂閱項目並附加至 Pub/Sub 主題，請參閱「建立訂閱項目」。

建立或編輯 FHIR 儲存庫

建立或編輯已設定 FhirNotificationConfig 物件的 FHIR 儲存庫。

下列範例說明如何編輯現有的 FHIR 儲存庫。sendFullResource 和 sendPreviousResourceOnDelete 欄位會設為 true，也就是說，當資源建立、更新、修補或刪除時，通知會包含完整的 FHIR 資源內容。

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

建立 FHIR 資源

在 FHIR 儲存庫中建立 FHIR 資源。這項要求會導致 Cloud Healthcare API 將訊息發布至已設定的 Pub/Sub 主題。

查看 Pub/Sub 通知

查看發布至 Pub/Sub 主題的訊息。在 FHIR 儲存庫中建立 Patient 資源時，系統會產生下列訊息。

在範例輸出內容中，FHIR 資源的內容位於 data 欄位，並以 Base64 編碼字串的形式呈現。您必須解碼 Base64 編碼的值，才能取得內容。大多數平台和作業系統都有工具，可以將 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"
    }
  }
]

FHIR 資源過大或流量過高時的行為

如果 FHIR 資源過大，或 Cloud Healthcare API 伺服器流量過高，attributes 欄位可能只會包含資源名稱，而非完整資源內容。即使 sendFullResource 和 sendPreviousResourceOnDelete 設為 true，也會發生這種情況。

如要確認 Pub/Sub 通知是否包含完整的 FHIR 資源，請查看通知回應中的 payloadType 欄位。如果 payloadType 設為 nameOnly，表示 attributes 欄位未完整填入 FHIR 資源資料。您必須從 FHIR 儲存庫手動取得 FHIR 資源的內容，而不是從 Pub/Sub 訊息取得。

Cloud Healthcare API 和 Pub/Sub 訊息儲存政策

如要確保 Cloud Healthcare API 資料和 Pub/Sub 訊息中的相關聯資料位於同一區域，您必須設定 Pub/Sub 訊息儲存政策。

您必須在資料存放區設定的 Pub/Sub 主題上明確設定訊息儲存政策，確保資料保留在同一區域。舉例來說，如果 Cloud Healthcare API 資料集和 FHIR 儲存庫位於 us-central1，訊息儲存政策就只能允許 us-central1 地區。

如要設定郵件儲存政策，請參閱「設定郵件儲存政策」。

排解 Pub/Sub 訊息遺失問題

如果通知無法發布至 Pub/Sub，系統會將錯誤記錄到 Cloud Logging。詳情請參閱「查看 Cloud Logging 中的錯誤記錄檔」。

如果錯誤產生率超過上限，系統就不會將超過上限的錯誤提交至 Cloud Logging。

使用 NotificationConfig 設定查看 FHIR 通知 (已淘汰)

FhirStore 資源包含 NotificationConfig 物件，您可以在其中指定 Pub/Sub 主題。FHIR 資源的變更一律會在 Pub/Sub 訊息的 data 欄位中包含下列 ID：

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

訊息的 attributes 欄位一律會包含下列鍵/值組合：

後續步驟

• 使用流量控制機制，處理 Pub/Sub 訊息流量的暫時性尖峰。
• 處理傳送失敗的訊息。
• 重播及清除訊息。
• 查看 Pub/Sub 架構總覽。