Cloud Storage

Google Cloud Storage 連接器可讓您連線至 Google Cloud Storage，並執行檔案傳輸作業。

事前準備

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

  • 在 Google Cloud 專案中：
    • 確認已設定網路連線。如要瞭解網路模式，請參閱「網路連線」。
    • 將 roles/connectors.admin IAM 角色授予設定連線器的使用者。
    • 將下列 IAM 角色授予要用於連接器的服務帳戶：
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor
      • roles/storage.admin

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

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

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

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

設定連接器

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

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

    前往「Connections」(連線) 頁面

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

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

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

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

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

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

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

    8. 專案 ID：資料所在的 Google Cloud 專案 ID。
    9. 選用：按一下「+ 新增標籤」，以鍵/值組合的形式為連線新增標籤。
    10. 點按「下一步」。
  5. 查看：查看連結。
  6. 點選「建立」。

實體、作業和動作

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

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

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

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

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

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

系統限制

Google Cloud Storage 連接器每秒最多可處理 10 筆交易 (每個節點)，並節流任何超出此限制的交易。根據預設，Integration Connectors 會為連線分配 2 個節點 (提高可用性)。

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

動作

Google Cloud Storage 連線支援下列動作：

DownloadObject 動作

下表說明 DownloadObject 動作的輸入參數。

參數名稱 必填 資料類型 說明
值區 是 字串 包含要下載物件的值區名稱。
ObjectFilePath 否 字串 要下載的物件名稱。如未指定，系統會下載指定 bucket 中的所有物件。

如果要下載的物件位於 bucket 的子資料夾中，您必須提供該物件的完整路徑。舉例來說，如要下載 bucket_01，該物件必須位於 bucket_01 的 folderA 中，物件路徑應為 folderA/logfile.txt。 logfile.txt
HasBytes 否 布林值 是否要以位元組為單位下載內容。有效值為 true 或 false。 如果設為 true，內容會以 Base64 編碼字串的形式下載。

根據預設，HasBytes 欄位會設為 false。
UpdatedEndDate 否 日期 下載物件的結束日期範圍。如未指定，系統會從指定的 UpdatedStartDate下載物件，直到目前為止。
UpdatedStartDate 否 日期 下載物件的日期範圍開始時間。如未指定，系統會從時間的開頭下載物件，直到 UpdatedEndDate 為止。

如需如何設定 DownloadObject 動作的範例，請參閱「範例」。

UploadObject 動作

下表說明 UploadObject 動作的輸入參數。

參數名稱 必填 資料類型 說明
值區 是 字串 要上傳物件的值區名稱。
FolderPath 否 字串 物件應上傳至的資料夾路徑。
ContentBytes 否 字串 以位元組形式上傳的內容 (Base64 編碼字串)。
HasBytes 否 布林值 是否要以位元組形式上傳內容。有效值為 true 或 false。 如果設為 true，您要上傳的內容應為 Base64 編碼字串。

根據預設，HasBytes 欄位會設為 false。
內容 是 字串 要上傳的內容。
ObjectName 否 字串 要上傳的物件名稱。

如需如何設定 UploadObject 動作的範例，請參閱「範例」。

CopyObject 動作

下表說明 CopyObject 動作的輸入參數。

參數名稱 必填 資料類型 說明
BucketSource 是 字串 要複製物件的值區名稱。
ObjectSource 是 字串 要複製物件的資料夾完整路徑。
BucketDestination 是 字串 要將物件複製到的值區名稱。
ObjectDestination 否 字串 目的地完整路徑，包括物件名稱。如未指定任何物件名稱，系統會保留來源物件的名稱。

如需如何設定 CopyObject 動作的範例，請參閱「範例」。

MoveObject 動作

下表說明 MoveObject 動作的輸入參數。

參數名稱 必填 資料類型 說明
BucketSource 是 字串 要從中移動物件的值區名稱。
ObjectSource 是 字串 要將物件移至的資料夾完整路徑。
BucketDestination 是 字串 要將物件移至的值區名稱。
ObjectDestination 否 字串 目的地完整路徑，包括物件名稱。如未指定任何物件名稱，系統會保留來源物件的名稱。

DeleteObject 動作

下表說明 DeleteObject 動作的輸入參數。

參數名稱 必填 資料類型 說明
BucketSource 是 字串 要刪除的物件所在的值區名稱。
ObjectSource 是 字串 要刪除的物件名稱。
產生 否 雙精度值 要刪除的物件版本。如有此參數，系統會刪除指定版本的物件，而非最新版本 (預設行為)。
IfGenerationMatch 否 雙精度值 根據物件的目前世代是否與指定值相符，有條件地執行刪除作業。如果將這個值設為 0，只有在物件沒有使用中版本時，作業才會成功。
IfGenerationNotMatch 否 雙精度值 如果物件的目前世代與指定值不符，則刪除作業會成為條件式作業。如果沒有使用中物件，前提條件就會失敗。如果將這個值設為 0，則只有在物件有使用中版本時，作業才會成功。
IfMetagenerationMatch 否 雙精度值 根據物件目前的元代碼是否符合指定值，決定是否執行刪除作業。
IfMetagenerationNotMatch 否 雙精度值 如果物件目前的 metageneration 與指定值不符，則刪除作業會成為條件式作業。

SignURL 動作

下表說明 SignURL 動作的輸入參數，該動作會為指定物件建立已簽署網址。

參數名稱 必填 資料類型 說明
值區 是 字串 物件所在的值區名稱。
物件 是 字串 要產生 SignedURL 的物件名稱。
RequestMethod 否 字串 簽署要求將使用的方法。預設值為 GET。
位置 否 字串 指定 bucket 的位置。預設值為 auto。
ActiveDateTime 否 字串 SignedURL 生效的日期和時間。如未指定，系統會使用目前的日期時間。
查詢 否 字串 使用 SignedURL 時必須加入的查詢字串，如果未指定，系統就不會使用任何查詢字串。
CustomHeaders 否 字串 以半形逗號分隔的標頭名稱=值清單，用於 SignedURL，如果未指定，則不會使用自訂標頭。
ExpiresIn 是 字串 SignedURL 的到期時間應採用 1d2h3m4s 格式，最大值為 7d0h0m0s。
HMAC 存取權 ID 是 字串 HMAC 存取權 ID。詳情請參閱「HMAC 金鑰」。
HMAC 密鑰 是 字串 HMAC 密鑰。

範例

本節中的範例說明下列作業：

  • 列出所有物件
  • 列出值區中的所有物件
  • 使用名稱的 LIKE 篩選器列出物件
  • 列出所有值區
  • 下載物件
  • 下載二進位物件
  • 將二進位物件上傳至 bucket
  • 將物件上傳至 bucket
  • 將物件上傳至資料夾
  • 複製物件
  • 移動物件
  • 刪除物件
  • 為物件建立已簽署的網址

下表列出範例情境，以及「連線器」工作中的對應設定：

工作 設定
列出所有物件
  1. 在「Configure connector task」對話方塊中，按一下 Entities。
  2. 選取 Objects 實體，然後選取 List 作業。
  3. 按一下 [完成]。

這會列出所有值區中的所有物件。物件會列在 Connectors 工作的 connectorOutputPayload 回應參數中。
列出值區中的所有物件
  1. 在「Configure connector task」對話方塊中，按一下 Entities。
  2. 選取 Objects 實體，然後選取 List 作業。
  3. 按一下 [完成]。
  4. 將 filterClause 設為要列出物件的值區名稱。如要設定子句，請在 Connectors 工作的 Task Input 部分中，按一下「filterClause」，然後在「Default Value」(預設值) 欄位中輸入 Bucket = 'BUCKET_NAME'。 例如：Bucket = 'bucket_01'。
使用名稱的 LIKE 篩選器列出物件
  1. 在「Configure connector task」對話方塊中，按一下 Entities。
  2. 選取 Objects 實體，然後選取 List 作業。
  3. 按一下 [完成]。
  4. 將 filterClause 設為要列出物件的值區名稱。如要設定子句，請在 Connectors 工作的 Task Input 部分中，按一下「filterClause」，然後在「Default Value」(預設值) 欄位中輸入 Name LIKE 'NAME%' AND Bucket = 'BUCKET_NAME'。

    例如 Name LIKE 'Operations%' AND Bucket = 'OperationsBucket'。
列出所有值區
  1. 在「Configure connector task」對話方塊中，按一下 Entities。
  2. 選取 Buckets 實體，然後選取 List 作業。
  3. 按一下 [完成]。
下載物件
  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 DownloadObject 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：
    {
  "Bucket": "bucket-test-01",
  "ObjectFilePath": "logfile.txt"
}

    4. 這個範例會下載 logfile.txt 檔案。下載的檔案內容會以 JSON 格式提供給您，位於 Connectors 工作 connectorOutputPayload 的回應參數中。
下載二進位物件

下載二進位物件的步驟與先前所述下載一般物件的步驟相同。此外，您必須在 connectorInputPayload 欄位中將 HasBytes 指定為 true。這會將物件下載為 Base64 編碼的字串。 connectorInputPayload 欄位的範例值：

{
"Bucket": "bucket-test-01",
"ObjectFilePath": "image01.png",
"HasBytes" : true
}

如果下載成功，connectorOutputPayload 欄位的輸出內容會類似下列內容：

{
"Success": "true",
"ContentBytes": "SGVsbG8gdGVzdCE\u003d"
}

根據預設，HasBytes 欄位會設為 false。

如果檔案含有特殊字元，例如 ä、Ø、Thành，請按照下列步驟操作：

  1. 以 UTF-8 編碼：以 UTF-8 編碼檔案，處理特殊字元。
  2. 轉換為 Base64：將檔案轉換為 Base64，確保原始文字保持完整。
  3. 解碼 Base64 字串：將檔案解碼為 Base64 字串，即可擷取含有特殊字元的原始值。
將二進位物件上傳至 bucket
  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 UploadObject 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入下列內容：
    {
"ContentBytes": "SGVsbG8gVGVzdCE=",
"Bucket": "bucket-test-01",
"ObjectName" : "test-file-01",
"HasBytes": true
}

    4. 這個範例會在 bucket-test-01 bucket 中建立 test-file-01 檔案。如果已有 test-file-01 名稱的檔案，系統會覆寫該檔案。
將物件上傳至 bucket
  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 UploadObject 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入下列內容：
    {
"Content": "Hello test!",
"Bucket": "bucket-test-01",
"ObjectName" : "test-file-01.txt"
}

    4. 這個範例會在 bucket-test-01 bucket 中建立 test-file-01.txt 檔案，並加入 Hello test! 內容。如果已有 test-file-01.txt 名稱的檔案，系統會覆寫該檔案。
將物件上傳至資料夾
  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 UploadObject 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入下列內容：
    {
"Content": "Hello test!",
"Bucket": "bucket-test-01",
"FolderPath": "folderA",
"ObjectName": "test-file-01.txt"
}

    4. 這個範例會在 bucket-test-01 的 folderA 資料夾中，建立包含 Hello test! 內容的 test-file-01.txt 檔案。如果資料夾中已有 test-file-01.txt 名稱的檔案，系統會覆寫該檔案。
複製物件
  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 CopyObject 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入下列內容：
    {
"BucketSource": "bucket_01",
"ObjectSource": "folderA/logfile.txt",
"BucketDestination": "bucket_02",
"ObjectDestination": "folderB/logfile.txt"
}

    4. 這個範例會將 folderA/logfile.txt 檔案從 bucket_01 複製到 bucket_02 中的 folderB/logfile.txt。

如果複製成功，connectorOutputPayload 欄位的輸出內容會類似於下列內容：

{
"Success": "true"
}
移動物件
  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 MoveObject 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入下列內容：
    {
"BucketSource": "bucket_01",
"ObjectSource": "folderA/logfile.txt",
"BucketDestination": "bucket_02",
"ObjectDestination": "folderB/logfile.txt"
}

    4. 這個範例會將 folderA/logfile.txt 檔案從 bucket_01 移至 bucket_02 中的 folderB/logfile.txt。

如果複製成功，connectorOutputPayload 欄位的輸出內容會類似於下列內容：

{
"Success": "true"
}
刪除物件
  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 DeleteObject 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入下列內容：
    {
"BucketSource": "bucket_01",
"ObjectSource": "logfile.txt"
}

    4. 這個範例會從 bucket_01 刪除 logfile.txt 檔案。

如果複製成功，connectorOutputPayload 欄位的輸出內容會類似於下列內容：

{
"Success": "true"
}
為物件建立已簽署的網址
  1. 在「Configure connector task」對話方塊中，按一下 Actions。
  2. 選取 SignURL 動作，然後按一下「完成」。
  3. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入下列內容：
    {
"Bucket": "bucket-test-01",
"ObjectName" : "test-file-01.txt"
}

    4. 這個範例會為 bucket-test-01 值區中的 test-file-01.txt 檔案建立已簽署的網址。如果動作成功，您會在回應中取得簽署網址，類似以下內容：

    {
"Success": "true",
"SignURL": "https://storage.googleapis.com/example-bucket/cat.jpeg?X-Goog-Algorithm=
GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com
%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T18
1309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f16
9edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa849
6def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dc
c1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c2058
0e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a
66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823
a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b13344703
2ea7abedc098d2eb14a7"
}

注意事項

  • 可下載物件的大小上限為 10 MB。
  • 您無法使用 UploadObject 動作上傳多個檔案。只能上傳單一檔案。

使用 Terraform 建立連線

您可以使用 Terraform 資源建立新連線。

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

如要查看用於建立連線的 Terraform 範本範例，請參閱範本範例。

使用 Terraform 建立這項連線時，您必須在 Terraform 設定檔中設定下列變數：

參數名稱 資料類型 必填 說明
project_id STRING 是 資料所在的 Google Cloud 專案 ID。

在整合中建立 Cloud Storage 連線

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

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

向 Google Cloud 社群尋求協助

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

後續步驟