設定 DICOM Pub/Sub 通知

本頁面說明如何使用 Pub/Sub 接收 DICOM 儲存庫中臨床事件的通知。當新的 DICOM 執行個體儲存在 DICOM 儲存庫中，或從 Cloud Storage 匯入時，您會收到 Pub/Sub 通知。

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

下圖說明如何產生及發布 Pub/Sub 通知。

DICOM Pub/Sub 通知。

圖 1. 接收 DICOM 儲存庫中臨床事件的 Pub/Sub 通知。

圖 1 顯示以下步驟：

  1. 呼叫端要求儲存或匯入 DICOM 執行個體。
  2. DICOM 儲存庫會收到要求、建立 Pub/Sub 訊息，並傳送至 DICOM 儲存庫上設定的 Pub/Sub 主題。
  3. Pub/Sub 會將訊息轉送至附加至主題的訂閱項目。
  4. 訂閱者會透過訂閱項目接收訊息。每個訂閱項目可以有一或多個訂閱者，以提高平行處理能力。

事前準備

  1. 建立主題。
  2. 建立提取訂閱項目。

新增 Pub/Sub 發布者權限

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

通知格式和內容

Pub/Sub 通知包含 Message 物件，其中含有臨床事件的相關資訊。Message 物件看起來類似如下：

{
  "message": {
    "attributes": {
      "action": "ACTION",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
      "studyInstanceUID": "STUDY_UID",
      "seriesInstanceUID": "SERIES_UID",
      "sopInstanceUID": "INSTANCE_UID",
      "versionId": "VERSION_ID",
      "modality": "MODALITY",
      "storageClass": "STORAGE_CLASS",
      "previousStorageClass": "PREVIOUS_STORAGE_CLASS"
    },
    "data": "BASE_64_ENCODED_DATA",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

如要進一步瞭解每個 Pub/Sub 訊息包含的欄位，請參閱 ReceivedMessage 和 PubsubMessage。

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

屬性 說明 範例
action 對 DICOM 資源執行的動作。可能的值包括：
  • StoreInstances
  • ImportDicomData
  • SetBlobSettings
  • DeleteInstances
 StoreInstances
lastUpdatedTime DICOM 資源最近一次修改的時間戳記。時間戳記採用 RFC 1123 格式。 Mon, 01 Jan 2020 00:00:00 UTC
storeName 發生動作的 DICOM 存放區完整資源名稱。 projects/my-project/locations/us/datasets/my-dataset/dicomStores/my-dicom-store
studyInstanceUID DICOM 研究例項專屬 ID (UID)。 1.2.3.4.5.6
seriesInstanceUID DICOM 系列執行個體專屬 ID (UID)。 1.2.3.4.5.6
sopInstanceUID DICOM SOP 執行個體專屬 ID (UID)。 1.2.3.4.5.6
versionId 發生動作的最新版 DICOM 資源 ID。 MTY4MzA2MDQzOTI5NjIxMDAwMA
modality DICOM 資源的模態標記。可能的值包括但不限於：
  • CT
  • MR
  • MG
 CT
storageClass DICOM 資源的儲存空間類別。可能的值包括：
  • STANDARD
  • NEARLINE
  • COLDLINE
  • ARCHIVE
 STANDARD
previousStorageClass DICOM 資源先前的儲存空間級別。可能的值包括：
  • STANDARD
  • NEARLINE
  • COLDLINE
  • ARCHIVE
 NEARLINE

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

欄位 說明
data 以下 ID 的 Base64 編碼字串：projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID
messageId Pub/Sub 訊息的 ID。
publishTime Pub/Sub 伺服器發布訊息的時間。

設定及查看通知

本節說明如何在 DICOM 儲存庫中啟用 Pub/Sub 通知、儲存或匯入 DICOM 執行個體來發布通知，以及查看通知。

設定 DICOM 儲存庫

下列範例說明如何在新 DICOM 執行個體儲存或從 Cloud Storage 匯入時，在 DICOM 儲存庫中啟用 Pub/Sub 通知。

REST

請使用 projects.locations.datasets.dicomStores.patch 方法。

NotificationConfig.sendForBulkImport 值為 true，因此從 Cloud Storage 匯入資料時會傳送通知。

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：資料集位置
  • DATASET_ID：DICOM 儲存庫的父項資料集
  • DICOM_STORE_ID：DICOM 儲存庫 ID
  • PUBSUB_TOPIC：當資料儲存庫中發生事件時，訊息發布至的 Pub/Sub 主題

JSON 要求主體：

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

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "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/dicomStores/DICOM_STORE_ID?updateMask=notificationConfig"

PowerShell

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "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/dicomStores/DICOM_STORE_ID?updateMask=notificationConfig" | Select-Object -Expand Content

APIs Explorer

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求內文貼到這項工具中，並填妥其他必填欄位，然後按一下「Execute」(執行)。

您應該會收到類似以下的回覆。

如果您在 DicomStore 資源中設定任何欄位，這些欄位也會顯示在回應中。

gcloud

執行 gcloud healthcare dicom-stores update 指令。

使用下方的任何指令資料之前，請先替換以下項目：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：資料集位置
  • DATASET_ID：DICOM 儲存庫的父項資料集
  • DICOM_STORE_ID：DICOM 儲存庫 ID
  • PUBSUB_TOPIC：資料儲存庫發生事件時，訊息發布至的 Pub/Sub 主題

執行下列指令：

Linux、macOS 或 Cloud Shell

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)

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)

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

您應該會收到類似以下的回應：

回應

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

儲存或匯入 DICOM 執行個體，並查看 Pub/Sub 通知

如要儲存或匯入 DICOM 執行個體，並提取產生的 Pub/Sub 訊息，請完成下列步驟：

  1. 儲存或匯入 DICOM 執行個體。這項要求會導致 Cloud Healthcare API 將訊息發布至已設定的 Pub/Sub 主題。

  2. 提取訊息。如果單一要求匯入多個 DICOM 執行個體，系統會為每個 DICOM 執行個體產生一則訊息。

    如要查看提取 Pub/Sub 訊息所需的 Identity and Access Management 權限，請參閱「Pub/Sub 存取權控管」。

    REST

    請使用 projects.subscriptions.pull 方法。下列範例使用 ?maxMessages=10 查詢參數，指定要求中要傳回的訊息數量上限。請根據您的用途調整這個值。

    使用任何要求資料之前，請先替換以下項目：

    • PROJECT_ID：您的 Google Cloud 專案 ID
    • PUBSUB_SUBSCRIPTION_ID：附加至 DICOM 儲存庫上設定的 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

    APIs Explorer

    開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

    您應該會收到如下的 JSON 回應：

    gcloud

    執行 gcloud pubsub subscriptions pull 指令。

    這個範例使用下列 Google Cloud CLI 標記：

    • --limit=10：最多傳回 10 則訊息。請根據您的用途調整這個值。
    • --format=json：以 JSON 格式算繪輸出內容。
    • --auto-ack：自動確認提取的每則訊息。

    使用下方的任何指令資料之前，請先替換以下項目：

    • PROJECT_ID：您的 Google Cloud 專案 ID
    • PUBSUB_SUBSCRIPTION_ID：附加至 DICOM 儲存庫上設定的 Pub/Sub 主題的訂閱 ID

    執行下列指令：

    Linux、macOS 或 Cloud Shell

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

    Windows (PowerShell)

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

    Windows (cmd.exe)

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

    您應該會收到類似以下的回應：

    [
  {
    "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
    "ackStatus": "SUCCESS",
    "message": {
      "attributes": {
        "action": "ImportDicomData",
        "lastUpdatedTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
        "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
        "studyInstanceUID": "1.3.6.1.4.1.1129.5.111396399361969898205364400549799252857604",
        "seriesInstanceUID": "1.3.6.1.4.1.1129.5.111396399361969898205364400549799252857605",
        "sopInstanceUID": "1.3.6.1.4.1.1129.5.111396399361969898205364400549799252857606",
        "versionId": "MTY4MzA2MDQzOTI5NjIxMDAwMA",
        "modality": "CT",
        "storageClass": "STANDARD",
      },
      "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==",
      "messageId": "7586159156345265",
      "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
    }
  }
]

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。

後續步驟