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)
如要瞭解如何啟用服務,請參閱「啟用服務」。
如果專案先前未啟用這些服務或權限,系統會在設定連結器時提示您啟用。
設定連接器
連線專屬於資料來源。也就是說,如果您有多個資料來源,則必須為每個資料來源建立個別的連線。如要建立連線,請按照下列步驟操作:
- 在 Cloud 控制台中,前往「Integration Connectors」>「Connections」頁面,然後選取或建立 Google Cloud 專案。
- 按一下「+ 建立新連線」,開啟「建立連線」頁面。
- 在「位置」部分中,選擇連線位置。
- 區域:從下拉式清單中選取位置。
如需所有支援的地區清單,請參閱「位置」一文。
- 點按「下一步」。
- 區域:從下拉式清單中選取位置。
- 在「連線詳細資料」部分,完成下列步驟:
- 連結器:從可用連結器的下拉式清單中選取「Cloud Storage」。
- 連接器版本:從可用版本的下拉式清單中選取連接器版本。
- 在「連線名稱」欄位中,輸入連線執行個體的名稱。
連線名稱必須符合下列條件:
- 連線名稱可使用英文字母、數字或連字號。
- 字母必須為小寫。
- 連線名稱開頭須為英文字母,結尾則須為英文字母或數字。
- 連結名稱不得超過 49 個字元。
- 視需要輸入連線執行個體的「Description」(說明)。
- 或者,可啟用 Cloud Logging,然後選取記錄層級。記錄層級預設為
Error
。 - 服務帳戶:選取具備必要角色的服務帳戶。
- 視需要設定「連線節點設定」:
- 節點數量下限:輸入連線節點數量下限。
- 節點數量上限:輸入連線節點數量上限。
節點是用來處理交易的連線單位 (或備用資源)。連線處理的交易量越多,就需要越多節點;反之,處理的交易量越少,需要的節點就越少。如要瞭解節點對連接器定價的影響,請參閱「 連線節點定價」。如未輸入任何值,系統預設會將節點下限設為 2 (提高可用性),節點上限則設為 50。
- 專案 ID:資料所在的 Google Cloud 專案 ID。
- 選用:按一下「+ 新增標籤」,以鍵/值組合的形式為連線新增標籤。
- 點按「下一步」。
- 查看:查看連結。
- 點選「建立」。
實體、作業和動作
所有整合連接器都會為所連應用程式的物件提供抽象層。您只能透過這個抽象化程序存取應用程式的物件。抽象化會以實體、作業和動作的形式呈現。
- 實體: 實體可以視為已連結應用程式或服務中的物件,或是屬性集合。實體的定義因連接器而異。舉例來說,在資料庫連接器中,資料表是實體;在檔案伺服器連接器中,資料夾是實體;在訊息系統連接器中,佇列是實體。
不過,連接器可能不支援或沒有任何實體,在這種情況下,
Entities
清單會是空白。 - 作業: 作業是指您可以在實體上執行的活動。您可以對實體執行下列任一操作:
從可用清單中選取實體,系統會產生該實體可用的作業清單。如需作業的詳細說明,請參閱 Connectors 工作的實體作業。 不過,如果連接器不支援任何實體作業,系統就不會在
Operations
清單中列出這些不支援的作業。 - 動作: 動作是透過連接器介面提供給整合的第一類函式。動作可讓您變更一或多個實體,且因連接器而異。一般來說,動作會有一些輸入參數和輸出參數。不過,連接器可能不支援任何動作,此時
Actions
清單會是空白。
系統限制
Google Cloud Storage 連接器每秒最多可處理 10 筆交易 (每個節點),並節流任何超出此限制的交易。根據預設,Integration Connectors 會為連線分配 2 個節點 (以提高可用性)。
如要瞭解 Integration Connectors 適用的限制,請參閱「限制」一文。
動作
Google Cloud Storage 連線支援下列動作:
DownloadObject 動作
下表說明 DownloadObject
動作的輸入參數。
參數名稱 | 必填 | 資料類型 | 說明 |
---|---|---|---|
值區 | 是 | 字串 | 包含要下載物件的值區名稱。 |
ObjectFilePath | 否 | 字串 | 要下載的物件名稱。如未指定,系統會下載指定 bucket 中的所有物件。
如果要下載的物件位於 bucket 的子資料夾中,您必須提供該物件的完整路徑。舉例來說,如要下載 |
HasBytes | 否 | 布林值 | 是否要以位元組為單位下載內容。有效值為 true 或 false 。
如果設為 true ,內容會以 Base64 編碼字串的形式下載。
根據預設, |
UpdatedEndDate | 否 | 日期 | 下載物件的結束日期範圍。如未指定,系統會從指定的 UpdatedStartDate 下載物件,直到目前為止。 |
UpdatedStartDate | 否 | 日期 | 下載物件的日期範圍開始時間。如未指定,系統會從時間的開頭下載物件,直到 UpdatedEndDate 為止。 |
如需如何設定 DownloadObject
動作的範例,請參閱「範例」。
UploadObject 動作
下表說明 UploadObject
動作的輸入參數。
參數名稱 | 必填 | 資料類型 | 說明 |
---|---|---|---|
值區 | 是 | 字串 | 要上傳物件的值區名稱。 |
FolderPath | 否 | 字串 | 物件應上傳至的資料夾路徑。 |
ContentBytes | 否 | 字串 | 以位元組形式上傳的內容 (Base64 編碼字串)。 |
HasBytes | 否 | 布林值 | 是否要以位元組形式上傳內容。有效值為 true 或 false 。
如果設為 true ,您要上傳的內容應為 Base64 編碼字串。
根據預設, |
內容 | 是 | 字串 | 要上傳的內容。 |
ObjectName | 否 | 字串 | 要上傳的物件名稱。 |
如需如何設定 UploadObject
動作的範例,請參閱「範例」。
CopyObject 動作
下表說明 CopyObject
動作的輸入參數。
參數名稱 | 必填 | 資料類型 | 說明 |
---|---|---|---|
BucketSource | 是 | 字串 | 要複製物件的值區名稱。 |
ObjectSource | 是 | 字串 | 要複製物件的資料夾完整路徑。 |
BucketDestination | 是 | 字串 | 要將物件複製到的值區名稱。 |
ObjectDestination | 否 | 字串 | 目的地完整路徑,包括物件名稱。如未指定任何物件名稱,系統會保留來源物件的名稱。 |
如需如何設定 CopyObject
動作的範例,請參閱「範例」。
MoveObject 動作
下表說明 MoveObject 動作的輸入參數。
參數名稱 | 必填 | 資料類型 | 說明 |
---|---|---|---|
BucketSource | 是 | 字串 | 要從中移動物件的值區名稱。 |
ObjectSource | 是 | 字串 | 要將物件移至的資料夾完整路徑。 |
BucketDestination | 是 | 字串 | 要將物件移至的值區名稱。 |
ObjectDestination | 否 | 字串 | 目的地完整路徑,包括物件名稱。如未指定任何物件名稱,系統會保留來源物件的名稱。 |
DeleteObject 動作
下表說明 DeleteObject
動作的輸入參數。
參數名稱 | 必填 | 資料類型 | 說明 |
---|---|---|---|
BucketSource | 是 | 字串 | 要刪除的物件所在的值區名稱。 |
ObjectSource | 是 | 字串 | 要刪除的物件名稱。 |
產生 | 否 | 雙精度值 | 要刪除的物件版本。如果存在,則會永久刪除指定修訂版本的物件,而非最新版本 (預設行為)。 |
IfGenerationMatch | 否 | 雙精度值 | 根據物件的目前世代是否與指定值相符,有條件地執行刪除作業。如果將這個值設為 |
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
- 將物件上傳至資料夾
- 複製物件
- 移動物件
- 刪除物件
- 為物件建立已簽署的網址
下表列出範例情境,以及「連線器」工作中的對應設定:
工作 | 設定 |
---|---|
列出所有物件 |
這會列出所有值區中的所有物件。物件會列在 |
列出值區中的所有物件 |
|
使用名稱的 LIKE 篩選器列出物件 |
|
列出所有值區 |
|
下載物件 |
這個範例會下載 |
下載二進位物件 |
下載二進位物件的步驟與先前所述下載一般物件的步驟相同。此外,您必須在 { "Bucket": "bucket-test-01", "ObjectFilePath": "image01.png", "HasBytes" : true } 如果下載成功, { "Success": "true", "ContentBytes": "SGVsbG8gdGVzdCE\u003d" } 根據預設, 如果檔案含有特殊字元,例如 ä、Ø、Thành,請按照下列步驟操作:
|
將二進位物件上傳至 bucket |
這個範例會在 |
將物件上傳至 bucket |
這個範例會在 |
將物件上傳至資料夾 |
這個範例會在 |
複製物件 |
這個範例會將 如果複製成功, { "Success": "true" } |
移動物件 |
這個範例會將 如果複製成功, { "Success": "true" } |
刪除物件 |
這個範例會從 如果複製成功, { "Success": "true" } |
為物件建立已簽署的網址 |
這個範例會為 { "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 中建立及使用「連線器」工作,請參閱「連線器工作」。