Azure Data Lake Storage

Azure Data Lake Storage 連接器可讓您連線至 Azure Data Lake Storage，並使用 SQL 擷取及更新 Azure Data Lake Storage 資料。

事前準備

使用 Azure Data Lake Storage 連接器前，請先完成下列工作：

  • 在 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)

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

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

  • 如要瞭解如何建立 Azure 儲存體帳戶，請參閱「建立儲存體帳戶」。如要瞭解如何在 Azure 中建立容器，請參閱「建立容器」。如要瞭解如何在 Azure 中建立目錄，請參閱「建立目錄」。

設定連接器

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

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

    前往「Connections」(連線) 頁面

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

      連接器支援的地區包括：

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

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

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

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

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

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

    8. 帳戶：這項屬性會指定 Azure Data Lake Storage 帳戶的名稱。
    9. 目錄：這個屬性會指定列出檔案和資料夾的根路徑。
    10. 檔案系統：這個屬性會指定第 2 代儲存空間帳戶中使用的檔案系統名稱。例如 Azure Blob 容器的名稱。
    11. 區塊大小：上傳大型檔案時使用的區塊大小 (以 MB 為單位)。
    12. 包含子目錄：選擇是否要在 ADLSGen2 架構的「資源」檢視畫面中列出子目錄路徑。
    13. (選用) 按一下「+ 新增標籤」，以鍵/值組合的形式為連線新增標籤。
    14. 點選「下一步」。
  5. 在「Authentication」(驗證) 部分，輸入驗證詳細資料。
    1. 選取「驗證類型」並輸入相關詳細資料。

      Azure Data Lake Storage 連線支援下列驗證類型：

      • 共用存取簽章
      • 帳戶存取金鑰
      • JWT 驗證

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

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

設定驗證機制

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

  • 共用存取簽章
    • 共用存取簽章：包含共用存取簽章的 Secret Manager 密鑰。
  • 帳戶存取金鑰
    • 帳戶存取金鑰：內含帳戶存取金鑰的 Secret Manager 密鑰。
  • JWT 驗證
    • 用戶端 ID：用於要求存取權杖的用戶端 ID。
    • 私密金鑰：Secret Manager 密鑰，內含 PEM 格式的私密金鑰檔案內容。私密金鑰必須與公開金鑰/憑證相符。
    • 私密金鑰密碼：Secret Manager 密鑰，內含私密金鑰檔案的密碼 (同義詞)。

連線設定範例

本節列出建立 Azure Data Lake Storage 連線時，您設定的各個欄位範例值。

共用存取簽章連線類型

Fieldname 詳細資料
位置 us-central1
連接器 azuredatalakestorage
連接器版本 1
連線名稱 adls-gen2-conn-public
啟用 Cloud Logging 是
服務帳戶 account@my-project.iam.gserviceaccount.com
帳戶 google-cloud-dslgen3
目錄 目錄
檔案系統 容器
包含子目錄 否
節點數量下限 2
節點數量上限 50
共用存取簽章 SHARED_ACCESS_SIGNATURE
Secret 版本 1

帳戶存取金鑰連線類型

Fieldname 詳細資料
位置 us-central1
連接器 azuredatalakestorage
連接器版本 1
連線名稱 azure-data-lake-conn
啟用 Cloud Logging 是
服務帳戶 account@my-project.iam.gserviceaccount.com
帳戶 google-cloud-dslgen3
目錄 北美洲
檔案系統 容器
包含子目錄 否
節點數量下限 2
節點數量上限 50
帳戶存取金鑰 ACCOUNT_ACCESS_KEY
Secret 版本 1

JWT 驗證連線類型

Fieldname 詳細資料
位置 us-central1
連接器 azuredatalakestorage
連接器版本 1
連線名稱 adls-gen2-jwt-conn
啟用 Cloud Logging 是
服務帳戶 account@my-project.iam.gserviceaccount.com
帳戶 your-adls-account-name
目錄 北美洲
檔案系統 data-lake-container
包含子目錄 是
節點數量下限 2
節點數量上限 50
驗證類型 JWT 驗證
用戶端 ID CLIENT_ID
私密金鑰 PRIVATE_KEY_SECRET
私密金鑰密碼 PRIVATE_KEY_PASSWORD_SECRET
密鑰版本 (適用於私密金鑰) 1
密鑰版本 (適用於私密金鑰密碼) 1

實體、作業和動作

所有整合連接器都會為所連應用程式的物件提供抽象層。您只能透過這個抽象化程序存取應用程式的物件。抽象化會以實體、作業和動作的形式呈現。

  • 實體： 實體可以視為已連結應用程式或服務中的物件，或是屬性集合。實體的定義因連接器而異。舉例來說，在資料庫連接器中，資料表是實體；在檔案伺服器連接器中，資料夾是實體；在訊息系統連接器中，佇列是實體。

    不過，連接器可能不支援或沒有任何實體，在這種情況下，Entities 清單會是空白。

  • 作業： 作業是指您可以在實體上執行的活動。您可以對實體執行下列任一操作：

    從可用清單中選取實體，系統會產生該實體可用的作業清單。如需作業的詳細說明，請參閱 Connectors 工作的實體作業。 不過，如果連接器不支援任何實體作業，系統就不會在 Operations 清單中列出這些不支援的作業。

  • 動作： 動作是透過連接器介面提供給整合的第一類函式。動作可讓您變更一或多個實體，且因連接器而異。一般來說，動作會有一些輸入參數和輸出參數。不過，連接器可能不支援任何動作，此時 Actions 清單會是空白。

系統限制

Azure Data Lake Storage 連接器每秒可處理 5 筆交易，每個節點也是如此，且會節流任何超出此限制的交易。根據預設，Integration Connectors 會為連線分配 2 個節點 (提高可用性)。

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

動作

本節列出連接器支援的動作。如要瞭解如何設定動作，請參閱「動作範例」。

DownloadFile 動作

這項操作可讓您從目錄或容器下載特定 Blob 的內容。

DownloadFile 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 要下載的檔案路徑 (包括檔案名稱)。例如：
  • FILE_NAME
  • dir1/FILE_NAME
  • dir1/dir2/FILE_NAME
HasBytes 布林值 否 是否要以位元組 (Base64 格式) 下載內容。
  • 如要下載非文字檔案 (例如 .pdf、.xls 和 .docx)，您必須將 HasBytes 設為 true。
  • 如要下載文字檔，您可以將 HasBytes 設為 true 或 false。如果將值設為 true，系統會以位元組 (Base64 格式) 下載文字內容。
這個參數的預設值為 false。

DownloadFile 動作的輸出參數

如果動作成功，系統會傳回檔案或 Blob 的內容。

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

CreateFile 動作

這項動作可讓您在容器或目錄中建立 Blob 或檔案。

CreateFile 動作的輸入參數

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

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

CopyFile 動作

這項動作可讓您將檔案或 Blob 的內容複製到相同容器或目錄中的另一個檔案或 Blob。

CopyFile 動作的輸入參數

參數名稱 資料類型 必填 說明
來源路徑 字串 是 要複製的檔案路徑。
DestinationPath 字串 是 要複製檔案的路徑。

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

DeleteObject 動作

這項動作可讓您刪除檔案或 Blob。

DeleteObject 動作的輸入參數

參數名稱 資料類型 必填 說明
遞迴 字串 否 將此項設為 true，即可刪除資料夾的所有內容，包括任何子資料夾。
路徑 字串 是 要刪除的檔案或資料夾路徑。
DeleteType 字串 是
  • 將此參數設為 FILESANDFOLDERS，即可刪除 Path 參數中指定的檔案或資料夾。
  • 將此參數設為 FILES，即可只刪除 Path 參數中指定資料夾內的檔案。

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

LeaseBlob 動作

這個動作可讓您建立及管理 Blob 的鎖定。

LeaseBlob 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 檔案路徑。
LeaseAction 字串 是 指定要執行的租約動作。
LeaseDuration 整數 是 指定租約期限。

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

UploadFile 動作

這項動作可讓使用者將內容上傳至特定 Blob 或容器。

UploadFile 動作的輸入參數

參數名稱 資料類型 必填 說明
路徑 字串 是 要上傳的檔案路徑。
HasBytes 布林值 否 是否要以位元組形式上傳內容。
內容 字串 是 要上傳的內容。

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

RenameObject 動作

這項操作可讓你重新命名檔案或資料夾。

RenameObject 動作的輸入參數

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

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

動作範例

範例 - 下載檔案

這個範例會下載二進位檔案。

  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 DownloadFile 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
"Path": "testdirectory1/test1.pdf",
"HasBytes": true
}

    4. 如果動作成功，DownloadFile 工作項目的 connectorOutputPayload 回應參數會包含類似下列內容的值：

    [{
"Success": "True",
"ContentBytes": "UEsDBBQABgAIAAAAIQCj77sdZQEAAFIFAAATAAgCW0NvbnRlbnRfVHlwZXNdLnhtbCCiBAIooA"
}]

範例 - 上傳檔案

這個範例會將內容上傳為 Blob。

  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 UploadFile 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
"Path": "testblob4",
"HasBytes": true,
"Content": "abcdef\nabcdef"
}

    4. 如果動作成功，UploadFile 工作項目的 connectorOutputPayload 回應參數會包含類似下列內容的值：

    [{
"Success": "true"
}]

範例 - 建立檔案

這個範例會在指定目錄中建立檔案。

  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 CreateFile 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
"path": "testdirectory1/testblob"
}

    4. 如果動作成功，CreateFile 工作項目的 connectorOutputPayload 回應參數會包含類似下列內容的值：

    [{
"Success": "true"
}]

範例 - 複製檔案

這個範例會將檔案從一個位置複製到另一個位置。

  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 CopyFile 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
"SourcePath": "testdirectory1/testblob",
"DestinationPath": "testblob"
}

    4. 如果動作成功，CopyFile 工作項目的 connectorOutputPayload 回應參數會包含類似下列內容的值：

    [{
"Success": "true"
}]

範例 - 刪除 Blob

這個範例會刪除指定的 Blob。

  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 DeleteObject 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
"path": "testdirectory1/testblob"
}

    4. 如果動作成功，DeleteObject 工作項目的 connectorOutputPayload 回應參數會包含類似下列內容的值：

    [{
"Success": "true"
}]

範例 - 租用 Blob

這個範例會租用指定的 Blob。

  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 LeaseBlob 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
"Path": "testblob2",
"LeaseAction": "Acquire",
"LeaseDuration": 60.0
}

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

    [{
"LeaseId": "7aae9ca2-f015-41b6-9bdf-5fd3401fc493",
"Success": "true"
}]

範例 - 重新命名 Blob

這個範例會重新命名 Blob。

  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 RenameObject 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
"Path": "testblob",
"RenameTo": "testblob6"
}

    4. 如果動作成功，RenameObject 工作項目的 connectorOutputPayload 回應參數會包含類似下列內容的值：

    [{
"Success": true
}]

實體作業範例

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

範例 - 列出所有記錄

這個範例會列出 Resource 實體中的所有記錄。

  1. 在「Configure connector task」對話方塊中，按一下 Entities。
  2. 從 Entity 清單中選取 Resource。
  3. 選取「List」作業，然後按一下「完成」。
  4. (選用) 在「連結器」工作的「工作輸入」部分，您可以指定篩選子句，篩選結果集。 請一律在單引號 (') 內指定篩選子句值。

範例 - 取得記錄

這個範例會從 Resource 實體取得具有指定 ID 的記錄。

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

    其中 testdirectory1/testblob1 是 Resource 實體中的專屬記錄 ID。

在整合中，使用 Azure Data Lake Storage 連線

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

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

向 Google Cloud 社群尋求協助

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

後續步驟