Cloud Storage 批次來源

本頁面提供相關指引，說明如何在 Cloud Data Fusion 中設定 Cloud Storage 批次來源外掛程式。

您可以使用 Cloud Storage 批次來源外掛程式，從 Cloud Storage bucket 讀取資料，並匯入 Cloud Data Fusion 進行後續處理和轉換。可讓您載入多種檔案格式的資料，包括：

• 結構化：CSV、Avro、Parquet、ORC
• 半結構化：JSON、XML
• 其他：文字、二進位

事前準備

Cloud Data Fusion 通常有兩個服務帳戶：

• 設計階段服務帳戶： Cloud Data Fusion API 服務代理人
• 執行階段服務帳戶： Compute Engine 服務帳戶

使用 Cloud Storage 批次來源外掛程式前，請將下列角色或權限授予每個服務帳戶。

Cloud Data Fusion API 服務代理

這個服務帳戶已具備所有必要權限，因此不需要新增其他權限。

注意： 設計管道時，您需要管道所用值區的 storage.buckets.list 權限。執行管道時不需要這個項目。

Compute Engine 服務帳戶

在 Google Cloud 專案中，將下列 IAM 角色或權限授予 Compute Engine 服務帳戶：

• Storage 舊版 bucket 讀取者 (roles/storage.legacyBucketReader)。這個預先定義的角色包含必要的 storage.buckets.get 權限。

• Storage 物件檢視者 (roles/storage.legacyBucketReader)。這個預先定義的角色包含下列必要權限：

  • storage.objects.get
  • storage.objects.list

設定外掛程式

1. 前往 Cloud Data Fusion 網頁介面，然後點選「Studio」。
2. 確認已選取「Data Pipeline - Batch」(資料管道 - 批次)，而非「Realtime」(即時)。
3. 在「來源」選單中，點選「GCS」。Cloud Storage 節點會顯示在管道中。
4. 如要設定來源，請前往 Cloud Storage 節點，然後按一下「Properties」(屬性)。

5. 輸入下列屬性。如需完整清單，請參閱「屬性」。

   1. 輸入 Cloud Storage 節點的標籤，例如 Cloud Storage tables。

   2. 輸入連線詳細資料。您可以設定新的單次連線，或是現有的可重複使用連線。

      新連結

      如要新增與 Cloud Storage 的一次性連線，請按照下列步驟操作：

      1. 請關閉「使用連線」。
      2. 保留「專案 ID」欄位中的自動偵測值。

      3. 在「服務帳戶類型」欄位中，將值保留為「檔案路徑」，並將「服務帳戶檔案路徑」保留為自動偵測。

         注意： 如果外掛程式未在 Managed Service for Apache Spark 叢集上執行，請輸入「服務帳戶類型」和「服務帳戶檔案路徑」的值。詳情請參閱「屬性」一節。

      可重複使用的連線

      如要重複使用現有連線，請按照下列步驟操作：

      1. 開啟「使用連線」。
      2. 按一下「Browse connections」(瀏覽連線)。

      3. 按一下連線名稱，例如「Cloud Storage Default」。

         注意： 如要進一步瞭解如何新增、匯入及編輯瀏覽連線時顯示的連線，請參閱「管理連線」。

      4. 選用：如果沒有連線，且您想建立新的可重複使用連線，請按一下「新增連線」，然後參閱本頁面「新連線」分頁中的步驟。

   3. 在「Reference name」(參照名稱) 欄位中，輸入要用於沿襲的名稱，例如 data-fusion-gcs-campaign。

   4. 在「Path」(路徑) 欄位中，輸入要讀取的路徑，例如 gs://BUCKET_PATH。

   5. 在「格式」欄位中，選取要讀取資料的下列其中一種檔案格式：

      • avro
      • blob (blob 格式需要包含名為 body 的欄位，且類型為位元組的結構定義)
      • csv
      • delimited
      • json
      • parquet
      • text (文字格式需要包含名為 body 的欄位，且類型為字串的結構定義)
      • tsv
      • 您在環境中部署的任何格式外掛程式名稱
      注意： 如果在這個欄位中使用巨集，必須使用預先定義的格式。巨集不支援外掛程式新增的格式。

   6. 選用：如要測試連線，請按一下「取得架構」。

   7. 選用：在「樣本大小」欄位中，輸入要檢查所選資料類型的最大列數，例如 1000。

   8. 選用：在「Override」(覆寫) 欄位中，輸入要略過的資料欄名稱和各自的資料類型。

   9. 選用：輸入進階屬性，例如最小分割大小或規則運算式路徑篩選器 (請參閱「屬性」)。

   10. 選用：在「Temporary bucket name」(暫時 bucket 名稱) 欄位中，輸入 Cloud Storage bucket 的名稱。

6. 選用：按一下「驗證」，並修正所有錯誤。

7. 按一下「關閉」。系統會儲存屬性，您可以在 Cloud Data Fusion Studio 中繼續建構資料管道。

屬性

屬性	含巨集功能	必要屬性	說明
標籤	否	是	資料管道中的節點名稱。
使用連線	否	否	瀏覽可重複使用的來源連線。如要進一步瞭解如何新增、匯入及編輯瀏覽連線時顯示的連線，請參閱「管理連線」。
連結	是	是	如果開啟「使用連線」，這個欄位會顯示您選取的重複使用連線名稱。
專案 ID	是	否	僅在關閉「使用連線」時使用。專案的全域專屬 ID。 預設值為 auto-detect。
服務帳戶類型	是	否	選取下列其中一個選項： 檔案路徑：服務帳戶所在的路徑。 JSON：服務帳戶的 JSON 內容。
服務帳戶檔案路徑	是	否	只有當服務帳戶類型值為「檔案路徑」時，才會使用這個值。用於授權的服務帳戶金鑰在本機檔案系統中的路徑。如果工作是在 Managed Service for Apache Spark 叢集上執行， 請將值設為自動偵測。如果工作在其他類型的叢集上執行，則叢集中的每個節點都必須有該檔案。 預設值為 auto-detect。
服務帳戶 JSON	是	否	僅在「服務帳戶類型」值為 JSON 時使用。 服務帳戶的 JSON 檔案內容。
參照名稱	否	是	這個名稱可供其他服務 (例如沿襲和註解中繼資料) 專屬識別這個來源。
路徑	是	是	要讀取檔案的路徑。如果指定目錄，請以反斜線 (/) 終止路徑。例如：gs://bucket/path/to/directory/。如要比對檔案名稱模式，可以使用星號 (*) 做為萬用字元。如果找不到或沒有相符的檔案，管道就會失敗。
格式	否	是	要讀取的資料格式。格式必須為下列其中一種： avro blob (blob 格式需要包含名為 body 的欄位，且類型為位元組的結構定義) csv delimited json parquet text (文字格式需要包含名為 body 的欄位 (類型為字串) 的結構定義) tsv 您在環境中部署的任何格式外掛程式名稱 如果格式為巨集，只能使用預先封裝的格式
樣本大小	是	否	系統會調查的列數上限，以自動偵測資料類型。預設值為 1000。
覆寫	是	否	系統會略過自動偵測資料類型，並列出對應資料的資料欄。
分隔符號	是	否	格式為「分隔」時使用的分隔符號。其他格式會忽略這項屬性。
啟用引用值	是	否	是否將引號之間的內容視為值。這個屬性僅適用於 csv、tsv 或分隔格式。舉例來說，如果這項屬性設為 true，下列輸出內容會包含兩個欄位：1, "a, b, c"。第一個欄位的值為 1。第二個具有 a, b, c。引號字元會遭到截斷。換行分隔符號不得位於引號內。 外掛程式會假設引號已正確括住，例如 "a, b, c"。如果沒有關閉引號 ("a,b,c,)，就會發生錯誤。 預設值為 False。
使用第一列做為標題	是	否	是否將每個檔案的第一行做為資料欄標題。支援的格式包括文字、CSV、TSV 和分隔。 預設值為 False。
最低分割大小	是	否	每個輸入分區的最小大小 (以位元組為單位)。較小的分割區會提高平行處理層級，但需要更多資源和額外負擔。 如果「格式」值為 blob，您就無法分割資料。
分割大小上限	是	否	每個輸入分割區的大小上限 (以位元組為單位)。較小的分割區會提高平行處理層級，但需要更多資源和額外負擔。 如果「格式」值為 blob，您就無法分割資料。 預設值為 128 MB。
規則運算式路徑篩選器	是	否	檔案路徑必須符合的規則運算式，才能納入輸入內容。系統會比較完整路徑，而不只是檔案名稱。如果未提供任何檔案，系統就不會篩選檔案。如要進一步瞭解規則運算式語法，請參閱模式。
路徑欄位	是	否	輸出欄位，用於放置記錄讀取來源檔案的路徑。如未指定，輸出記錄中不會包含路徑。如果指定這個值，則欄位必須以字串形式存在於輸出結構定義中。
僅限路徑檔案名稱	是	否	如果已設定「路徑欄位」屬性，請只使用檔案名稱，不要使用路徑的 URI。 預設值為 False。
以遞迴方式讀取檔案	是	否	是否要從路徑以遞迴方式讀取檔案。 預設值為 False。
允許輸入空白內容	是	否	是否允許輸入路徑不含資料。如果設為 False，外掛程式會在沒有資料可讀取時發生錯誤。設為 True 時，系統不會擲回任何錯誤，且讀取的記錄為零。 預設值為 False。
資料檔案已加密	是	否	檔案是否經過加密。詳情請參閱「資料檔案加密」。 預設值為 False。
加密中繼資料檔案後置字串	是	否	加密中繼資料檔案的檔案名稱後置字串。 預設值為 metadata。
檔案系統屬性	是	否	讀取資料時，要搭配 InputFormat 使用的額外屬性。
檔案編碼	是	否	要讀取檔案的字元編碼。 預設值為 UTF-8。
輸出內容結構定義	是	否	如果設定了「路徑欄位」屬性，則必須以字串形式出現在結構定義中。

資料檔案加密

本節說明「資料檔案加密」屬性。如果設為 true，系統會使用 Tink 程式庫提供的串流 AEAD 解密檔案。每個資料檔案都必須隨附中繼資料檔案，其中包含密碼資訊。舉例來說，gs://BUCKET/PATH_TO_DIRECTORY/file1.csv.enc 的加密資料檔案必須有 gs://BUCKET/ PATH_TO_DIRECTORY/file1.csv.enc.metadata 的中繼資料檔案。中繼資料檔案包含具有下列屬性的 JSON 物件：

屬性	說明
kms	用來加密資料加密金鑰的 Cloud Key Management Service URI。
aad	加密時使用的 Base64 編碼額外驗證資料。
key set	JSON 物件，代表 Tink 程式庫中序列化的金鑰組資訊。

範例

    /* Counting example */
    {

      "kms": "gcp-kms://projects/my-key-project/locations/us-west1/keyRings/my-key-ring/cryptoKeys/mykey",

      "aad": "73iT4SUJBM24umXecCCf3A==",

      "keyset": {

          "keysetInfo": {

              "primaryKeyId": 602257784,

              "keyInfo": [{

                  "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmHkdfStreamingKey",

                  "outputPrefixType": "RAW",

                  "keyId": 602257784,

                  "status": "ENABLED"

              }]

          },

          "encryptedKeyset": "CiQAz5HH+nUA0Zuqnz4LCnBEVTHS72s/zwjpcnAMIPGpW6kxLggSrAEAcJKHmXeg8kfJ3GD4GuFeWDZzgGn3tfolk6Yf5d7rxKxDEChIMWJWGhWlDHbBW5B9HqWfKx2nQWSC+zjM8FLefVtPYrdJ8n6Eg8ksAnSyXmhN5LoIj6az3XBugtXvCCotQHrBuyoDY+j5ZH9J4tm/bzrLEjCdWAc+oAlhsUAV77jZhowJr6EBiyVuRVfcwLwiscWkQ9J7jjHc7ih9HKfnqAZmQ6iWP36OMrEn"

      }

    }
    

版本資訊

• 2023 年 9 月 6 日

後續步驟

• 進一步瞭解 Cloud Data Fusion 中的外掛程式。