Cloud Storage 移轉作業

您可利用 Cloud Storage 專用 BigQuery 資料移轉服務安排週期性資料載入工作,將資料從 Cloud Storage 載入 BigQuery。

事前準備

建立 Cloud Storage 移轉作業之前:

限制

從 Cloud Storage 到 BigQuery 的週期性移轉作業會受到下列限制:

  • 只要移轉的檔案符合由萬用字元或執行階段參數所定義的模式,就必須使用您為目標資料表設定的結構定義,否則移轉作業會失敗。在執行階段之間變更資料表結構定義,也會導致移轉失敗。
  • Cloud Storage 的來源檔案需建立至少一個小時,才能列入移轉範圍。
  • 由於 Cloud Storage 提供物件版本管理功能,請務必注意 BigQuery 移轉作業並不支援已封存的 Cloud Storage 物件。只有未封存的物件才能移轉。
  • 不同於從 Cloud Storage 將資料個別載入到 BigQuery,對於持續進行的移轉作業,您必須在設定移轉前先建立目標資料表及其結構定義。BigQuery 無法在週期性資料移轉流程期間建立資料表。
  • 來自 Cloud Storage 的移轉皆由 WRITE_APPEND 的偏好設定觸發,該偏好設定會將資料附加至目標資料表。詳情請參閱 load 工作設定中的 configuration.load.writeDisposition
  • 如果將資料集的位置設定為 US 以外的值,則單一地區或多地區 Cloud Storage 值區必須與資料集位於相同的地區。

另外,Cloud Storage 來源資料的格式可能會造成其他限制。詳情請參閱:

所需權限

將資料載入 BigQuery 時,您必須具備相關權限才能將資料載入新的或現有的 BigQuery 資料表和分區。如要載入 Cloud Storage 中的資料,您也必須具備資料所屬值區的存取權。請確認您已擁有下列必要權限:

  • BigQuery:需要 bigquery.transfers.update 權限,以建立排定的移轉作業。bigquery.admin 預先定義的 Cloud IAM 角色擁有 bigquery.transfers.update 權限。如要進一步瞭解 BigQuery 中的 Cloud IAM 角色,請參閱存取權控管一文。
  • Cloud Storage:您必須取得個別值區或更高層級的 storage.objects.get 權限。如要使用 URI 萬用字元,您還必須具備 storage.objects.list 權限。如果要在每次成功移轉後刪除來源檔案,您也需要具有 storage.objects.delete 權限。storage.objectAdmin 預先定義的 Cloud IAM 角色具有以上所有權限。

設定 Cloud Storage 移轉作業

如何在 BigQuery 資料移轉服務中建立 Cloud Storage 移轉作業:

主控台

  1. 前往 GCP Console。

    前往 GCP Console

  2. 按一下 [Transfers] (傳輸作業)

  3. 按一下 [Create] (建立)。

  4. 在「Create Transfer」(建立轉移作業) 頁面:

    • 在「Source type」(來源類型) 區段中,針對「Source」(來源),選擇 [Cloud Storage]。

      移轉作業來源

    • 在「Transfer config name」(轉移設定名稱) 區段中,針對「Display name」(顯示名稱) 輸入移轉作業的名稱,例如 My Transfer。移轉作業名稱可以是任何容易辨識的值,方便您日後在必要時進行修改。

      移轉作業名稱

    • 在「Schedule options」(排程選項) 區段中,保留「Schedule」(排程) 的預設值 ([Start now] (立即開始)),或按一下 [Start at a set time] (於設定的時間開始)。

      • 在「Repeats」(重複時間間隔) 部分,選擇多久執行一次移轉作業的選項。
        • Daily (每天) (預設值)
        • Weekly (每週)
        • Monthly (每月)
        • Custom (自訂)
        • 隨選
      • 在「Start date and run time」(開始日期和執行時間) 部分,輸入開始移轉的日期與時間。如果您選擇 [Start now] (立即開始),系統就會停用這個選項。

        移轉作業時間表

    • 在 [Destination settings] (目的地設定) 區段的「Destination dataset」(目標資料集) 中,選擇您為儲存資料而建立的資料集。

      移轉資料集

    • 在「Data source details」(資料來源詳細資料) 區段:

      • 在「Destination table」(目標資料表) 中輸入目標資料表的名稱。 目標資料表必須遵循資料表命名規則。目標資料表名稱也支援參數
      • 在「Cloud Storage URI」部分,輸入 Cloud Storage URI。輸入內容支援使用萬用字元參數
      • 如要在每次成功移轉後刪除來源檔案,請勾選 [Delete source files after transfer] (移轉完成後刪除來源檔案) 的方塊。 系統會在可能的情況下執行刪除工作。如果首次刪除來源檔案失敗,系統並不會重試刪除工作。
      • 在「Transfer Options」(移轉作業選項) 區段中:

        • 在「All Formats」(所有格式) 下方:
          • 在「Number of errors allowed」(允許的錯誤數量) 欄位中,輸入 BigQuery 在執行工作時可忽略的錯誤記錄數量上限。如果錯誤記錄的數量超過這個值,系統就會在工作結果中傳回「invalid」(無效) 錯誤,且該工作會失敗。預設值為 0
        • 在「JSON, CSV」(JSON、CSV) 下方:
          • 如要在移轉時排除不符合目標資料表結構定義的資料,請勾選 [gnore unknown values] (略過不明的值) 的方塊。
        • 在「CSV」 下方:

          • 在「Field delimiter」(欄位分隔符號) 部分輸入分隔欄位的字元。預設值為逗號。
          • 如果您不想匯入來源檔案中的標題列,請在「Header rows to skip」(要略過的標題列) 輸入不要匯入的標題列數。預設值為 0
          • 如果要允許在引用欄位中使用換行符號,請勾選 [Allow quoted newlines] (允許引用換行符號) 的方塊。
          • 如要允許移轉缺少 NULLABLE 欄位的資料列,請勾選 [Allow jagged rows] (允許不規則資料列) 的方塊。

      Cloud Storage 來源詳細資料

    • (選用) 在「Notification options」(通知選項) 區段中:

      • 按一下啟用電子郵件通知的切換開關。當您啟用此選項時,移轉管理員會在移轉作業執行失敗時收到電子郵件通知。
      • 在「Select a Cloud Pub/Sub topic」(選取 Cloud Pub/Sub 主題) 部分,選擇您的主題名稱,或按一下 [Create a topic] (建立主題) 來建立主題。您可透過此選項設定移轉作業的 Cloud Pub/Sub 執行通知。移轉執行通知目前仍為 Alpha 版。
  5. 按一下 [Save] (儲存)

傳統版 UI

  1. 前往 BigQuery 網頁版 UI。

    前往 BigQuery 網頁版 UI

  2. 按一下 [Transfers] (傳輸作業)

  3. 按一下 [Add Transfer] (新增移轉作業)。

  4. 在「New Transfer」(新增移轉作業) 頁面上:

    • 在「Source」(來源) 部分選擇 [Cloud Storage]。
    • 在「Display name」(顯示名稱) 部分,輸入移轉作業的名稱,例如 My Transfer。顯示名稱可以是任何容易辨識的值,方便您日後在必要時進行修改。
    • (選用) 在「Schedule」(排程) 部分,您可保留預設值 [Daily] (每日) (即從建立時間開始,每 24 小時一次),或可按一下 [Edit] (編輯) 變更時間。時間間隔亦可改成 [Weekly] (每週)、[Monthly] (每月) 或 [Custom] (自訂)。如果選取「Custom」(自訂),則必須以類似 Cron 的表示方式輸入時間間隔,例如:every 12 hours。允許的最短週期為 12 小時。如需其他有效的 API 值,請參閱 TransferConfig 下方的 schedule 欄位。

      移轉作業時間表

    • 在「Destination dataset」(目標資料集) 部分,選擇適當的資料集。

    • 在「Destination table」(目標資料表) 中輸入目標資料表的名稱。目標資料表必須遵循資料表命名規則。目標資料表名稱也支援參數

    • 在「Cloud Storage URI」部分,輸入 Cloud Storage URI。輸入內容支援使用萬用字元參數

    • 如要在每次成功移轉後刪除來源檔案,請勾選 [Delete source files after transfer] (移轉完成後刪除來源檔案) 的方塊。 系統會在可能的情況下執行刪除工作。如果首次刪除來源檔案失敗,系統並不會重試刪除工作。

    • 在「File format」(檔案格式) 部分,選取您想要移轉的檔案類型

    • 在「Transfer Options - All Formats」(移轉選項 - 所有格式) 區段下方:

      • 在「Number of errors allowed」(允許的錯誤數量) 欄位中,輸入 BigQuery 在執行工作時可忽略的錯誤記錄數量上限。如果錯誤記錄的數量超過這個值,系統就會在工作結果中傳回「invalid」(無效) 錯誤,且該工作會失敗。預設值為 0
    • 在「Transfer Options - JSON, CSV」(移轉選項 - JSON、CSV) 區段下方:

      • 如要在移轉時排除不符合目標資料表結構定義的資料,請勾選 [gnore unknown values] (略過不明的值) 的方塊。
    • 在「Transfer Options - CSV」(移轉選項 - CSV) 區段下方:

      • 在「Field delimiter」(欄位分隔符號) 部分輸入分隔欄位的字元。預設值為逗號。
      • 如果您不想匯入來源檔案中的標題列,請在「Header rows to skip」(要略過的標題列) 輸入不要匯入的標題列數。預設值為 0
      • 如果要允許在引用欄位中使用換行符號,請勾選 [Allow quoted newlines] (允許引用換行符號) 的方塊。
      • 如要允許移轉缺少 NULLABLE 欄位的資料列,請勾選 [Allow jagged rows] (允許不規則資料列) 的方塊。

      新的 Cloud Storage 移轉作業

    • (選用) 展開「Advanced」(進階) 區段,然後設定移轉作業的執行通知。移轉執行通知目前仍為 Alpha 版。

    • 在「Cloud Pub/Sub topic」(Cloud Pub/Sub 主題) 部分,輸入您的主題名稱,例如 projects/myproject/topics/mytopic

    • 勾選 [Send email notifications] (傳送電子郵件通知),讓系統在移轉執行失敗時,寄送電子郵件通知。

      Cloud Cloud Pub/Sub 主題

  5. 按一下 [Add] (新增)

CLI

輸入 bq mk 指令並提供移轉建立標記 - --transfer_config。另外,您也必須提供以下標記:

  • --data_source
  • --display_name
  • --target_dataset
  • --params
bq mk \
--transfer_config \
--project_id=project_id \
--data_source=data_source \
--display_name=name \
--target_dataset=dataset \
--params='parameters'

其中:

  • project_id 是您的專案 ID。如未提供 --project_id 指定特定專案,系統會使用預設專案。
  • data_source 是資料來源:google_cloud_storage
  • name 是移轉設定的顯示名稱。移轉作業名稱可以是任何容易辨識的值,方便您日後在必要時進行修改。
  • dataset 是移轉設定的目標資料集。
  • parameters 含有已建立移轉設定的 JSON 格式參數,例如:--params='{"param":"param_value"}'
    • 針對 Cloud Storage,您必須提供 data_path_templatedestination_table_name_templatefile_format 參數。data_path_template 是包含要移轉檔案的 Cloud Storage URI,當中可加入一個萬用字元。destination_table_name_template 是目標資料表的名稱。請針對 file_format 指出您要移轉的檔案類型:CSVJSONAVROPARQUETORC。預設值為 CSV。
    • 所有 file_format 值均可加入選用參數 max_bad_records。預設值為 0
    • 如果是 file_format 中的 JSON 或 CSV 值,您可以加入選用參數 ignore_unknown_values。如果您未針對 file_format 選取 CSVJSON,系統會忽略此參數。
    • 如果是 CSV file_format,您可為分隔欄位的字元加入選用參數 field_delimiter。預設值為逗號。如果您未針對 file_format 選取 CSV,系統會忽略此參數。
    • 如果是 CSV file_format,您可加入選用參數 skip_leading_rows 來指出不想匯入的標題列數。預設值為 0。如果您未針對 file_format 選取 CSV,系統會忽略此參數。
    • 如果是 CSV file_format,您可以加入選用參數 allow_quoted_newlines,允許在引用欄位中使用換行符號。如果您未針對 file_format 選取 CSV,系統會忽略此參數。
    • 如果是 CSV file_format,您可以加入選用參數 allow_jagged_rows,以便接受缺少結尾自選欄的資料列。缺少的值將以 NULL 填入。 如果您未針對 file_format 選取 CSV,系統會忽略此參數。
    • 選用參數 delete_source_files 將在每次成功移轉後刪除來源檔案 (如果首次刪除來源檔案失敗,系統並不會重試刪除工作)。delete_source_files 的預設值為 false。

舉例來說,下列指令會使用 gs://mybucket/myfile/*.csvdata_path_template 值、目標資料集 mydataset 以及 file_format CSV,建立名為 My Transfer 的 Cloud Storage 移轉作業。本範例包含有關 CSV file_format 的選用參數非預設值。

移轉作業會在預設專案中建立:

bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path_template":"gs://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage

執行指令後,您會收到如下的訊息:

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

請按照指示進行操作,並在指令列中貼上驗證碼。

API

使用 projects.locations.transferConfigs.create 方法並提供 TransferConfig 資源的執行個體。

設定移轉的重新整理執行作業

除了設定來自 Cloud Storage 的週期性移轉作業之外,您也可以設定重新整理執行作業,以便取得其他資料檔案。

如果移轉設定與日期有關 (參數化) 且/或 Cloud Storage URI 已參數化,就可以在特定日期執行重新整理。

設定重新整理移轉作業:

主控台

  1. 開啟 GCP Console。

    前往 GCP Console

  2. 按一下 [Transfers] (傳輸作業)

  3. 按一下您的移轉作業。

  4. 按一下 [More] (更多) 選單,然後選取 [Refresh Transfer] (重新整理移轉作業)。

  5. 在「Schedule a backfill run」(安排執行補充作業) 對話方塊中,選擇您的 [Start date] (開始日期) 與 [End date] (結束日期)。您可以透過傳統 BigQuery 網頁版 UI 微調時間限制。

    設定重新整理日期

傳統版 UI

  1. 前往 BigQuery 網頁版 UI。

    前往 BigQuery 網頁版 UI

  2. 按一下 [Transfers] (傳輸作業)

  3. 按一下您的移轉作業。

  4. 按一下 [Refresh Transfer] (重新整理移轉作業)。

    重新整理移轉作業

  5. 在「Start Transfer Runs」(開始執行移轉作業) 對話方塊中,選擇「Start Time」(開始時間) 和「End Time」(結束時間)。

    設定重新整理日期

    如果 Cloud Storage 移轉設定並未參數化,則您按下 [Refresh Transfer] (重新整理移轉作業) 時並不會出現日期選項, 系統會改為立即執行重新整理作業。

    立即重新整理

  6. 按一下 [OK] (確定)

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁