排定 Snowflake 轉移作業

AWS

AWS 代管 Snowflake 帳戶的暫存值區

如果是 AWS 代管的 Snowflake 帳戶，請建立 Amazon S3 值區來暫存 Snowflake 資料，再將資料載入 BigQuery。

1. 建立 Amazon S3 bucket。

2. 建立及設定 Snowflake 儲存空間整合物件，允許 Snowflake 將資料寫入 Amazon S3 值區，做為外部階段。

如要允許 Amazon S3 bucket 的讀取權限， 您也必須執行下列操作：

1. 建立專用的 Amazon IAM 使用者，並授予 AmazonS3ReadOnlyAccess 政策。

2. 為 IAM 使用者建立 Amazon 存取金鑰組。

Azure

Azure 託管 Snowflake 帳戶的暫存 Azure Blob 儲存體容器

如果是 Azure 代管的 Snowflake 帳戶，請建立 Azure Blob 儲存體容器，暫存 Snowflake 資料，再載入 BigQuery。

1. 建立 Azure 儲存體帳戶，並在其中建立儲存體容器。
2. 建立及設定 Snowflake 儲存空間整合物件，允許 Snowflake 將資料寫入 Azure 儲存空間容器，做為外部階段。請注意，由於我們不會使用「步驟 3：建立外部階段」，因此可以略過。

如要允許讀取 Azure 容器，請為該容器產生 SAS 權杖。

Cloud de Confiance

Cloud de Confiance代管 Snowflake 帳戶的暫存值區

如果是 Cloud de Confiance代管的 Snowflake 帳戶，請建立 Cloud Storage bucket，暫存 Snowflake 資料，再載入 BigQuery。

1. 建立 Cloud Storage 值區。
2. 建立及設定 Snowflake 儲存空間整合物件，允許 Snowflake 將資料寫入 Cloud Storage bucket 做為外部階段。

3. 如要允許存取暫存 bucket，請使用下列指令，將 roles/storage.objectViewer 角色授予 DTS 服務代理：

   gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET_NAME \
     --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.s3ns-system.iam.gserviceaccount.com \
     --role=roles/storage.objectViewer

控制台

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

   前往「資料轉移」頁面

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

3. 在「來源類型」部分，從「來源」清單中選取「Snowflake 遷移」。

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

5. 在「Destination settings」(目的地設定) 部分，從「Dataset」(資料集) 清單中選擇您建立的資料集。

6. 在「Snowflake Credentials」(Snowflake 憑證) 部分，執行下列操作：

   1. 在「帳戶 ID」中，輸入 Snowflake 帳戶的專屬 ID，也就是機構名稱和帳戶名稱的組合。這個 ID 是 Snowflake 帳戶網址的前置字元，而非完整網址。例如：ACCOUNT_IDENTIFIER.snowflakecomputing.com。
   2. 在「Username」(使用者名稱) 中，輸入 Snowflake 使用者名稱。系統會使用該使用者的憑證和授權，存取資料庫以轉移 Snowflake 資料表。建議您使用為這項轉移作業建立的使用者。
   3. 在「Authentication Mechanism」部分，選取 Snowflake 使用者驗證方法：

      密碼

      • 在「Password」(密碼) 中輸入 Snowflake 使用者的密碼。

      KEY_PAIR

      • 在「Private Key」(私密金鑰)，輸入與與 Snowflake 使用者相關聯的公開金鑰連結的私密金鑰。
      • 如要使用通關密語加密私密金鑰，請選取「Is Private Key Encrypted」(私密金鑰是否已加密) 欄位。
      • 在「Private Key Passphrase」(私密金鑰通關密語) 部分，輸入加密私密金鑰的通關密語。如果您已選取「私密金鑰是否經過加密」，就必須填寫這個欄位。 詳情請參閱「產生金鑰組以進行驗證」。
   • 在「Warehouse」中，輸入用於執行這項資料移轉作業的倉庫。
   • 在「Snowflake Database」(Snowflake 資料庫) 中，輸入包含此資料移轉所含資料表的 Snowflake 資料庫名稱。
   • 在「Snowflake Schema」(Snowflake 結構定義) 中，輸入包含此資料移轉作業所含資料表的 Snowflake 結構定義名稱。

7. 在「儲存空間設定」部分，執行下列操作：

   1. 在「Storage integration object name」(儲存空間整合物件名稱) 中，輸入 Snowflake 儲存空間整合物件的名稱。
   2. 選用：在「檔案大小上限」中，指定從 Snowflake 卸載至暫存位置的每個檔案大小上限 (以 MB 為單位)。

   3. 在「Cloud Provider」(雲端服務供應商) 部分，根據代管 Snowflake 帳戶的雲端服務供應商，選取 AWS、AZURE 或 GCP。

      AWS

      • 在「Amazon S3 URI」部分，輸入將做為暫存區使用的 Amazon S3 值區的 URI。
      • 在「Access key ID」(存取金鑰 ID) 和「Secret access key」(存取密鑰) 部分，輸入存取金鑰組。

      Azure

      • 在「Azure storage account name」(Azure 儲存體帳戶名稱)和「The container in the Azure storage account」(Azure 儲存體帳戶中的容器)，輸入要用做暫存區的 Azure Blob 儲存體帳戶和容器名稱。
      • 在「SAS Token」(SAS 權杖) 部分，輸入為容器產生的 SAS 權杖。

      Cloud de Confiance

      • 在「GCS URI」部分，輸入將做為暫存區使用的 Cloud Storage URI。

8. 在「服務帳戶」部分執行下列操作：

   1. 在「服務帳戶」中，輸入要用於這項資料移轉作業的服務帳戶。服務帳戶應屬於移轉設定和目的地資料集建立所在的Cloud de Confiance by S3NS 專案。服務帳戶必須具備 storage.objects.list 和 storage.objects.get 必要權限。

9. 在「結構定義設定」部分，執行下列操作：

   1. 在「Ingestion type」(擷取類型) 部分，選取「Full」(完整) 或「Incremental」(增量)。詳情請參閱「資料擷取行為」一文。
   2. 在「Table name patterns」(資料表名稱格式) 部分，輸入符合結構定義中資料表名稱的名稱或格式，指定要移轉的資料表。您可以使用規則運算式指定模式，例如 table1_regex;table2_regex。此格式必須遵循 Java 規則運算式語法。例如：
      • lineitem;ordertb 會比對名為 lineitem 和 ordertb 的資料表。
      • .* 會比對所有資料表。
   3. 選用：如要「使用 BigQuery Translation Engine 輸出」，請選取這個欄位，指定自訂的翻譯輸出路徑。
   4. 選用：在「翻譯輸出 GCS 路徑」中，指定 Cloud Storage 資料夾的路徑，該資料夾包含翻譯引擎的結構對應檔案。您可以將此欄位留空，讓 Snowflake 連接器自動偵測結構定義。
      • 路徑應採用 translation_target_base_uri/metadata/config/db/schema/ 格式，且結尾必須為 /。
   5. 選用：在「自訂架構檔案路徑」中，指定自訂架構檔案的 Cloud Storage 路徑。
   6. 選用：如要將零比例的 Snowflake NUMBER 對應至 BigQuery INT64，請選取這個欄位，將 Snowflake NUMBER(p, 0) 型別對應至 BigQuery INT64。

10. 在「網路連線」部分，執行下列操作：

    1. 如要使用私人網路，請在建立私人資料轉移時選取「True」。
    2. 如果是 PSC 服務連結，請輸入服務連結 URI (如要建立私人連線)。詳情請參閱「建立私有 Snowflake 轉移設定」。
    3. 如果是 Private Network Service，請輸入服務目錄的自我連結，建立私人資料移轉作業。詳情請參閱「建立私有 Snowflake 轉移設定」。

11. 選用：在「Notification options」(通知選項) 專區，執行下列操作：

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

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

13. 按一下 [儲存]。

14. Cloud de Confiance 控制台會顯示移轉設定的所有詳細資料，包括此移轉作業的「Resource name」(資源名稱)。

bq

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

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

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

更改下列內容：

• project_id：您的 Cloud de Confiance by S3NS 專案 ID。如果未指定 --project_id，系統會使用預設專案。
• data_source：資料來源 snowflake_migration。
• dataset：移轉設定的 BigQuery 目標資料集。
• name：移轉設定的顯示名稱。移轉作業名稱可以是任意值，日後需要修改移轉作業時，能夠據此識別即可。
• service_account：(選用) 用於驗證轉移作業的服務帳戶名稱。服務帳戶應由用於建立移轉作業的 project_id 擁有，且應具備所有必要角色。
• parameters：已建立移轉設定的 JSON 格式參數。例如：--params='{"param":"param_value"}'。

您可以為 Snowflake 轉移設定下列參數：

• account_identifier：指定 Snowflake 帳戶的專屬 ID，也就是機構名稱和帳戶名稱的組合。這個 ID 是 Snowflake 帳戶網址的前置字元，而非完整網址。例如：account_identifier.snowflakecomputing.com。
• username：指定 Snowflake 使用者的使用者名稱，系統會使用該使用者的憑證和授權存取資料庫，以轉移 Snowflake 資料表。
• auth_mechanism：指定 Snowflake 使用者驗證方法。 支援的值為 PASSWORD 和 KEY_PAIR。詳情請參閱「產生驗證用的金鑰組」。
• password：指定 Snowflake 使用者的密碼。如果您在 auth_mechanism 欄位中指定 PASSWORD，則此欄位為必填欄位。
• private_key：指定與與 Snowflake 使用者相關聯的公開金鑰連結的私密金鑰。如果您在 auth_mechanism 欄位中指定 KEY_PAIR，則此欄位為必填欄位。
• is_private_key_encrypted：如果私密金鑰是以通關密語加密，請指定 true。
• private_key_passphrase：指定加密私密金鑰的通關密語。如果您在 auth_mechanism 欄位中指定 KEY_PAIR，並在 is_private_key_encrypted 欄位中指定 true，則此為必填欄位。
• warehouse：指定用於執行這項資料移轉的倉儲。
• service_account：指定要用於這項資料移轉作業的服務帳戶。服務帳戶應屬於建立移轉設定和目的地資料集的相同 Cloud de Confiance by S3NS 專案。服務帳戶必須具備 storage.objects.list 和 storage.objects.get 必要權限。
• database：指定包含此資料轉移作業所用資料表的 Snowflake 資料庫名稱。
• schema：指定包含此資料移轉所含資料表的 Snowflake 結構定義名稱。

• table_name_patterns：輸入名稱或符合結構定義中資料表名稱的格式，指定要轉移的資料表。您可以使用規則運算式指定模式，例如 table1_regex;table2_regex。此格式必須遵循 Java 規則運算式語法。例如，假設使用者要求系統 將文字從英文翻譯成法文

  • lineitem;ordertb 會比對名為 lineitem 和 ordertb 的資料表。

  • .* 會比對所有資料表。

    您也可以將這個欄位留白，用以遷移所有來自指定結構定義的資料表。

• ingestion_mode：指定轉移的擷取模式。支援的值為 FULL 和 INCREMENTAL。詳情請參閱「資料擷取行為」。

• translation_output_gcs_path：(選用) 指定 Cloud Storage 資料夾的路徑，該資料夾包含翻譯引擎的結構定義對應檔案。您可以將此欄位留空，讓 Snowflake 連接器自動偵測結構定義。

  • 路徑應採用 gs://translation_target_base_uri/metadata/config/db/schema/ 格式，且結尾必須為 /。

• storage_integration_object_name：指定 Snowflake 儲存空間整合物件的名稱。

• cloud_provider：輸入 AWS、AZURE 或 GCP，視代管 Snowflake 帳戶的雲端服務供應商而定。

• staging_s3_uri：輸入將做為暫存區使用的 S3 值區 URI。只有在 cloud_provider 為 AWS 時才需要。

• aws_access_key_id：輸入存取金鑰組。只有在 cloud_provider 為 AWS 時才需要。

• aws_secret_access_key：輸入存取金鑰組。只有在 cloud_provider 為 AWS 時才需要。

• azure_storage_account：輸入要用做暫存區的儲存空間帳戶名稱。只有在 cloud_provider 為 AZURE 時才需要。

• staging_azure_container：輸入Azure Blob 儲存體中的容器，做為暫存區。只有在 cloud_provider 為 AZURE 時才需要。

• azure_sas_token：輸入 SAS 權杖。只有在 cloud_provider 為 AZURE 時才需要。

• staging_gcs_uri：輸入要用做暫存區的 Cloud Storage URI。只有在 cloud_provider 為 GCP 時才需要。

• use_private_network：如要建立私人資料轉移，請設為 TRUE。

• service_attachment：如要建立私人資料移轉作業，請指定服務連結 URI。詳情請參閱「建立私人 Snowflake 轉移設定」。

• private_network_service：如果您要建立私人資料移轉作業，請指定 NLB 服務的自我連結。詳情請參閱「建立私有 Snowflake 轉移設定」。

舉例來說，如果是 AWS 代管的 Snowflake 帳戶，下列指令會建立名為 Snowflake transfer config 的 Snowflake 移轉作業，其中目標資料集的名稱為 your_bq_dataset，專案的 ID 為 your_project_id。

  PARAMS='{
  "account_identifier": "your_account_identifier",
  "auth_mechanism": "KEY_PAIR",
  "aws_access_key_id": "your_access_key_id",
  "aws_secret_access_key": "your_aws_secret_access_key",
  "cloud_provider": "AWS",
  "database": "your_sf_database",
  "ingestion_mode": "INCREMENTAL",
  "private_key": "-----BEGIN PRIVATE KEY----- privatekey\nseparatedwith\nnewlinecharacters=-----END PRIVATE KEY-----",
  "schema": "your_snowflake_schema",
  "service_account": "your_service_account",
  "storage_integration_object_name": "your_storage_integration_object",
  "staging_s3_uri": "s3://your/s3/bucket/uri",
  "table_name_patterns": ".*",
  "translation_output_gcs_path": "gs://sf_test_translation/output/metadata/config/database_name/schema_name/",
  "username": "your_sf_username",
  "warehouse": "your_warehouse"
}'

bq mk --transfer_config \
    --project_id=your_project_id \
    --target_dataset=your_bq_dataset \
    --display_name='snowflake transfer config' \
    --params="$PARAMS" \
    --data_source=snowflake_migration

API

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