Cloud Storage 批次來源

本頁面提供在 Cloud Data Fusion 中設定 Cloud Storage 批次來源外掛程式的指引。

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

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

事前準備

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

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

Cloud Data Fusion API 服務代理人

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

Compute Engine 服務帳戶

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

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

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

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

設定外掛程式

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

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

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

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

      新連結

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

      1. 關閉「Use connection」。
      2. 將「Project ID」欄位的值保留為「自動偵測」。

      3. 在「Service account type」欄位中，將值保留為「File path」，並將「Service account file path」設為自動偵測。

      可重複使用的連線

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

      1. 開啟「Use connection」。
      2. 按一下「瀏覽連線」。

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

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

    3. 在「Reference name」欄位中，輸入要用於系統系譜的名稱，例如 data-fusion-gcs-campaign。

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

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

      • avro
      • blob (Blob 格式需要包含名為 body 的欄位，且欄位類型為 bytes)
      • csv
      • delimited
      • json
      • parquet
      • text (文字格式需要包含一個欄位，其名稱為 body，類型為字串)
      • tsv
      • 您在環境中部署的任何格式外掛程式名稱

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

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

    8. 選用步驟：在「Override」欄位中，輸入要略過的資料欄名稱及其對應的資料類型。

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

    10. 選用：在「臨時值區名稱」欄位中輸入 Cloud Storage 值區的名稱。

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

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

屬性

屬性 已啟用巨集 必要屬性 說明
標籤 否 是 資料管道中的節點名稱。
使用連線 否 否 瀏覽可重複使用的來源連線。如要進一步瞭解如何新增、匯入及編輯瀏覽連線時顯示的連線，請參閱「管理連線」。
連線 是 是 如果已開啟「使用連線」，您選取的可重複使用連線名稱就會顯示在這個欄位中。
專案 ID 是 否 僅在「Use connection」關閉時使用。專案的全域專屬 ID。
預設值為 auto-detect。
服務帳戶類型 是 否 選取下列其中一個選項：
  • 檔案路徑：服務帳戶所在的路徑。
  • JSON：服務帳戶的 JSON 內容。
服務帳戶檔案路徑 是 否 只有在服務帳戶類型值為「檔案路徑」時才會使用。用於授權的服務帳戶金鑰在本機檔案系統中的路徑。如果工作在 Dataproc 叢集中執行，請將值設為自動偵測。如果工作在其他類型的叢集中執行，則該檔案必須位於叢集中的每個節點。
預設為 auto-detect。
服務帳戶 JSON 是 否 只有在服務帳戶類型值為 JSON 時才會使用。服務帳戶的 JSON 檔案內容。
參照名稱 否 是 這個名稱可在其他服務 (例如沿革和註解中繼資料) 中，識別出這個來源。
路徑 是 是 要讀取的檔案路徑。如果指定目錄，請使用反斜線 (/) 結束路徑。例如 gs://bucket/path/to/directory/。如要比對檔案名稱模式，您可以使用星號 (*) 做為萬用字元。如果找不到或沒有相符的檔案，管道就會失敗。
格式 否 是 要讀取的資料格式。格式必須符合下列其中一種：
  • avro
  • blob (Blob 格式需要包含名為 body 的欄位，且欄位類型為 bytes)
  • 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。
規則運算式路徑篩選器 是 否 檔案路徑必須符合的規則運算式，才能納入輸入內容。系統會比較完整路徑，而非只比較檔案名稱。如果未提供檔案，系統就不會篩選檔案。如要進一步瞭解規則運算式語法，請參閱「模式」。
路徑欄位 是 否 輸出欄位，用於放置記錄讀取的檔案路徑。如果未指定，輸出記錄中就不會包含路徑。如果指定了這個值，則欄位必須以字串形式存在於輸出結構定義中。
僅限路徑檔案名稱 是 否 如果已設定 Path 欄位屬性，請只使用檔案名稱，而非路徑的 URI。
預設值為 False。
遞迴讀取檔案 是 否 是否要從路徑遞迴讀取檔案。
預設值為 False。
允許空白輸入 是 否 是否允許不含資料的輸入路徑。如果設為 False，當沒有可讀取的資料時，外掛程式就會發生錯誤。設為 True 時，系統不會擲回錯誤，也不會讀取任何記錄。
預設值為 False。
資料檔案已加密 是 否 檔案是否已加密。詳情請參閱「資料檔案加密」。
預設值為 False。
加密中繼資料檔案後置字元 是 否 加密中繼資料檔案的檔案名稱後置字元。
預設值為「metadata」。
檔案系統屬性 是 否 讀取資料時，要與 InputFormat 搭配使用的其他屬性。
檔案編碼 是 否 要讀取的檔案使用的字元編碼。
預設為 UTF-8。
輸出結構定義 是 否 如果已設定 Path 欄位屬性，則該屬性必須以字串形式出現在結構定義中。

資料檔案加密

本節將說明「資料檔案加密」屬性。如果將其設為 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 代表 Tink 程式庫中序列化金鑰組資訊的 JSON 物件。

示例

    /* 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"

      }

    }

版本資訊

後續步驟