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 的偏好設定觸發,該偏好設定會將資料附加至目的地資料表。詳情請參閱載入配置中的 configuration.load.writeDisposition
  • 如果將資料集的位置設定為 US 以外的值,則單一地區或多地區 Cloud Storage 值區必須與資料集位於相同的地區。

根據 Cloud Storage 來源資料的格式,可能還有其他的限制。如需詳細資訊,請參閱:

所需權限

將資料載入至 BigQuery 時,您必須擁有專案或資料集層級的權限,才能將資料載入至新的或現有的 BigQuery 資料表與分區。如果要從 Cloud Storage 載入資料,您也要有權限存取包含資料的值區。請確認您已擁有下列必要權限:

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

設定 Cloud Storage 移轉作業

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

主控台

  1. 前往 BigQuery 網頁版 UI。

    前往 BigQuery 網頁版 UI

  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 (自訂)
        • On-demand (隨選)
      • 在「Start date and run time」(開始日期和執行時間) 部分,輸入開始移轉的日期與時間。如果您選擇 [Start now] (立即開始),就會停用此選項。

        移轉作業時間表

    • 在 [Destination dataset] (目的地資料集) 區段,針對「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) 下:
          • 如要在移轉時排除不符合目的地資料表結構定義的資料,請勾選「Ignore 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) 區段下方:

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

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

      全新 Cloud Storage 移轉

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

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

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

      Cloud Pub/Sub 主題

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

指令列

輸入 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
  • --display_name 是移轉設定的顯示名稱。移轉名稱可以是任何容易識別並且方便您後續修改的值。
  • --target_dataset 是移轉設定的目標資料集。
  • --params 含有已建立移轉設定的 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 的預設值為否。

例如下列指令建立名為 My Transfer 的 Cloud Storage 移轉作業,其中使用 gs://mybucket/myfile/*.csvdata_path_template 值、目標資料集 mydataset,以及 file_format CSV。本範例包含有關 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 主控台中開啟 BigQuery 網頁版 UI。

    前往 BigQuery 網頁版 UI

  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] (確定)

後續步驟

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

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

這個網頁