將 DICOM 中繼資料匯出至 BigQuery

本頁面說明如何將 DICOM 中繼資料匯出至 BigQuery，以便探索及分析。如要瞭解匯出 DICOM 中繼資料時建立的 BigQuery 結構定義，請參閱「瞭解 BigQuery DICOM 結構定義」。

設定 BigQuery 權限

匯出 DICOM 中繼資料至 BigQuery 資料表前，您必須將額外權限授予 Cloud Healthcare Service Agent 服務帳戶。詳情請參閱「DICOM 儲存庫 BigQuery 權限」。

設定 BigQuery 目的地

設定 BigQuery 目的地時，請使用完整的 URI，如下所示：
bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID
匯出作業的行為可能會因下列因素而異：
  • 目的地資料表是否已存在
  • 您是否已設定 force 欄位 (使用 API) 或 --overwrite-table 標記 (使用 Google Cloud CLI)
  • 您是否已為 writeDisposition 列舉設定值。如果您使用 writeDisposition 列舉，請勿設定 force 欄位。
在上述每種情況中，行為如下：
  • 如果目的地資料表已存在，且 force 設為 true 或指定 --overwrite-table 旗標，匯出作業就會覆寫現有資料表。
  • 如果目的地資料表已存在，且 force 設為 false，或是未指定 --overwrite-table 標記，就會發生錯誤。
  • 無論您指定 force 欄位或 --overwrite-table 標記，如果目標資料表不存在，系統都會建立新資料表。
  • 說明文件會說明 writeDisposition 的行為。writeDisposition 列舉的執行行為與使用 force 時的選項類似，但有以下例外狀況：如果目的地資料表已存在且為空白，匯出作業會完成，而不會傳回錯誤。

匯出 DICOM 中繼資料

以下範例說明如何將 DICOM 中繼資料匯出至 BigQuery 資料表。在這些範例中，DICOM 儲存空間和 BigQuery 資料表位於同一個專案中。如要將 DICOM 中繼資料匯出至另一個專案中的 BigQuery 資料表，請參閱「將 DICOM 中繼資料匯出至其他專案」。

控制台

如要將 DICOM 中繼資料匯出至 BigQuery 資料表，請完成下列步驟：

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

    前往「資料集」

  2. 按一下含有您要匯出中繼資料的 DICOM 存放區資料集。

  3. 在 DICOM 儲存庫所在的資料列中，開啟「Actions」清單，然後選取「Export」。

  4. 在隨即顯示的「Export DICOM store」(匯出 DICOM 儲存庫) 頁面中，選取「BigQuery table」(BigQuery 資料表)。

  5. 在「Project」欄位中，按一下「Browse」，然後選取專案。

  6. 在「資料集」清單中，選取要匯出 DICOM 中繼資料的 BigQuery 資料集。

  7. 在「Table」欄位中，輸入新表格的名稱。BigQuery 會檢查每個選項，確保目的地資料表有效。

  8. 在「Destination table write disposition」(目標資料表寫入配置) 部分，選取下列其中一個選項。這些選項對應至 WriteDisposition 列舉。

    • 只在目的地資料表空白時匯出資料：等同於 WRITE_EMPTY
    • 將資料附加至目的地資料表：等同於 WRITE_APPEND
    • 在寫入執行個體前清除目的地資料表中的所有現有資料：等同於 WRITE_TRUNCATE。

  9. 按一下「Export」，將 DICOM 中繼資料匯出至 BigQuery 資料表。

  10. 如要追蹤作業狀態，請按一下「Operations」分頁。作業完成後，系統會顯示下列指示：
    • 「長時間執行的作業狀態」部分的「OK」標題下方有綠色勾號。
    • 「總覽」部分會顯示綠色勾號和「OK」指標，與作業 ID 位於同一行。
    如果發生任何錯誤，請按一下「Actions」，然後點選「View details in Cloud Logging」。

gcloud

如要將 DICOM 中繼資料匯出至 BigQuery 資料表，請執行 gcloud healthcare dicom-stores export bq 指令。

  1. 匯出 DICOM 中繼資料。

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

    • PROJECT_ID： Google Cloud 專案的 ID
    • LOCATION：資料集位置
    • DATASET_ID：DICOM 儲存庫的父資料集
    • DICOM_STORE_ID：DICOM 儲存庫 ID
    • BIGQUERY_DATASET_ID：匯出 DICOM 中繼資料的現有 BigQuery 資料集名稱
    • BIGQUERY_TABLE_ID：BigQuery 資料集中新建或現有的資料表名稱。如果匯出作業是建立新資料表，請參閱「資料表命名」一文，瞭解資料表名稱規定。
    • WRITE_DISPOSITION：WriteDisposition 列舉的值。請使用下列其中一個值：
      • write-empty：僅在 BigQuery 資料表為空白時匯出資料。
      • write-truncate：在寫入 DICOM 例項前，清除 BigQuery 資料表中的所有現有資料。
      • write-append：將資料附加至 BigQuery 資料表。

    執行下列指令：

    Linux、macOS 或 Cloud Shell

    gcloud healthcare dicom-stores export bq DICOM_STORE_ID \
  --location=LOCATION \
  --dataset=DATASET_ID \
  --bq-table=bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID \
  --write-disposition=WRITE_DISPOSITION

    Windows (PowerShell)

    gcloud healthcare dicom-stores export bq DICOM_STORE_ID `
  --location=LOCATION `
  --dataset=DATASET_ID `
  --bq-table=bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID `
  --write-disposition=WRITE_DISPOSITION

    Windows (cmd.exe)

    gcloud healthcare dicom-stores export bq DICOM_STORE_ID ^
  --location=LOCATION ^
  --dataset=DATASET_ID ^
  --bq-table=bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID ^
  --write-disposition=WRITE_DISPOSITION
         回應如下：回應會包含長時間執行作業的 ID。如果方法呼叫可能需要大量時間才能完成，系統就會傳回長時間執行的作業。這個指令會輪詢長期執行作業，然後在匯出作業完成後，在 name 欄位中列印作業名稱。請記下 OPERATION_ID 的值。您需要在下一個步驟中使用這個值。

    回應

    Request issued for: [DICOM_STORE_ID]
Waiting for operation [projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID] to complete...⠏
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID

  2. 如要查看作業的更多詳細資料，請執行 gcloud healthcare operations describe 指令，並提供回應中的 OPERATION_ID：

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

    • PROJECT_ID： Google Cloud 專案的 ID
    • DATASET_ID：資料集 ID
    • LOCATION：資料集位置
    • OPERATION_ID：長時間執行作業傳回的 ID

    執行下列指令：

    Linux、macOS 或 Cloud Shell

    gcloud healthcare operations describe OPERATION_ID \
    --project=PROJECT_ID \
    --dataset=DATASET_ID \
    --location=LOCATION

    Windows (PowerShell)

    gcloud healthcare operations describe OPERATION_ID `
    --project=PROJECT_ID `
    --dataset=DATASET_ID `
    --location=LOCATION

    Windows (cmd.exe)

    gcloud healthcare operations describe OPERATION_ID ^
    --project=PROJECT_ID ^
    --dataset=DATASET_ID ^
    --location=LOCATION

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

    回應

    done: true
// If there were any errors, an `error` field displays instead of a `response` field.
// See Troubleshooting long-running operations for a list of response codes.
error: ERROR
  code: ERROR_CODE
  message: DESCRIPTION
metadata:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata'
  apiMethodName: 'google.cloud.healthcare.v1.dicom.DicomService.ExportDicomData_bq'
  counter:
    success: 'SUCCESS_COUNT'
    // If there were any failures, they display in the `failure` field.
    failure: 'FAILURE_COUNT'
  createTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  endTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  logsUrl: https://console.cloud.google.com/CLOUD_LOGGING_URL
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID
// The `response` field only displays if there were no errors.
response:
  '@type': 'type.googleapis.com/google.protobuf.Empty'

REST

如要將 DICOM 中繼資料匯出至 BigQuery 資料表，請使用 projects.locations.datasets.dicomStores.export 方法。

  1. 匯出 DICOM 中繼資料。

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

    • PROJECT_ID： Google Cloud 專案的 ID
    • LOCATION：資料集位置
    • DATASET_ID：DICOM 儲存庫的父資料集
    • DICOM_STORE_ID：DICOM 儲存庫 ID
    • BIGQUERY_DATASET_ID：匯出 DICOM 中繼資料的現有 BigQuery 資料集名稱
    • BIGQUERY_TABLE_ID：BigQuery 資料集中新建或現有的資料表名稱。如果匯出作業是建立新資料表，請參閱「資料表命名」一文，瞭解資料表名稱規定。
    • WRITE_DISPOSITION：WriteDisposition 列舉的值。請使用下列其中一個值：
      • WRITE_EMPTY：僅在 BigQuery 資料表為空白時匯出資料。
      • WRITE_TRUNCATE：在寫入 DICOM 例項前，清除 BigQuery 資料表中的所有現有資料。
      • WRITE_APPEND：將資料附加至 BigQuery 資料表。

    JSON 要求主體：

    {
  "bigqueryDestination": {
      "tableUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID",
      "writeDisposition": "WRITE_DISPOSITION"
  }
}

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

    curl

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

    cat > request.json << 'EOF'
{
  "bigqueryDestination": {
      "tableUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID",
      "writeDisposition": "WRITE_DISPOSITION"
  }
}
EOF

    接著，執行下列指令來傳送 REST 要求： 

    curl -X POST \
         -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:export"

    PowerShell

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

    @'
{
  "bigqueryDestination": {
      "tableUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID",
      "writeDisposition": "WRITE_DISPOSITION"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

    接著，執行下列指令來傳送 REST 要求： 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -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:export" | Select-Object -Expand Content

    APIs Explorer

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

    輸出內容如下。回應會包含長時間執行作業 (LRO) 的 ID。如果方法呼叫可能需要額外時間才能完成，系統就會傳回長時間執行的作業。請記下 OPERATION_ID 的值。您需要在下一個步驟中使用這個值。

  2. 使用 projects.locations.datasets.operations.get 方法取得長時間執行作業的狀態。

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

    • PROJECT_ID： Google Cloud 專案的 ID
    • DATASET_ID：資料集 ID
    • LOCATION：資料集位置
    • OPERATION_ID：長時間執行作業傳回的 ID

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

    curl

    執行下列指令：

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

    PowerShell

    執行下列指令：

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

    APIs Explorer

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

    輸出內容如下。如果回應包含 "done": true，表示長時間執行作業已完成。

將 DICOM 中繼資料匯出至其他專案

如要將 DICOM 中繼資料從一個專案的 DICOM 儲存庫匯出至另一個專案的 BigQuery 資料集，請先參閱「將 DICOM 中繼資料匯出至其他專案的權限」，瞭解如何在目的專案中設定 IAM 權限。

gcloud

如要將 DICOM 中繼資料從一個專案的 DICOM 儲存庫匯出至另一個專案的 BigQuery 資料表，請使用 gcloud healthcare dicom-stores export bq 指令。

  1. 匯出 DICOM 中繼資料。

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

    • SOURCE_PROJECT_ID：來源 Google Cloud 專案的 ID
    • SOURCE_LOCATION：來源資料集位置
    • SOURCE_DATASET_ID：來源 DICOM 儲存庫的父資料集
    • SOURCE_DICOM_STORE_ID：來源 DICOM 儲存庫 ID
    • DESTINATION_PROJECT_ID：不同專案的 ID
    • DESTINATION_BIGQUERY_DATASET_ID：匯出 DICOM 中繼資料的目標專案中現有 BigQuery 資料集的名稱
    • DESTINATION_BIGQUERY_TABLE_ID：BigQuery 資料集中新建或現有的資料表名稱。如果匯出作業是建立新資料表，請參閱「資料表命名」一文，瞭解資料表名稱規定。
    • WRITE_DISPOSITION：WriteDisposition 列舉的值。請使用下列其中一個值：
      • write-empty：僅在 BigQuery 資料表為空白時匯出資料。
      • write-truncate：在寫入 DICOM 例項前，清除 BigQuery 資料表中的所有現有資料。
      • write-append：將資料附加至 BigQuery 資料表。

    執行下列指令：

    Linux、macOS 或 Cloud Shell

    gcloud healthcare dicom-stores export bq SOURCE_DICOM_STORE_ID \
  --project=SOURCE_PROJECT_ID \
  --location=SOURCE_LOCATION \
  --dataset=SOURCE_DATASET_ID \
  --bq-table=bq://DESTINATION_PROJECT_ID.DESTINATION_BIGQUERY_DATASET_ID.DESTINATION_BIGQUERY_TABLE_ID \
  --write-disposition=WRITE_DISPOSITION

    Windows (PowerShell)

    gcloud healthcare dicom-stores export bq SOURCE_DICOM_STORE_ID `
  --project=SOURCE_PROJECT_ID `
  --location=SOURCE_LOCATION `
  --dataset=SOURCE_DATASET_ID `
  --bq-table=bq://DESTINATION_PROJECT_ID.DESTINATION_BIGQUERY_DATASET_ID.DESTINATION_BIGQUERY_TABLE_ID `
  --write-disposition=WRITE_DISPOSITION

    Windows (cmd.exe)

    gcloud healthcare dicom-stores export bq SOURCE_DICOM_STORE_ID ^
  --project=SOURCE_PROJECT_ID ^
  --location=SOURCE_LOCATION ^
  --dataset=SOURCE_DATASET_ID ^
  --bq-table=bq://DESTINATION_PROJECT_ID.DESTINATION_BIGQUERY_DATASET_ID.DESTINATION_BIGQUERY_TABLE_ID ^
  --write-disposition=WRITE_DISPOSITION
         回應如下：回應會包含長時間執行作業的 ID。如果方法呼叫可能需要大量時間才能完成，系統就會傳回長時間執行的作業。這個指令會輪詢長期執行作業，然後在匯出作業完成後，在 name 欄位中列印作業名稱。請記下 OPERATION_ID 的值。您需要在下一個步驟中使用這個值。

    回應

    Request issued for: [SOURCE_DICOM_STORE_ID]
Waiting for operation [projects/SOURCE_PROJECT_ID/locations/SOURCE_LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID] to complete...⠏
name: projects/SOURCE_PROJECT_ID/locations/SOURCE_LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID

  2. 如要查看作業的更多詳細資料，請執行 gcloud healthcare operations describe 指令，並提供回應中的 OPERATION_ID：

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

    • SOURCE_PROJECT_ID：來源 Google Cloud 專案的 ID
    • SOURCE_LOCATION：來源資料集位置
    • SOURCE_DATASET_ID：來源資料集 ID
    • OPERATION_ID：長時間執行作業傳回的 ID

    執行下列指令：

    Linux、macOS 或 Cloud Shell

    gcloud healthcare operations describe OPERATION_ID \
    --project=SOURCE_PROJECT_ID \
    --dataset=SOURCE_DATASET_ID \
    --location=SOURCE_LOCATION

    Windows (PowerShell)

    gcloud healthcare operations describe OPERATION_ID `
    --project=SOURCE_PROJECT_ID `
    --dataset=SOURCE_DATASET_ID `
    --location=SOURCE_LOCATION

    Windows (cmd.exe)

    gcloud healthcare operations describe OPERATION_ID ^
    --project=SOURCE_PROJECT_ID ^
    --dataset=SOURCE_DATASET_ID ^
    --location=SOURCE_LOCATION

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

    回應

    done: true
// If there were any errors, an `error` field displays instead of a `response` field.
// See Troubleshooting long-running operations for a list of response codes.
error: ERROR
  code: ERROR_CODE
  message: DESCRIPTION
metadata:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata'
  apiMethodName: 'google.cloud.healthcare.v1.dicom.DicomService.ExportDicomData_bq'
  counter:
    success: 'SUCCESS_COUNT'
    // If there were any failures, they display in the `failure` field.
    failure: 'FAILURE_COUNT'
  createTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  endTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  logsUrl: https://console.cloud.google.com/CLOUD_LOGGING_URL
name: projects/SOURCE_PROJECT_ID/locations/SOURCE_LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID
// The `response` field only displays if there were no errors.
response:
  '@type': 'type.googleapis.com/google.protobuf.Empty'

REST

如要將 DICOM 中繼資料從一個專案的 DICOM 儲存庫匯出至另一個專案的 BigQuery 資料表，請使用 projects.locations.datasets.dicomStores.export 方法。

  1. 匯出 DICOM 中繼資料。

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

    • SOURCE_PROJECT_ID：來源 Google Cloud 專案的 ID
    • SOURCE_LOCATION：來源資料集位置
    • SOURCE_DATASET_ID：來源 DICOM 儲存庫的父資料集
    • SOURCE_DICOM_STORE_ID：來源 DICOM 儲存庫 ID
    • DESTINATION_PROJECT_ID：不同專案的 ID
    • DESTINATION_BIGQUERY_DATASET_ID：匯出 DICOM 中繼資料的目標專案中現有 BigQuery 資料集的名稱
    • DESTINATION_BIGQUERY_TABLE_ID：BigQuery 資料集中新建或現有的資料表名稱。如果匯出作業是建立新資料表，請參閱「資料表命名」一文，瞭解資料表名稱規定。
    • WRITE_DISPOSITION：WriteDisposition 列舉的值。請使用下列其中一個值：
      • WRITE_EMPTY：僅在 BigQuery 資料表為空白時匯出資料。
      • WRITE_TRUNCATE：在寫入 DICOM 例項前，清除 BigQuery 資料表中的所有現有資料。
      • WRITE_APPEND：將資料附加至 BigQuery 資料表。

    JSON 要求主體：

    {
  "bigqueryDestination": {
      "tableUri": "bq://DESTINATION_PROJECT_ID.DESTINATION_BIGQUERY_DATASET_ID.DESTINATION_BIGQUERY_TABLE_ID",
      "writeDisposition": "WRITE_DISPOSITION"
  }
}

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

    curl

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

    cat > request.json << 'EOF'
{
  "bigqueryDestination": {
      "tableUri": "bq://DESTINATION_PROJECT_ID.DESTINATION_BIGQUERY_DATASET_ID.DESTINATION_BIGQUERY_TABLE_ID",
      "writeDisposition": "WRITE_DISPOSITION"
  }
}
EOF

    接著，執行下列指令來傳送 REST 要求： 

    curl -X POST \
         -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/SOURCE_PROJECT_ID/locations/SOURCE_LOCATION/datasets/SOURCE_DATASET_ID/dicomStores/SOURCE_DICOM_STORE_ID:export"

    PowerShell

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

    @'
{
  "bigqueryDestination": {
      "tableUri": "bq://DESTINATION_PROJECT_ID.DESTINATION_BIGQUERY_DATASET_ID.DESTINATION_BIGQUERY_TABLE_ID",
      "writeDisposition": "WRITE_DISPOSITION"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

    接著，執行下列指令來傳送 REST 要求： 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://healthcare.googleapis.com/v1/projects/SOURCE_PROJECT_ID/locations/SOURCE_LOCATION/datasets/SOURCE_DATASET_ID/dicomStores/SOURCE_DICOM_STORE_ID:export" | Select-Object -Expand Content

    APIs Explorer

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

    輸出內容如下。回應會包含長時間執行作業 (LRO) 的 ID。如果方法呼叫可能需要額外時間才能完成，系統就會傳回長時間執行的作業。請記下 OPERATION_ID 的值。您需要在下一個步驟中使用這個值。

  2. 使用 projects.locations.datasets.operations.get 方法取得長時間執行作業的狀態。

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

    • SOURCE_PROJECT_ID：來源 Google Cloud 專案的 ID
    • SOURCE_LOCATION：來源資料集位置
    • SOURCE_DATASET_ID：來源資料集 ID
    • OPERATION_ID：長時間執行作業傳回的 ID

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

    curl

    執行下列指令：

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://healthcare.googleapis.com/v1/projects/SOURCE_PROJECT_ID/locations/SOURCE_LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID"

    PowerShell

    執行下列指令：

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://healthcare.googleapis.com/v1/projects/SOURCE_PROJECT_ID/locations/SOURCE_LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

    APIs Explorer

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

    輸出內容如下。如果回應包含 "done": true，表示長時間執行作業已完成。

使用篩選器匯出 DICOM 中繼資料

根據預設，當您將 DICOM 檔案匯出至 Cloud Storage 時，系統會匯出指定 DICOM 儲存庫中的所有 DICOM 檔案。同樣地，當您將 DICOM 中繼資料匯出至 BigQuery 時，系統會匯出指定 DICOM 存放區中所有 DICOM 資料的中繼資料。

您可以使用篩選器匯出 DICOM 資料或中繼資料的子集。您可以在篩選器檔案中定義篩選器。

設定篩選器檔案

篩選器檔案會定義要匯出至 Cloud Storage 或 BigQuery 的 DICOM 檔案。您可以在下列層級設定篩選器檔案：

  • 在研究層級
  • 在系列叢書層級
  • 在執行個體層級

篩選器檔案由多行組成，每行定義要匯出的試驗、系列或例項。每行都使用 /studies/STUDY_UID[/series/SERIES_UID[/instances/INSTANCE_UID]] 格式。

如果您在傳入篩選器檔案時未在篩選器檔案中指定研究、系列或例項，系統就不會匯出該研究、系列或例項。

只需要路徑的 /studies/STUDY_UID 部分。您可以指定 /studies/STUDY_UID 匯出整個研究，也可以指定 /studies/STUDY_UID/series/SERIES_UID 匯出整個系列。

請參考下列篩選器檔案。篩選器檔案會匯出一個研究、兩個系列和三個個別例項：

/studies/1.123.456.789
/studies/1.666.333.111/series/123.456
/studies/1.666.333.111/series/567.890
/studies/1.888.999.222/series/123.456/instances/111
/studies/1.888.999.222/series/123.456/instances/222
/studies/1.888.999.222/series/123.456/instances/333

使用 BigQuery 建立篩選器檔案

建立篩選器檔案時，通常會先將中繼資料從 DICOM 儲存庫匯出至 BigQuery。這樣一來，您就能使用 BigQuery 查看 DICOM 儲存庫中 DICOM 資料的研究、系列和執行個體 UID。接著，請完成下列步驟：

  1. 查詢您感興趣的研究、系列和執行個體 UID。舉例來說，將 DICOM 中繼資料匯出至 BigQuery 後，您可以執行下列查詢，將研究、系列和例項 UID 連結至符合篩選器檔案需求的格式：
    SELECT CONCAT
    ('/studies/', StudyInstanceUID, '/series/', SeriesInstanceUID, '/instances/', SOPInstanceUID)
FROM
    [PROJECT_ID:BIGQUERY_DATASET.BIGQUERY_TABLE]
  2. 如果查詢傳回的結果集很大，您可以將查詢結果儲存至 BigQuery 中的目的地資料表，藉此具現新的資料表。
  3. 如果您將查詢結果儲存到目的地資料表，可以將目的地資料表的內容儲存到檔案，然後匯出至 Cloud Storage。如要瞭解相關步驟，請參閱「匯出資料表資料」一文。匯出的檔案就是您的篩選器檔案。在匯出作業中指定篩選器時，請使用 Cloud Storage 中的篩選器檔案位置。

手動建立篩選器檔案

您可以建立含有自訂內容的篩選器檔案，然後上傳至 Cloud Storage 值區。在匯出作業中指定篩選條件時，您會使用 Cloud Storage 中的篩選器檔案位置。下列範例說明如何使用 gcloud storage cp 指令，將篩選器檔案上傳至 Cloud Storage 值區：
gcloud storage cp FILTER_FILE gs://BUCKET

傳入篩選器檔案

建立篩選器檔案後，您可以呼叫 DICOM 匯出作業，並使用 REST API 傳入篩選器檔案。以下範例說明如何使用篩選器匯出 DICOM 中繼資料。

gcloud

如要使用篩選器將 DICOM 中繼資料匯出至 BigQuery 資料表，請執行 gcloud beta healthcare dicom-stores export bq 指令。

  1. 匯出 DICOM 中繼資料。

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

    • PROJECT_ID： Google Cloud 專案的 ID
    • LOCATION：資料集位置
    • DATASET_ID：DICOM 儲存庫的父資料集
    • DICOM_STORE_ID：DICOM 儲存庫 ID
    • BIGQUERY_DATASET_ID：匯出 DICOM 中繼資料的現有 BigQuery 資料集名稱
    • BIGQUERY_TABLE_ID：BigQuery 資料集中新建或現有的資料表名稱。如果匯出作業是建立新資料表，請參閱「資料表命名」一文，瞭解資料表名稱規定。
    • BUCKET：含有篩選器檔案的 Cloud Storage 值區名稱。如果篩選器檔案位於目錄中，請在路徑中加入該目錄。
    • FILTER_FILE：Cloud Storage 值區中篩選器檔案的位置和名稱
    • WRITE_DISPOSITION：WriteDisposition 列舉的值。請使用下列其中一個值：
      • write-empty：僅在 BigQuery 資料表為空白時匯出資料。
      • write-truncate：在寫入 DICOM 例項前，清除 BigQuery 資料表中的所有現有資料。
      • write-append：將資料附加至 BigQuery 資料表。

    執行下列指令：

    Linux、macOS 或 Cloud Shell

    gcloud beta healthcare dicom-stores export bq DICOM_STORE_ID \
  --location=LOCATION \
  --dataset=DATASET_ID \
  --bq-table=bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID \
  --filter-config-gcs-uri=gs://BUCKET/FILTER_FILE \
  --write-disposition=WRITE_DISPOSITION

    Windows (PowerShell)

    gcloud beta healthcare dicom-stores export bq DICOM_STORE_ID `
  --location=LOCATION `
  --dataset=DATASET_ID `
  --bq-table=bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID `
  --filter-config-gcs-uri=gs://BUCKET/FILTER_FILE `
  --write-disposition=WRITE_DISPOSITION

    Windows (cmd.exe)

    gcloud beta healthcare dicom-stores export bq DICOM_STORE_ID ^
  --location=LOCATION ^
  --dataset=DATASET_ID ^
  --bq-table=bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID ^
  --filter-config-gcs-uri=gs://BUCKET/FILTER_FILE ^
  --write-disposition=WRITE_DISPOSITION
         回應如下：回應會包含長時間執行作業的 ID。如果方法呼叫可能需要大量時間才能完成，系統就會傳回長時間執行的作業。這個指令會輪詢長期執行作業，然後在匯出作業完成後，在 name 欄位中列印作業名稱。請記下 OPERATION_ID 的值。您需要在下一個步驟中使用這個值。

    回應

    Request issued for: [DICOM_STORE_ID]
Waiting for operation [projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID] to complete...⠏
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID

  2. 如要查看作業的更多詳細資料，請執行 gcloud healthcare operations describe 指令，並提供回應中的 OPERATION_ID：

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

    • PROJECT_ID： Google Cloud 專案的 ID
    • DATASET_ID：資料集 ID
    • LOCATION：資料集位置
    • OPERATION_ID：長時間執行作業傳回的 ID

    執行下列指令：

    Linux、macOS 或 Cloud Shell

    gcloud healthcare operations describe OPERATION_ID \
    --project=PROJECT_ID \
    --dataset=DATASET_ID \
    --location=LOCATION

    Windows (PowerShell)

    gcloud healthcare operations describe OPERATION_ID `
    --project=PROJECT_ID `
    --dataset=DATASET_ID `
    --location=LOCATION

    Windows (cmd.exe)

    gcloud healthcare operations describe OPERATION_ID ^
    --project=PROJECT_ID ^
    --dataset=DATASET_ID ^
    --location=LOCATION

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

    回應

    done: true
// If there were any errors, an `error` field displays instead of a `response` field.
// See Troubleshooting long-running operations for a list of response codes.
error: ERROR
  code: ERROR_CODE
  message: DESCRIPTION
metadata:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata'
  apiMethodName: 'google.cloud.healthcare.v1.dicom.DicomService.ExportDicomData_bq'
  counter:
    success: 'SUCCESS_COUNT'
    // If there were any failures, they display in the `failure` field.
    failure: 'FAILURE_COUNT'
  createTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  endTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  logsUrl: https://console.cloud.google.com/CLOUD_LOGGING_URL
name: projects/SOURCE_PROJECT_ID/locations/SOURCE_LOCATION/datasets/SOURCE_DATASET_ID/operations/OPERATION_ID
// The `response` field only displays if there were no errors.
response:
  '@type': 'type.googleapis.com/google.protobuf.Empty'

REST

如要使用篩選器將 DICOM 中繼資料匯出至 BigQuery 資料表，請使用 projects.locations.datasets.dicomStores.export 方法。

  1. 匯出 DICOM 中繼資料。

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

    • PROJECT_ID： Google Cloud 專案的 ID
    • LOCATION：資料集位置
    • DATASET_ID：DICOM 儲存庫的父資料集
    • DICOM_STORE_ID：DICOM 儲存庫 ID
    • BIGQUERY_DATASET_ID：匯出 DICOM 中繼資料的現有 BigQuery 資料集名稱
    • BIGQUERY_TABLE_ID：BigQuery 資料集中新建或現有的資料表名稱。如果匯出作業是建立新資料表，請參閱「資料表命名」一文，瞭解資料表名稱規定。
    • BUCKET：含有篩選器檔案的 Cloud Storage 值區名稱。如果篩選器檔案位於目錄中，請在路徑中加入該目錄。
    • FILTER_FILE：Cloud Storage 值區中篩選器檔案的位置和名稱
    • WRITE_DISPOSITION：WriteDisposition 列舉的值。請使用下列其中一個值：
      • WRITE_EMPTY：僅在 BigQuery 資料表為空白時匯出資料。
      • WRITE_TRUNCATE：在寫入 DICOM 例項前，清除 BigQuery 資料表中的所有現有資料。
      • WRITE_APPEND：將資料附加至 BigQuery 資料表。

    JSON 要求主體：

    {
  "bigqueryDestination": {
      "tableUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID",
      "writeDisposition": "WRITE_DISPOSITION"
  },
  "filterConfig": {
      "resourcePathsGcsUri": "gs://BUCKET/FILTER_FILE"
  }
}

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

    curl

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

    cat > request.json << 'EOF'
{
  "bigqueryDestination": {
      "tableUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID",
      "writeDisposition": "WRITE_DISPOSITION"
  },
  "filterConfig": {
      "resourcePathsGcsUri": "gs://BUCKET/FILTER_FILE"
  }
}
EOF

    接著，執行下列指令來傳送 REST 要求： 

    curl -X POST \
         -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:export"

    PowerShell

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

    @'
{
  "bigqueryDestination": {
      "tableUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID",
      "writeDisposition": "WRITE_DISPOSITION"
  },
  "filterConfig": {
      "resourcePathsGcsUri": "gs://BUCKET/FILTER_FILE"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

    接著，執行下列指令來傳送 REST 要求： 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -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:export" | Select-Object -Expand Content

    APIs Explorer

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

    輸出內容如下：回應會包含長時間執行作業 (LRO) 的 ID。如果方法呼叫可能需要額外時間才能完成，系統就會傳回長時間執行的作業。請記下 OPERATION_ID 的值。您需要在下一個步驟中使用這個值。

  2. 使用 projects.locations.datasets.operations.get 方法取得長時間執行作業的狀態。

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

    • PROJECT_ID： Google Cloud 專案的 ID
    • DATASET_ID：資料集 ID
    • LOCATION：資料集位置
    • OPERATION_ID：長時間執行作業傳回的 ID

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

    curl

    執行下列指令：

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

    PowerShell

    執行下列指令：

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

    APIs Explorer

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

    輸出內容如下。如果回應包含 "done": true，表示長時間執行作業已完成。

在 BigQuery 中查詢及分析 DICOM 資料

將 DICOM 中繼資料匯出至 BigQuery 資料表後，您可以執行範例查詢，進一步瞭解中繼資料。以下範例說明如何針對一些常見用途執行查詢。

搜尋中繼資料

假設您想搜尋大量中繼資料，但在其他系統 (例如影像封存與通訊系統 (PACS) 或供應商中立封存系統 (VNA)) 中很難搜尋。以下查詢說明如何查詢病患的 PatientID 值，並使用 DICOMweb 路徑擷取特定影像例項。本範例使用 NIH 胸部 X 光資料集的 chc-nih-chest-xray.nih_chest_xray.nih_chest_xray 資料表。

#standardSQL
SELECT CONCAT('/dicomWeb/studies/', StudyInstanceUID, '/series/', SeriesInstanceUID, '/instances/', SOPInstanceUID) as DICOMwebPath
FROM `chc-nih-chest-xray.nih_chest_xray.nih_chest_xray`
WHERE PatientID = '19045';

查詢會傳回與患者相關的研究。以下回應使用 JSON 格式：

[
  {
    "DICOMwebPath": "/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.169629990647803559688464142879817265366193/series/1.3.6.1.4.1.11129.5.5.141990184899344268273968625887396932057061/instances/1.3.6.1.4.1.11129.5.5.162448513493627342869165322873398445570578"
  },
  {
    "DICOMwebPath": "/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.114160532832901355654444239008681456919023/series/1.3.6.1.4.1.11129.5.5.178361108150351071908200174504411112440700/instances/1.3.6.1.4.1.11129.5.5.145959606905209488520697484018030440952428"
  },
  {
    "DICOMwebPath": "/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.177801331756958922168115732894519725643007/series/1.3.6.1.4.1.11129.5.5.134128639331055702643451404466208677561042/instances/1.3.6.1.4.1.11129.5.5.148534317486838863760908141408862094292875"
  },
  {
    "DICOMwebPath": "/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.119570482687494886334491471870663517807852/series/1.3.6.1.4.1.11129.5.5.148050768676645373034111775531663876425927/instances/1.3.6.1.4.1.11129.5.5.111153708388576066195389700503245704293300"
  },
  {
    "DICOMwebPath": "/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.144704399171290022427247626928443085419319/series/1.3.6.1.4.1.11129.5.5.190285793344339390593165731988543561416633/instances/1.3.6.1.4.1.11129.5.5.110245902713751842026864359179754889505217"
  },
  {
    "DICOMwebPath": "/dicomWeb/studies/1.3.6.1.4.1.11129.5.5.172276126220388966649736649950361623806435/series/1.3.6.1.4.1.11129.5.5.171512371498506519035489729484464872160452/instances/1.3.6.1.4.1.11129.5.5.111721417729733087384317002785068394901165"
  }
]

查詢最新研究

假設您想在 PACS 閱讀工作表中填入資料集的最新研究。

以下查詢顯示如何擷取及顯示最新研究，以及相關執行個體數量和周遭結構化資料。範例使用 TCIA 資料集的 bigquery-public-data.idc_v5.dicom_metadata 資料表。

#standardSQL
SELECT
  MIN(CONCAT(StudyDate, ' ', StudyTime)) as StudyDateTime, MIN(PatientID) as PatientID, StudyInstanceUID, COUNT(*) as InstanceCount
FROM
 `bigquery-public-data.idc_v5.dicom_metadata` AS dicom
GROUP BY StudyInstanceUID
ORDER BY StudyDateTime DESC
LIMIT 10;

查詢會傳回以下資訊：

  • 進入系統的 10 項最新研究，以及這些研究進入系統的時間
  • 與每項研究相關的病患
  • 研究的 UID
  • 與研究相關的例項數量

以下回應使用 JSON 格式：

[
  {
    "StudyDateTime": "2021-07-11 00:38:22",
    "PatientID": "C3L-01924",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2466232160.763753303.1625963902816.3.0",
    "InstanceCount": "4"
  }, {
    "StudyDateTime": "2021-07-10 23:52:10",
    "PatientID": "C3L-01924",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2463459463.1074873794.1625961130119.3.0",
    "InstanceCount": "4"
  }, {
    "StudyDateTime": "2021-07-10 23:31:13",
    "PatientID": "C3L-02513",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2462202516.1453336368.1625959873172.3.0",
    "InstanceCount": "7"
  }, {
    "StudyDateTime": "2021-07-10 23:25:17",
    "PatientID": "C3L-01924",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2461846936.496969835.1625959517592.3.0",
    "InstanceCount": "4"
  }, {
    "StudyDateTime": "2021-07-10 22:35:16",
    "PatientID": "C3L-02515",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2458845347.1905567435.1625956516003.3.0",
    "InstanceCount": "6"
  }, {
    "StudyDateTime": "2021-07-10 21:49:46",
    "PatientID": "C3L-02515",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2456116127.1264613559.1625953786783.3.0",
    "InstanceCount": "7"
  }, {
    "StudyDateTime": "2021-07-10 21:46:04",
    "PatientID": "C3L-02513",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2455894080.1705479047.1625953564736.3.0",
    "InstanceCount": "6"
  }, {
    "StudyDateTime": "2021-07-10 21:13:30",
    "PatientID": "C3L-01924",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2453939652.2052768474.1625951610308.3.0",
    "InstanceCount": "4"
  }, {
    "StudyDateTime": "2021-07-10 21:10:17",
    "PatientID": "C3L-02515",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2453746219.164669562.1625951416875.3.0",
    "InstanceCount": "6"
  }, {
    "StudyDateTime": "2021-07-10 20:05:48",
    "PatientID": "C3L-02513",
    "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.2449877792.1996682667.1625947548448.3.0",
    "InstanceCount": "6"
  }
]

限制和其他行為

如果 DICOM 標記在 BigQuery 中沒有支援的類型 (列於「排除的 VR」)，則會在目的地 BigQuery 資料表中以個別資料欄 (稱為 DroppedTags.TagName) 列出。

排解 DICOM 匯出要求的問題

如果在將 DICOM 中繼資料匯出至 BigQuery 的要求中發生錯誤，系統會將錯誤記錄到 Cloud Logging。詳情請參閱「查看 Cloud Logging 中的錯誤記錄檔」。