將 Cloud Storage 資料載入 BigQuery

主控台

1. 前往 Google Cloud 控制台的「資料移轉」頁面。

   前往「資料移轉」

2. 按一下 add「建立移轉作業」。

3. 在「Source type」(來源類型) 區段中，針對「Source」(來源)，選擇「Google Cloud Storage」。

   

4. 在「Transfer config name」(轉移設定名稱) 專區，針對「Display name」(顯示名稱) 輸入資料移轉作業的名稱，例如 My Transfer。移轉作業名稱可以是任意值，日後需要修改移轉作業時能夠據此識別。

   

5. 在「Schedule options」(排程選項) 部分選取「Repeat frequency」(重複執行頻率)：

   • 如果選取「Hours」(小時)、「Days」(天)、「Weeks」(週)或「Months」(月)，必須一併指定頻率。您也可以選取「Custom」(自訂)，自行指定重複頻率。您可以選取「Start now」(立即開始) 或「Start at set time」(在所設時間開始執行)，並提供開始日期和執行時間。

   • 如果選取「On-demand」，這項資料移轉作業會在您手動觸發後執行。

   • 如果選取「Event-driven」(以事件為依據)，則須一併指定Pub/Sub 訂閱項目。請選取訂閱項目名稱，或是點選「Create a subscription」(建立訂閱項目)。這個選項會啟用以事件為依據的移轉作業，事件傳送至 Pub/Sub 訂閱項目時，就會觸發執行移轉作業。

6. 在「Destination settings」(目的地設定) 部分，「Destination dataset」(目的地資料集) 請選取您為了儲存資料而建立的資料集。

   

7. 在「Data source details」(資料來源詳細資料) 區段：

   1. 在「Destination table」(目標資料表) 中輸入目標資料表的名稱。 目的地資料表的名稱必須符合資料表命名規則，目的地資料表名稱也支援參數。
   2. 在「Cloud Storage URI」部分，輸入 Cloud Storage URI。可以使用萬用字元和參數。如果 URI 與所有檔案都不相符，不會覆寫目的地資料表中任何資料。

   3. 「Write preference」(寫入偏好設定) 提供下列選項：

      • 「APPEND」(附加)：逐步將新的資料附加至現有目的地資料表。「Write preference」(寫入偏好設定) 的預設值為「APPEND」(附加)。
      • 「MIRROR」(建立鏡像)：每次移轉資料時，覆寫目的地資料表資料。

      如要進一步瞭解 BigQuery 資料移轉服務如何使用「APPEND」(附加) 或「MIRROR」(建立鏡像) 來擷取資料，請參閱 Cloud Storage 移轉作業資料擷取的相關說明。 如要進一步瞭解 writeDisposition 欄位，請參閱 JobConfigurationLoad。

   4. 如要在每次成功移轉資料後刪除來源檔案，請勾選「Delete source files after transfer」方塊。系統會盡可能執行刪除工作，但不保證一定達成。如果第一次刪除來源檔案失敗，不會再重試。

   5. 在「Transfer Options」部分執行下列操作：

      1. 在「All Formats」底下：
         1. 在「Number of errors allowed」(允許的錯誤數量) 欄位中，輸入 BigQuery 在執行工作時可忽略的錯誤記錄數量上限。如果損壞記錄數量超過這個值，該項工作就會失敗，並在結果傳回 invalid 錯誤。預設值為 0。
         2. (選用步驟) 在「Decimal target types」部分，輸入以半形逗號分隔的清單，內含來源小數值可能轉換成的 SQL 資料類型。系統會依據下列條件，選取要轉換的 SQL 資料類型：
            • 系統會按照 NUMERIC、BIGNUMERIC 和 STRING 的順序，選取下列清單中第一個支援來源資料有效位數和小數位數的資料類型，用來轉換。
            • 如果清單中的資料類型都不支援有效位數和小數位數，則會選取指定清單中支援範圍最廣的資料類型。如果讀取來源資料時，值超過支援的範圍，就會擲回錯誤。
            • 資料類型 STRING 支援所有有效位數和小數位數值。
            • 如果將這個欄位留空，ORC 的預設資料類型為 NUMERIC,STRING，其他檔案格式則為 NUMERIC。
            • 這個欄位不得含有重複的資料類型。
            • 您在這個欄位提供資料類型時採用的順序不會有影響。
      2. 如要在移轉資料時，捨棄不符合目的地資料表結構定義的資料，請勾選「JSON, CSV」(JSON、CSV) 底下的「Ignore unknown values」(略過不明的值) 方塊。
      3. 如果希望資料移轉作業將 Avro 邏輯類型轉換為對應的 BigQuery 資料類型，請在「AVRO」底下勾選「Use avro logical types」方塊。預設會忽略多數類型的 logicalType 屬性，並改用基礎 Avro 類型。

      4. 在「CSV」底下執行下列操作：

         1. 在「Field delimiter」(欄位分隔符號) 部分輸入分隔欄位的字元。預設值為半形逗號。
         2. 在「Quote character」(引用字元) 輸入 CSV 檔案中用來引用資料區段的字元，預設值為英文雙引號 (")。
         3. 如果您不想匯入來源檔案中的標題列，請在「Header rows to skip」(要略過的標題列) 輸入不要匯入的標題列數。預設值為 0。
         4. 如果要允許在引用欄位中使用換行符號，請勾選 [Allow quoted newlines] (允許引用換行符號) 的方塊。
         5. 如要允許移轉缺少 NULLABLE 欄位的資料列，請勾選「Allow jagged rows (CSV)」(允許空值資料列 (CSV)) 方塊。

         請參閱此處，進一步瞭解 CSV 適用選項。

8. 在「Service Account」(服務帳戶) 選單，選取與貴機構 Google Cloud 專案相關聯的服務帳戶。您可以將服務帳戶與資料移轉作業建立關聯，這樣就不需要使用者憑證。如要進一步瞭解如何搭配使用服務帳戶與資料移轉作業，請參閱使用服務帳戶。

   • 如果使用聯合身分登入，您必須擁有服務帳戶才能建立資料移轉作業。如果是以 Google 帳戶登入，則不一定要透過服務帳戶建立資料移轉作業。
   • 服務帳戶必須具備 BigQuery 和 Cloud Storage 的必要權限。

9. 選用步驟：在「Notification options」(通知選項) 部分執行下列操作：

   1. 按一下啟用電子郵件通知的切換開關。啟用這個選項之後，若移轉失敗，資料移轉設定的擁有者會收到電子郵件通知。
   2. 在「Select a Pub/Sub topic」(選取 Pub/Sub 主題) 選取主題名稱，或是點選「Create a topic」(建立主題)。這個選項會針對移轉作業設定 Pub/Sub 執行通知。

10. 選用步驟：如果您使用 CMEK，請在「Advanced options」(進階選項) 部分選取「Customer-managed key」(客戶管理的金鑰)，畫面隨即會列出可用的 CMEK 供您選擇。如要瞭解 CMEK 如何與 BigQuery 資料移轉服務搭配運作，請參閱指定移轉作業加密金鑰的相關說明。

11. 按一下 [儲存]。

bq

輸入 bq mk 指令並提供移轉建立標記 - --transfer_config。還需加上以下旗標：

• --data_source
• --display_name
• --target_dataset
• --params

選用標記：

• --destination_kms_key：指定 Cloud KMS 金鑰的金鑰資源 ID。如果使用客戶管理加密金鑰 (CMEK) 進行這項資料轉移，如要瞭解 CMEK 如何與 BigQuery 資料移轉服務搭配運作，請參閱指定移轉作業加密金鑰。
• --service_account_name：指定要用於 Cloud Storage 移轉驗證的服務帳戶，而非使用者帳戶。

bq mk \
--transfer_config \
--project_id=PROJECT_ID \
--data_source=DATA_SOURCE \
--display_name=NAME \
--target_dataset=DATASET \
--destination_kms_key="DESTINATION_KEY" \
--params='PARAMETERS' \
--service_account_name=SERVICE_ACCOUNT_NAME

其中：

• PROJECT_ID 是您的專案 ID。如未提供 --project_id 指定特定專案，系統會使用預設專案。
• DATA_SOURCE 是資料來源，例如 google_cloud_storage。
• NAME 是資料移轉設定的顯示名稱。移轉作業名稱可以是任意值，日後需要修改移轉作業時，能夠據此識別即可。
• DATASET 是移轉設定的目標資料集。
• DESTINATION_KEY：Cloud KMS 金鑰資源 ID，例如 projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name。
• PARAMETERS 含有已建立移轉設定的 JSON 格式參數，例如：--params='{"param":"param_value"}'。
  • destination_table_name_template：目的地 BigQuery 資料表的名稱。
  • data_path_template：包含要移轉檔案的 Cloud Storage URI。可以使用萬用字元和參數。
  • write_disposition：決定要將相符檔案附加至目的地資料表，還是完全鏡像複製。支援的值為 APPEND 或 MIRROR。如要瞭解 BigQuery 資料移轉服務如何在 Cloud Storage 移轉作業中附加或建立鏡像資料，請參閱「Cloud Storage 移轉作業資料擷取」。
  • file_format：要轉移的檔案格式。格式可以是 CSV、JSON、AVRO、PARQUET 或 ORC。預設值為 CSV。
  • max_bad_records：針對任何 file_format 值，可忽略的錯誤記錄數量上限。預設值為 0。
  • decimal_target_types：針對任何 file_format 值，以半形逗號分隔的清單，內含來源小數值可能轉換成的 SQL 資料類型。如果未提供這個欄位，ORC 的預設資料類型為 "NUMERIC,STRING"，其他檔案格式則為 "NUMERIC"。
  • ignore_unknown_values：針對任何 file_format 值，設為 TRUE 即可接受含有與結構定義不符值的資料列。詳情請參閱JobConfigurationLoad 參考資料表中的 ignoreUnknownvalues 欄位詳細資料。
  • use_avro_logical_types：如為 AVRO file_format 值，請設為 TRUE，將邏輯型別解讀為對應型別 (例如 TIMESTAMP)，而非僅使用原始型別 (例如 INTEGER)。
  • parquet_enum_as_string：如為 PARQUET file_format 值，請設為 TRUE，將 PARQUET ENUM 邏輯型別推斷為 STRING，而非預設的 BYTES。
  • parquet_enable_list_inference：如為 PARQUET file_format 值，請設為 TRUE，以便專門針對 PARQUET LIST 邏輯型別使用結構定義推論。
  • reference_file_schema_uri：參照檔案的 URI 路徑，其中包含讀取器結構定義。
  • field_delimiter：適用於 CSV file_format 值，用來分隔欄位的字元。預設值為半形逗號。
  • quote：適用於 CSV file_format 值，CSV 檔案中用來引用資料區段的字元。預設值為英文雙引號 (")。
  • skip_leading_rows：針對 CSV file_format 值，指出您不想匯入的開頭標題列數。預設值為 0。
  • allow_quoted_newlines：如為 CSV file_format 值，請設為 TRUE，允許在加上引號的欄位中換行。
  • allow_jagged_rows：針對 CSV file_format 值，請設為 TRUE，接受缺少結尾自選欄的資料列。缺少的值會填入 NULL。
  • preserve_ascii_control_characters：針對 CSV file_format 值，請設為 TRUE，保留所有內嵌的 ASCII 控制字元。
  • encoding：指定 CSV 編碼類型。支援的值為 UTF8、ISO_8859_1、UTF16BE、UTF16LE、UTF32BE 和 UTF32LE。
  • delete_source_files：設為 TRUE，即可在每次成功移轉後刪除來源檔案。如果首次刪除來源檔案失敗，系統並不會重試刪除工作。預設值為 FALSE。
• SERVICE_ACCOUNT_NAME 是用於驗證移轉作業的服務帳戶名稱。服務帳戶應由用於建立轉移作業的 project_id 擁有，且應具備所有必要權限。

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

資料移轉作業會在預設專案中建立：

bq mk --transfer_config \
--target_dataset=mydataset \
--project_id=myProject \
--display_name='My Transfer' \
--destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey \
--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":"|",
"quote":";",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com projects/862514376110/locations/us/transferConfigs/ 5dd12f26-0000-262f-bc38-089e0820fe38

執行指令後，您會收到如下的訊息：

[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 資源的執行個體。

Java

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create google cloud storage transfer config
public class CreateCloudStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    // GCS Uri
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    String fileFormat = "CSV";
    String fieldDelimiter = ",";
    String skipLeadingRows = "1";
    Map<String, Value> params = new HashMap<>();
    params.put(
        "destination_table_name_template", Value.newBuilder().setStringValue(tableId).build());
    params.put("data_path_template", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("write_disposition", Value.newBuilder().setStringValue("APPEND").build());
    params.put("file_format", Value.newBuilder().setStringValue(fileFormat).build());
    params.put("field_delimiter", Value.newBuilder().setStringValue(fieldDelimiter).build());
    params.put("skip_leading_rows", Value.newBuilder().setStringValue(skipLeadingRows).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Google Cloud Storage Config Name")
            .setDataSourceId("google_cloud_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createCloudStorageTransfer(projectId, transferConfig);
  }

  public static void createCloudStorageTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Cloud storage transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Cloud storage transfer was not created." + ex.toString());
    }
  }
}

主控台

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery 頁面

2. 按一下 sync_alt「資料移轉」。

3. 從清單中選取資料轉移作業。

4. 按一下「立即執行移轉作業」或「排定補充作業」 (適用於執行階段參數化移轉設定)。

   • 如果您點選「立即執行轉移作業」，請視需要選取「執行一次性轉移作業」或「在特定日期執行」。如果選取「在特定日期執行」，請選取特定日期和時間：

     

   • 如果點選「安排補充作業」，請視需要選取「執行一次性轉移作業」或「在指定日期範圍內執行」。如果選取「在指定日期範圍內執行」，請選取開始和結束日期與時間：

     

5. 按一下 [確定]。

bq

輸入 bq mk 指令並提供 --transfer_run 旗標。您可以使用 --run_time 旗標，也可以使用 --start_time 和 --end_time 旗標。

bq mk \
--transfer_run \
--start_time='START_TIME' \
--end_time='END_TIME' \
RESOURCE_NAME

bq mk \
--transfer_run \
--run_time='RUN_TIME' \
RESOURCE_NAME

其中：

• START_TIME 和 END_TIME 是以 Z 結尾或包含有效時區設定的時間戳記。例如：

  • 2017-08-19T12:11:35.00Z
  • 2017-05-25T00:00:00+00:00

• RUN_TIME 是時間戳記，用來指定排定資料移轉執行作業的時間。如要執行一次性轉移，可以使用 --run_time 標記。

• RESOURCE_NAME 是移轉的資源名稱 (也稱為移轉設定)，例如 projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7。如果您不知道移轉的資源名稱，請執行 bq ls --transfer_config --transfer_location=LOCATION 指令來尋找資源名稱。

API

使用 projects.locations.transferConfigs.startManualRuns 方法，並使用 parent 參數提供移轉設定資源。