本頁面說明如何使用 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 顯示以下步驟:
- 呼叫端發出
fhirStores.fhir.create要求,建立 FHIR 資源。 - FHIR 儲存庫會收到要求、建立 Pub/Sub 訊息,並傳送至 FHIR 儲存庫上設定的 Pub/Sub 主題。
- Pub/Sub 會將訊息轉送至附加至主題的訂閱項目。
- 訂閱者會透過訂閱項目收到 Pub/Sub 訊息形式的通知。每個訂閱項目可以有一或多個訂閱者,以提高平行處理能力。
通知設定
您可以在 FHIR 儲存庫的 FhirNotificationConfig 物件中設定 Pub/Sub 通知及其行為。每個 FHIR 儲存庫可設定多個。FhirNotificationConfig
下表說明 FhirNotificationConfig 物件中的欄位。
| 欄位 | 說明 | 範例 |
|---|---|---|
pubsubTopic |
要附加至 FHIR 儲存庫的 Pub/Sub 主題。通知會傳送至指定主題。 | projects/my-project/topics/my-topic |
sendFullResource |
是否要在通知中加入已建立、更新或修補的 FHIR 資源完整內容。刪除 FHIR 資源時傳送的通知不受此欄位影響。如要納入已刪除資源的完整內容,請將 sendPreviousResourceOnDelete 設為 true。 |
true |
sendPreviousResourceOnDelete |
是否要在通知中加入已刪除 FHIR 資源的完整內容。這個欄位不會影響在建立、更新或修補 FHIR 資源時傳送的通知。 | true |
通知格式和內容
每個 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 物件中的每個欄位:
| 屬性 | 說明 | 範例 |
|---|---|---|
action |
對 FHIR 資源執行的動作。可能的值包括:
|
CreateResource |
resourceType |
遭修改的 FHIR 資源類型。可能的值包括 Cloud Healthcare API 中任何支援的 FHIR 資源類型。 | Patient |
payloadType |
訊息的酬載類型,為 NameOnly 或 FullResource。 |
FullResource |
storeName |
發生動作的 FHIR 儲存庫完整資源名稱。 | projects/my-project/locations/us/datasets/my-dataset/fhirStores/my-fhir-store |
lastUpdatedTime |
FHIR 資源最近一次修改的時間戳記。時間戳記採用 RFC 1123 格式。 | Mon, 01 Jan 2020 00:00:00 UTC |
versionId |
發生動作的最新版 FHIR 資源 ID。如要進一步瞭解版本 ID,請參閱「列出 FHIR 資源版本」。 | MTY4MzA2MDQzOTI5NjIxMDAwMA |
下表說明 message 物件中的其餘欄位:
| 欄位 | 說明 | 範例 |
|---|---|---|
data |
FHIR 資源名稱或 FHIR 資源內容的 Base64 編碼字串,視 FhirNotificationConfig 中指定的值而定。 |
|
messageId |
Pub/Sub 訊息的 ID。 | |
publishTime |
Pub/Sub 伺服器發布訊息的時間。 |
指定要在通知中顯示的資訊
如「通知格式和內容」一文所述,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 配額和限制。如要瞭解如何查看配額、申請提高配額值,以及配額用盡時會發生什麼情況,請參閱 Cloud Quotas 說明文件。
啟用 Pub/Sub API
在 Google Cloud 控制台啟用 Pub/Sub 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 資源內容。
REST
如要編輯 FHIR 儲存庫,請使用 projects.locations.datasets.fhirStores.patch 方法。
使用任何要求資料之前,請先替換以下項目:
- PROJECT_ID:您的 Google Cloud 專案 ID
- LOCATION:資料集位置
- DATASET_ID:FHIR 儲存庫的父項資料集
- FHIR_STORE_ID:FHIR 儲存庫 ID
- PUBSUB_TOPIC_ID:Pub/Sub 主題 ID
JSON 要求主體:
{
"notificationConfigs": [
{
"pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
"sendFullResource": true,
"sendPreviousResourceOnDelete": true
}
]
}
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json 的檔案中。
在終端機中執行下列指令,在目前目錄中建立或覆寫這個檔案:
cat > request.json << 'EOF'
{
"notificationConfigs": [
{
"pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
"sendFullResource": true,
"sendPreviousResourceOnDelete": true
}
]
}
EOF接著,請執行下列指令來傳送 REST 要求:
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"
PowerShell
將要求主體儲存在名為 request.json 的檔案中。
在終端機中執行下列指令,在目前目錄中建立或覆寫這個檔案:
@'
{
"notificationConfigs": [
{
"pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
"sendFullResource": true,
"sendPreviousResourceOnDelete": true
}
]
}
'@ | Out-File -FilePath request.json -Encoding utf8接著,請執行下列指令來傳送 REST 要求:
$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
您應該會收到如下的 JSON 回應:
建立 FHIR 資源
在 FHIR 儲存庫中建立 FHIR 資源。這項要求會導致 Cloud Healthcare API 將訊息發布至已設定的 Pub/Sub 主題。
查看 Pub/Sub 通知
查看發布至 Pub/Sub 主題的訊息。在 FHIR 儲存庫中建立 Patient 資源時,系統會產生下列訊息。
在範例輸出內容中,FHIR 資源的內容位於 data 欄位,並以 Base64 編碼字串表示。您必須解碼 Base64 編碼的值,才能取得內容。大多數平台和作業系統都有工具,可以將 base64 文字解碼。
REST
如要查看發布至 Pub/Sub 主題的訊息,請使用 projects.subscriptions.pull 方法。下列範例使用 ?maxMessages=10 查詢參數,指定要求中要傳回的訊息數量上限。您可以視需要調整值。
使用任何要求資料之前,請先替換以下項目:
- PROJECT_ID:您的 Google Cloud 專案 ID
- PUBSUB_SUBSCRIPTION_ID:附加至 FHIR 存放區中設定的 Pub/Sub 主題的訂閱項目 ID
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
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
執行下列指令:
$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
您應該會收到如下的 JSON 回應:
gcloud
如要查看發布至 Pub/Sub 主題的訊息,請執行
gcloud pubsub subscriptions pull
指令。
這個範例使用下列 Google Cloud CLI 標記:
--format=json:以 JSON 格式算繪輸出內容。--auto-ack:自動確認提取的每則訊息。
使用下列任何指令資料之前,請先替換以下項目:
- PROJECT_ID:您的 Google Cloud 專案 ID
- PUBSUB_SUBSCRIPTION_ID:附加至 FHIR 存放區中設定的 Pub/Sub 主題的訂閱項目 ID
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud pubsub subscriptions pull \ projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID \ --auto-ack \ --format=json
Windows (PowerShell)
gcloud pubsub subscriptions pull ` projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ` --auto-ack ` --format=json
Windows (cmd.exe)
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 欄位一律會包含下列鍵/值組合:
| 屬性名稱 | 可能的值 | 範例 | 說明 |
|---|---|---|---|
action |
|
CreateResource |
最新發生事件的類型。 |
resourceType |
任何 FHIR 資源類型。 | Patient |
遭修改的資源類型。 |