HDFS

您可以使用 HDFS 連接器，對 HDFS 資料執行插入、刪除、更新和讀取動作。

支援的版本

這個連接器支援 HDFS Hadoop 3.4.0 版。

事前準備

使用 HDFS 連接器前，請先完成下列工作：

  • 在 Google Cloud 專案中：
    • 將 roles/connectors.admin IAM 角色授予設定連線器的使用者。
    • 將下列 IAM 角色授予要用於連接器的服務帳戶：
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      服務帳戶是特殊的 Google 帳戶類型，主要用於代表需要驗證且必須取得授權才能存取 Google API 資料的非人類使用者。如果您沒有服務帳戶，請建立服務帳戶。連接器和服務帳戶必須屬於相同專案。詳情請參閱「建立服務帳戶」。

    • 啟用下列服務：
      • secretmanager.googleapis.com (Secret Manager API)
      • connectors.googleapis.com (Connectors API)

      如要瞭解如何啟用服務，請參閱「啟用服務」。

    如果先前未啟用這些服務或權限，系統會在設定連結器時提示您啟用。

設定連接器

連線專屬於資料來源。也就是說，如果您有多個資料來源，則必須為每個資料來源建立個別的連線。如要建立連結，請按照下列步驟操作：

  1. 在 Cloud 控制台中，前往「Integration Connectors」>「Connections」頁面，然後選取或建立 Google Cloud 專案。

    前往「連線」頁面

  2. 按一下「+ 建立新連線」，開啟「建立連線」頁面。
  3. 在「位置」部分中，選擇連線的位置。
    1. 區域：從下拉式清單中選取位置。

      如需所有支援區域的清單，請參閱「地點」一文。

    2. 點按「下一步」。
  4. 在「連線詳細資料」部分，完成下列步驟：
    1. 連接器：從可用連接器的下拉式清單中選取「HDFS」。
    2. 連接器版本：從可用版本的下拉式清單中選取連接器版本。
    3. 在「連線名稱」欄位中，輸入連線執行個體的名稱。

      連線名稱必須符合下列條件：

      • 連線名稱可使用英文字母、數字或連字號。
      • 字母必須為小寫。
      • 連線名稱開頭須為英文字母，結尾則須為英文字母或數字。
      • 連結名稱不得超過 49 個半形字元。
    4. 視需要輸入連線執行個體的「Description」(說明)。
    5. 或者，可啟用 Cloud Logging，然後選取記錄層級。記錄層級預設為 Error。
    6. 服務帳戶：選取具備必要角色的服務帳戶。
    7. 路徑：指定要當做工作目錄的 HDFS 路徑。
    8. 視需要設定「連線節點設定」：

      • 節點數量下限：輸入連線節點數量下限。
      • 節點數量上限：輸入連線節點數量上限。

      節點是用來處理交易的連線單位 (或備用資源)。連線處理的交易量越多，就需要越多節點；反之，處理的交易量越少，需要的節點就越少。如要瞭解節點對連接器價格的影響，請參閱「 連線節點的定價」。如未輸入任何值，系統預設會將節點下限設為 2 (提高可用性)，節點上限則設為 50。

    9. (選用) 按一下「+ 新增標籤」，以鍵/值組合的形式為連線新增標籤。
    10. 點按「下一步」。
  5. 在「目的地」部分，輸入要連線的遠端主機 (後端系統) 詳細資料。
    1. 目的地類型：選取目的地類型。
      • 如要指定目的地主機名稱或 IP 位址，請選取「主機位址」，然後在「主機 1」欄位中輸入位址。
      • 如要建立私人連線，請選取「端點連結」。在「Endpoint Attachment」(端點連結) 清單中，選取為後端系統建立的端點連結。

      如要建立與後端系統的公開連線，並加強安全性，可以為連線設定靜態輸出 IP 位址，然後設定防火牆規則，只允許特定靜態 IP 位址。

      如要輸入其他目的地，請按一下「+新增目的地」。

    2. 點按「下一步」。
  6. 在「Authentication」(驗證) 部分，輸入驗證詳細資料。
    1. 選取「驗證類型」，然後輸入相關詳細資料。

      HDFS 連線支援下列驗證類型：

      • 使用者名稱和密碼

      如要瞭解如何設定這些驗證類型，請參閱「設定驗證」。

    2. 點按「下一步」。
  7. 檢查：檢查連結和驗證詳細資料。
  8. 點選「建立」。

設定驗證機制

根據要使用的驗證方式輸入詳細資料。

  • 使用者名稱和密碼
    • 使用者名稱：輸入要用於 HDFS 連線的使用者名稱。
    • 密碼：輸入 Secret Manager 密鑰，內含與使用者名稱相關聯的密碼。
    • 密鑰版本：選取上述所選密鑰的密鑰版本。

連線設定範例

本節列出您在建立連線時設定的各個欄位範例值。

使用者名稱和密碼連線類型

欄位名稱 詳細資料
位置 europe-west1
連接器 HDFS
連接器版本 1
連線名稱 hdfs-v24-new
服務帳戶 my-service-account@my-project.iam.gserviceaccount.com
節點數量下限 2
節點數量上限 2
目的地類型 主機地址
主機 10.128.0.
port1 10000
使用者名稱 user1
密碼 密碼
Secret 版本 1

系統限制

每個節點的 HDFS 連接器每秒最多可處理 20 筆交易，超過此限制的交易會遭到節流。根據預設，Integration Connectors 會為連線分配 2 個節點 (以提高可用性)。

如要瞭解 Integration Connectors 適用的限制，請參閱「限制」一文。

在整合中建立 HDFS 連線

建立連線後，Apigee Integration 和 Application Integration 都會提供該連線。您可以在整合中透過「連接器」工作使用連線。

  • 如要瞭解如何在 Apigee Integration 中建立及使用「連接器」工作，請參閱「連接器工作」。
  • 如要瞭解如何在 Application Integration 中建立及使用連接器工作，請參閱「連接器工作」。

動作

本節說明如何在這個連接器中執行部分動作。

MakeDirectory 動作

這項動作會在指定路徑中建立目錄。

MakeDirectory 動作的輸入參數

參數名稱 資料類型 必填 說明
權限 字串 否 建立新目錄的權限。
路徑 字串 是 新目錄的路徑。

如要瞭解如何設定 MakeDirectory 動作，請參閱範例。

ListStatus 動作

這項動作會列出所提供路徑的內容。

ListStatus 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。

如要瞭解如何設定 ListStatus 動作，請參閱範例。

GetHomeDirectory 動作

這項動作會取得目前使用者的主目錄。

GetHomeDirectory 動作的輸入參數

參數名稱 資料類型 必填 說明
connectorInputPayload JSON 是 連接器的輸入酬載。

如要瞭解如何設定 GetHomeDirectory 動作，請參閱範例。

DeleteFile 動作

這項操作會刪除檔案或目錄。

DeleteFile 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。
遞迴 布林值 否 指定是否要刪除資料夾的子資料夾。

如要瞭解如何設定 DeleteFile 動作，請參閱範例。

GetContentSummary 動作

這項動作會取得檔案或資料夾的內容摘要。

GetContentSummary 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案或資料夾的路徑。

如要瞭解如何設定 GetContentSummary 動作，請參閱範例。

RenameFile 動作

這項動作會重新命名檔案或目錄。

RenameFile 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。
目的地 字串 是 指定檔案的新名稱和路徑。

如要瞭解如何設定 RenameFile 動作，請參閱範例。

SetPermission 動作

這項操作會設定路徑的權限。

SetPermission 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。
權限 字串 是 以八進位 (8 進位) 標記法指定 Unix 權限。

如要瞭解如何設定 SetPermission 動作，請參閱範例。

SetPermission 動作

這項操作會設定路徑的權限。

SetPermission 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。
權限 字串 是 以八進位 (8 進位) 標記法指定 Unix 權限。

如要瞭解如何設定 SetPermission 動作，請參閱範例。

SetOwner 動作

這項動作會設定路徑的擁有者和群組。

SetOwner 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。
擁有者 字串 是 路徑的新擁有者。
群組 字串 否 新群組的名稱。

如要瞭解如何設定 SetOwner 動作，請參閱範例。

UploadFile 動作

這項動作會上傳檔案。

UploadFile 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。
內容 字串 是 上傳檔案的內容。

如要瞭解如何設定 UploadFile 動作，請參閱範例。

DownloadFile 動作

這項操作會下載檔案。

DownloadFile 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。
WriteToFile 字串 否 要寫入輸出內容的檔案本機位置。

如要瞭解如何設定 DownloadFile 動作，請參閱範例。

AppendToFile 動作

這項動作會附加檔案。

AppendToFile 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。
內容 字串 是 要附加至檔案的內容。

如要瞭解如何設定 AppendToFile 動作，請參閱範例。

GetFileChecksum 動作

這項動作會取得檔案的總和檢查碼。

GetFileChecksum 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。

如要瞭解如何設定 GetFileChecksum 動作，請參閱範例。

動作範例

本節說明如何執行這個連接器中的部分動作範例。

範例 - 建立目錄

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「MakeDirectory」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    {
  "Path": "/user/hduser"
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "Success": true
}]

範例 - 取得主目錄

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「GetHomeDirectory」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
      {}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "Path": "/user/hduser"
}]

範例 - 刪除檔案

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「DeleteFile」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    {
  "Path": "/user/hduser/testFile"
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "Success": true
}]

範例 - 列出檔案的狀態

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「ListStatus」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    {
  "path": "/user/hduser/deletefile"
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "fileId": 16471.0,
  "PathSuffix": "data.txt",
  "owner": "hduser",
  "group": "supergroup",
  "length": 38.0,
  "permission": "644",
  "replication": 1.0,
  "storagePolicy": 0.0,
  "childrenNum": 0.0,
  "blockSize": 1.34217728E8,
  "modificationTime": "2024-08-16 16:12:01.921",
  "accessTime": "2024-08-16 16:12:01.888",
  "type": "FILE"
}, {
  "fileId": 16469.0,
  "PathSuffix": "file2.txt",
  "owner": "hduser",
  "group": "supergroup",
  "length": 53.0,
  "permission": "644",
  "replication": 1.0,
  "storagePolicy": 0.0,
  "childrenNum": 0.0,
  "blockSize": 1.34217728E8,
  "modificationTime": "2024-08-16 16:12:01.762",
  "accessTime": "2024-08-16 16:12:01.447",
  "type": "FILE"
}]

範例 - 取得檔案的內容摘要

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「GetContentSummary」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    {
  "Path": "/user/hduser/appendtofile"
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

      [{
  "DirectoryCount": "1",
  "FileCount": "1",
  "Length": 52.0,
  "Quota": -1.0,
  "SpaceConsumed": 52.0,
  "SpaceQuota": -1.0,
  "ecpolicy": "",
  "snapshotdirectorycount": "0",
  "snapshotfilecount": "0",
  "snapshotlength": "0",
  "snapshotspaceconsumed": "0"
}]

範例 - 重新命名檔案

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「hdfs_RenameFile_action」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    {
  "Path": "/user/hduser/renamefile_second/file1.txt",
  "Destination": "/user/hduser/renamefile_second/file1rename"
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "Success": true
}]

範例 - 設定檔案權限

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「SetPermission」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    {
  "Path": "/user/hduser/gcpdirectory",
  "Permission": "777"
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "Success": true
}]

範例 - 設定檔案擁有者

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「SetOwner」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    {
  "Path": "/user/hduser/gcpdirectory",
  "Owner": "newowner"
}

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "Success": true
}]

範例 - 上傳檔案

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「UploadFile」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
       { "Path": "/user/newfile9087.txt", "Content": "string" }

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [{
  "Success": true
}]

範例 - 下載檔案

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「DownloadFile」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    { "Path": "/user/sampleFile/file1.txt" }

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [ { "Output": "This is sample File\nfor this testing\ncontent" } ]

範例 - 附加檔案

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「AppendToFile 」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    { "Path": "/user/sampleFile/file1.txt", "Content": "content" }

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [ { "Success": true } ]

範例 - 取得檔案的總和檢查碼

  1. 在 Configure connector task 對話方塊中，按一下 Actions。
  2. 選取「GetFileChecksum 」動作，然後按一下「完成」。
  3. 在「資料對應」區段中 Open Data Mapping Editor，然後在「Input」欄位中輸入類似下列的值： 
    { "Path": "/user/sampleFile/file1.txt" }

    4. 如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似於下列內容：

    [ { "Algorithm": "MD5-of-0MD5-of-512CRC32C", "Bytes": "00000200000000000000000080f5b53ae8c165ae56e86109b8bb2a1700000000", "Length": 28 } ]

實體作業範例

本節說明如何在這個連接器中執行部分實體作業。

範例 - 列出所有檔案的資料

這個範例會擷取 Files 實體中所有檔案的資料。

  1. 在 Configure connector task 對話方塊中，按一下 Entities。
  2. 從 Entity 清單中選取 Object。
  3. 選取 List 作業，然後按一下「完成」。

範例 - 取得權限資料

這個範例會從 Permission 實體取得具有指定 ID 的權限資料。

  1. 在 Configure connector task 對話方塊中，按一下 Entities。
  2. 從 Entity 清單中選取 Permission。
  3. 選取 Get 作業，然後按一下「完成」。
  4. 在「連線器」工作的「工作輸入」部分，按一下「EntityId」，然後在「預設值」欄位中輸入 /user/hduser/appendfile。

    其中 /user/hduser/appendfile 是 Permission 實體的專屬 ID。

向 Google Cloud 社群尋求協助

如要發布問題及討論這個連接器，請前往 Cloud 論壇的 Google Cloud 社群。

後續步驟