本頁面由 Cloud Translation API 翻譯而成。

將 FHIR 資源變更串流至 BigQuery

本頁說明如何設定 FHIR 存放區，在每次建立、更新、修補或刪除 FHIR 資源時，自動將 FHIR 資源匯出至 BigQuery 資料表。這項程序稱為「BigQuery 串流」。

您可以使用 BigQuery 串流執行下列操作：

以近乎即時的方式，將 FHIR 儲存庫中的資料與 BigQuery 資料集同步處理。
對 FHIR 資料執行複雜查詢，不必每次分析資料時都匯出至 BigQuery。

如要提升查詢效能並降低費用，您可以將 BigQuery 串流設定為分區資料表。如需操作說明，請參閱「以串流方式將 FHIR 資源傳入分區資料表」。

事前準備

請參閱「將 FHIR 資源匯出至 BigQuery」，瞭解匯出程序運作方式。

限制

如果您從 Cloud Storage 匯入 FHIR 資源，系統不會將變更串流至 BigQuery。

設定 BigQuery 權限

如要啟用 BigQuery 串流，您必須將其他權限授予 Cloud Healthcare 服務代理程式 服務帳戶。詳情請參閱「FHIR 存放區 BigQuery 權限」。

在 FHIR 儲存庫上設定 BigQuery 串流

如要啟用 BigQuery 串流，請在 FHIR 儲存庫中設定 StreamConfigs 物件。在 StreamConfigs 中，您可以設定 resourceTypes[] 陣列，控管 BigQuery 串流適用的 FHIR 資源類型。如未指定 resourceTypes[]，BigQuery 串流會套用至所有 FHIR 資源類型。

如要瞭解 StreamConfigs 中提供的其他設定 (例如 BigQueryDestination)，請參閱「匯出 FHIR 資源」。

下列範例說明如何在現有 FHIR 儲存庫上啟用 BigQuery 串流。

控制台

如要使用Google Cloud 主控台，在現有的 FHIR 儲存庫中設定 BigQuery 串流，請完成下列步驟：

在 Google Cloud 控制台中，前往「Datasets」(資料集) 頁面。

前往「資料集」頁面
選取要編輯 FHIR 儲存庫的資料集。
在「資料儲存庫」清單中，按一下要編輯的 FHIR 儲存庫。
在「BigQuery streaming」(BigQuery 串流) 區段中，完成下列步驟：
1. 按一下「新增串流設定」。
2. 在「New streaming configuration」(新的串流設定) 區段中，按一下「Browse」(瀏覽)，選取要串流 FHIR 資源變更的 BigQuery 資料集。
3. 在「結構定義類型」下拉式選單中，選取 BigQuery 資料表的輸出結構定義。可用的結構化資料如下：
  - Analytics。以 FHIR 的 SQL 文件為基礎的結構定義。由於 BigQuery 每張資料表最多只能有 10,000 個資料欄，因此系統不會為 Parameters.parameter.resource、Bundle.entry.resource 和 Bundle.entry.response.outcome 欄位產生結構定義。
  - Analytics V2。類似於 Analytics 結構定義的結構定義，但新增了下列支援：
    - 擴充功能的同一個 url 有多個值
    - 內含 FHIR 資源
    Analytics 第 2 版結構定義在目的地表格中使用的空間，比 Analytics 結構定義更多。
4. 在「遞迴結構深度」滑桿中選取深度層級，即可為輸出結構定義中的所有遞迴結構設定深度。根據預設，遞迴值為 2。
5. 在「選取 FHIR 資源類型」清單中，選取要串流的資源類型。
按一下「完成」，儲存串流設定。

gcloud

gcloud CLI 不支援這項操作。請改用 Google Cloud 控制台、curl、PowerShell 或偏好的語言。

REST

如要在現有的 FHIR 儲存庫上設定 BigQuery 串流，請使用 projects.locations.datasets.fhirStores.patch 方法。

下列範例未指定 resourceTypes[] 陣列，因此系統會為所有 FHIR 資源類型啟用 BigQuery 串流。

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

PROJECT_ID：您的 Google Cloud 專案 ID
LOCATION：資料集位置
DATASET_ID：FHIR 儲存庫的父項資料集
FHIR_STORE_ID：FHIR 儲存庫 ID
BIGQUERY_DATASET_ID：現有 BigQuery 資料集的名稱，您要將 FHIR 資源變更串流至該資料集
SCHEMA_TYPE：SchemaType 列舉的值。請使用下列其中一個值：
- ANALYTICS. 以 FHIR 的 SQL 文件為基礎的結構定義。由於 BigQuery 每張資料表最多只能有 10,000 個資料欄，因此系統不會為 Parameters.parameter.resource、Bundle.entry.resource 和 Bundle.entry.response.outcome 欄位產生結構定義。
- ANALYTICS_V2。類似於 ANALYTICS 的架構，但新增了下列項目的支援：
  - 擴充功能的同一個 url 有多個值
  - 內含 FHIR 資源
  ANALYTICS_V2 在目的地資料表使用的空間比 ANALYTICS 多
  。
WRITE_DISPOSITION：WriteDisposition 列舉的值。請使用下列其中一個值：
- WRITE_EMPTY。只在目的地 BigQuery 資料表空白時匯出資料。
- WRITE_TRUNCATE。在寫入 FHIR 資源前，清除 BigQuery 資料表中的所有現有資料。
- WRITE_APPEND. 將資料附加至目的地 BigQuery 資料表。

JSON 要求主體：

{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

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

curl

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

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

cat > request.json << 'EOF'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
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=streamConfigs"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

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

@'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
'@  | 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=streamConfigs" | Select-Object -Expand Content

APIs Explorer

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

您應該會收到類似如下的 JSON 回應。

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

回應

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "FHIR_STORE_VERSION",
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

根據預設，將 FHIR 資源變更串流至 BigQuery 時，系統會為每個串流的資源建立檢視區塊。檢視區塊具有下列屬性：

與 BigQuery 資料集中的資源和資源資料表同名。舉例來說，當您串流 Patient 資源時，系統會建立名為 Patient 的資料表，以及名為 Patientview 的檢視區塊。
其中只包含資源的目前版本，而非所有歷史版本。

將 FHIR 資源串流至分區資料表

如要將 FHIR 資源匯出至 BigQuery 分區資料表，請在 FHIR 儲存庫的 lastUpdatedPartitionConfig 欄位中設定 TimePartitioning 列舉。

分區資料表運作方式與 BigQuery 時間單位分區資料表類似。分區資料表會新增名為 lastUpdated 的資料欄，這是從 FHIR 資源的 meta.lastUpdated 欄位產生的 meta.lastUpdated 資料欄副本。BigQuery 會使用 lastUpdated 資料欄，依小時、天、月或年將資料表分區。

如需如何選取分區細微程度的建議，請參閱「選取每日、每小時、每月或每年分區」。

您無法將現有的非分區 BigQuery 資料表轉換為分區資料表。如果將 Patient 資源變更匯出至非分區 Patients 資料表，然後建立新的 FHIR 儲存庫 (含資料表分區)，並匯出至相同的 BigQuery 資料集，Cloud Healthcare API 仍會將資料匯出至非分區 Patients 資料表。如要開始使用已分割的資料表，請刪除現有的 Patients 資料表，或使用其他 BigQuery 資料集。

如果您在現有的 FHIR 存放區設定中新增分區，仍可匯出至現有的非分區資料表。不過，分區功能只會對新資料表生效。

下列範例說明如何為現有 FHIR 存放區的已分割資料表啟用 BigQuery 串流。

控制台

Google Cloud 控制台和 gcloud CLI 不支援這項操作。請改用 curl、PowerShell 或偏好語言。

gcloud

Google Cloud 控制台和 gcloud CLI 不支援這項操作。請改用 curl、PowerShell 或偏好語言。

REST

如要設定 BigQuery 串流，將資料傳入現有 FHIR 儲存庫的分區資料表，請使用 projects.locations.datasets.fhirStores.patch 方法。

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

PROJECT_ID：您的 Google Cloud 專案 ID
LOCATION：資料集位置
DATASET_ID：FHIR 儲存庫的父項資料集
FHIR_STORE_ID：FHIR 儲存庫 ID
BIGQUERY_DATASET_ID：現有 BigQuery 資料集的名稱，您要將 FHIR 資源變更串流至該資料集
SCHEMA_TYPE：SchemaType 列舉的值。請使用下列其中一個值：
- ANALYTICS. 以 FHIR 的 SQL 文件為基礎的結構定義。由於 BigQuery 每張資料表最多只能有 10,000 個資料欄，因此系統不會為 Parameters.parameter.resource、Bundle.entry.resource 和 Bundle.entry.response.outcome 欄位產生結構定義。
- ANALYTICS_V2。類似於 ANALYTICS 的架構，但新增了下列項目的支援：
  - 擴充功能的同一個 url 有多個值
  - 內含 FHIR 資源
  ANALYTICS_V2 在目的地資料表使用的空間比 ANALYTICS 多
  。
TIME_PARTITION_TYPE：分割匯出 FHIR 資源的精細程度。請使用下列其中一個值：
- HOUR：按小時分區資料
- DAY：按天分區資料
- MONTH：按月分區資料
- YEAR：按年份劃分資料
WRITE_DISPOSITION：WriteDisposition 列舉的值。請使用下列其中一個值：
- WRITE_EMPTY。只在目的地 BigQuery 資料表空白時匯出資料。
- WRITE_TRUNCATE。在寫入 FHIR 資源前，清除 BigQuery 資料表中的所有現有資料。
- WRITE_APPEND. 將資料附加至目的地 BigQuery 資料表。

JSON 要求主體：

{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

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

curl

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

cat > request.json << 'EOF'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
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=streamConfigs"

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

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

@'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
'@  | 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=streamConfigs" | Select-Object -Expand Content

APIs Explorer

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

回應

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "FHIR_STORE_VERSION",
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

查詢分區資料表

如要減少查詢分區資料表時的查詢費用，請使用 WHERE 子句依時間單位篩選。

舉例來說，假設您將 PartitionType 列舉設為 DAY。如要查詢 Patients 資料表，找出特定日期變更的 Patient 資源，請執行下列查詢：

SELECT * FROM `PROJECT_ID.BIGQUERY_DATASET.Patients`
  WHERE DATE(lastUpdated) = 'YYYY-MM-DD'

從 Analytics 遷移至 Analytics 第 2 版

您無法使用任何方法 (包括下列方法)，將現有的 BigQuery 資料集從 Analytics 架構遷移至 Analytics V2 架構：

變更 BigQuery 中資料表的結構定義類型。
變更現有 FHIR 串流設定中的結構定義類型。

這是因為 Analytics 結構定義中 FHIR 擴充功能的 BigQuery 資料表資料欄模式設為 NULLABLE，而 Analytics V2 結構定義中的模式則設為 REPEATED。BigQuery 不允許將資料欄的模式從 NULLABLE 變更為 REPEATED。因此這兩種結構定義類型不相容。

如要將匯出的 FHIR 資源結構定義類型從 Analytics 遷移至 Analytics V2，您必須使用更新後的結構定義類型，透過新的串流設定將 FHIR 資源匯出至新的 BigQuery 資料集。如要這麼做，請按照下列步驟操作：

建立新的 BigQuery 資料集。
設定 BigQuery 資料集的權限。
在 FHIR 儲存庫中新增串流設定，並將結構定義類型設為 Analytics V2。
使用下列設定匯出現有 FHIR 資料，回填現有資料。如要瞭解如何使用 Google Cloud 控制台、Google Cloud CLI 或 REST API 設定這些選項，請參閱匯出 FHIR 資源。下列設定適用於 REST API：
- 將 WriteDisposition 設為 WRITE_APPEND，將資料附加至目的地資料表。
- 將 SchemaType 設為 ANALYTICS_V2。

新資料集可能缺少 BigQuery 中的檢視表，這些檢視表對應於原始 BigQuery 資料集中的部分或所有 FHIR 資源。如要排解這個問題，請參閱「缺少 FHIR 資源檢視畫面建立作業」。

排解 FHIR 串流問題

如果將資源變更傳送至 BigQuery 時發生錯誤，系統會將錯誤記錄至 Cloud Logging。詳情請參閱「查看 Cloud Logging 中的錯誤記錄檔」。

無法將資料欄從 NULLABLE 轉換為 REPEATED

這個錯誤是由重複的擴充功能所造成。如要解決這項錯誤，請使用 ANALYTICS_V2 結構化資料類型。如果您已使用 ANALYTICS_V2，可能會有兩個擴充功能發生衝突，或是擴充功能與其他欄位發生衝突。

系統會根據擴充網址中最後一個 / 字元後的文字產生資料欄名稱。如果擴充網址以 /resource_field name 等值結尾，可能會發生衝突。

為避免再次發生這項錯誤，請勿使用欄位名稱與您填入的資源欄位相同的擴充功能。

缺少 FHIR 資源檢視畫面建立作業

如果您在串流 FHIR 資源前大量匯出 FHIR 資源至 BigQuery，BigQuery 就不會為該 FHIR 資源建立檢視區塊。

舉例來說，在下列情況中，您可能不會看到 Encounter 資源的任何檢視畫面：

您可以在 FHIR 儲存區設定 BigQuery 串流，然後使用 REST API 建立 Patient 資源。

BigQuery 會為 Patient 資源建立資料表和檢視區塊。
將大量「就診」資源匯出至與上一個步驟相同的 BigQuery 資料集。

BigQuery 會為 Encounter 資源建立資料表。
您可以使用 REST API 建立 Encounter 資源。

完成這個步驟後，系統不會為 Encounter 資源建立 BigQuery 檢視區塊。

如要解決這個問題，請使用下列查詢建立檢視區塊：

SELECT
    * EXCEPT (_resource_row_id)
FROM (
  SELECT
    ROW_NUMBER() OVER(PARTITION BY id ORDER BY meta.lastUpdated DESC, commitTimestamp DESC) as _resource_row_id,
    *
    FROM `PROJECT_ID.BIGQUERY_DATASET_ID.RESOURCE_TABLE` AS p
) AS p
WHERE
  p._resource_row_id=1
  AND
  NOT EXISTS (
  SELECT
    *
  FROM
    UNNEST(p.meta.tag)
  WHERE
    code = 'DELETE');

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID
BIGQUERY_DATASET_ID：您大量匯出 FHIR 資源的 BigQuery 資料集 ID
RESOURCE_TABLE：與要建立檢視區塊的 FHIR 資源對應的資料表名稱

建立檢視後，您可以繼續將變更串流至 FHIR 資源，系統會相應更新檢視。

後續步驟

如需串流 FHIR 資源變更的用途教學課程，請參閱「透過 BigQuery 串流及同步處理 FHIR 資源」。

將 FHIR 資源變更串流至 BigQuery 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

限制

設定 BigQuery 權限

在 FHIR 儲存庫上設定 BigQuery 串流

控制台

gcloud

REST

curl

PowerShell

APIs Explorer

回應

將 FHIR 資源串流至分區資料表

控制台

gcloud

REST

curl

PowerShell

APIs Explorer

回應

查詢分區資料表

從 Analytics 遷移至 Analytics 第 2 版

排解 FHIR 串流問題

無法將資料欄從 NULLABLE 轉換為 REPEATED

缺少 FHIR 資源檢視畫面建立作業

後續步驟

將 FHIR 資源變更串流至 BigQuery