HTTP
HTTP 連接器提供 HTTP 服務的連線能力,讓您使用以 HTTP 為基礎的 API。連接器也支援透過自訂設定建立 SSL/TLS 連線,以及 OAuth 2.0 用戶端憑證授權、基本和摘要等各種驗證機制。
事前準備
使用 HTTP 連接器前,請先完成下列工作:
- 在 Google Cloud 專案中:
- 確認已設定網路連線。如要瞭解網路模式,請參閱「網路連線」。
- 將 roles/connectors.admin IAM 角色授予設定連接器的使用者。
- 將下列 IAM 角色授予要用於連接器的服務帳戶:
roles/secretmanager.viewerroles/secretmanager.secretAccessor
服務帳戶是特殊的 Google 帳戶類型,主要用於代表非人類使用者,需要通過驗證並取得授權,才能存取 Google API 中的資料。如果您沒有服務帳戶,則必須建立服務帳戶。連接器和服務帳戶必須屬於同一個專案。詳情請參閱「建立服務帳戶」。
- 啟用下列服務:
secretmanager.googleapis.com(Secret Manager API)connectors.googleapis.com(Connectors API)
如要瞭解如何啟用服務,請參閱「啟用服務」。
如果專案先前未啟用這些服務或權限,系統會在設定連接器時提示您啟用。
設定連接器
連結是資料來源專屬。也就是說,如果您有多個資料來源,就必須為每個資料來源建立個別連線。如要建立連線,請按照下列步驟操作:
- 在 Cloud 控制台中,前往「Integration Connectors」>「Connections」頁面,然後選取或建立 Google Cloud 專案。
- 按一下「+ 新建」,開啟「建立連線」頁面。
- 在「Location」(位置) 部分,選擇連線的位置。
- 「Region」(區域):從下拉式選單中選取位置。
如需所有支援的地區清單,請參閱「位置」。
- 點選「下一步」。
- 「Region」(區域):從下拉式選單中選取位置。
- 在「Connection Details」(連線詳細資料) 部分,完成下列操作:
- 連接器:從可用連接器的下拉式清單中,選取「HTTP」。
- 連接器版本:從可用版本的下拉式清單中選取連接器版本。
- 在「Connection Name」(連線名稱) 欄位中,輸入連線執行個體的名稱。
連線名稱必須符合下列條件:
- 連線名稱可以使用英文字母、數字或連字號。
- 英文字母必須為小寫。
- 連線名稱的開頭須為英文字母,結尾則須為英文字母或數字。
- 連線名稱不得超過 49 個字元。
- 視需要輸入連線執行個體的說明。
- 視需要啟用「Cloud logging」(Cloud Logging),然後選取記錄層級。記錄層級預設為
Error。 - 服務帳戶:選取具備必要角色的服務帳戶。
- 如要檢查連線狀態,您可以在「Status Check」(狀態檢查) 欄位中指定端點網址。網址也可以包含端點連結 IP 位址。狀態預設為有效。
- 視需要設定連線節點設定:
- 「Minimum number of nodes」(節點數量下限):輸入連線節點數量下限。
- Maximum number of nodes (節點數量上限):輸入連線節點數量上限。
節點是用來處理交易的連線單位 (或副本)。處理的交易量越多,就需要越多節點。反之,處理的交易量越少,需要的節點就越少。如要瞭解節點對連接器定價的影響,請參閱「連線節點定價」。如未輸入任何值,節點數量下限預設為 2 (可提高可用性),節點數量上限則預設為 50。
- 使用 Proxy:勾選核取方塊,為連線設定 Proxy 伺服器。
- (選用) 按一下「+ 新增標籤」,以鍵/值組合的形式為連線新增標籤。
- 如要使用 SSL,請選取「啟用 SSL」。系統隨即會顯示 SSL 設定詳細資料。
- 選取信任存放區類型。可以是「公開」、「私人」或「不安全連線」。
- 根據所選信任存放區,選取顯示的憑證。
- 如果您使用自行簽署的憑證或私人信任存放區憑證,請將根憑證儲存為 Secret Manager 密鑰,格式為 PEM (隱私強化郵件),然後在「Custom Trust Store」(自訂信任存放區) 中選取所需密鑰。
- 如果您使用 mTLS,請在「Key Store」(金鑰儲存庫) 部分選取金鑰儲存庫憑證。
- 視需要選取 TLS 版本。
- 輸入支援的加密套件。輸入多個加密套件,並以半形逗號分隔。詳情請參閱「支援的加密套件」。
- 按一下「Next」。
- 在「Destinations」(目的地) 部分,輸入要連線的遠端主機 (後端系統) 詳細資料。
- 目的地類型:選取「目的地類型」。
- 如要指定目的地主機名稱或 IP 位址,請選取「Host address」(主機位址),然後在「host 1」(主機 1) 欄位中輸入位址。
- 如要建立私人連線,請選取「Endpoint attachment」(端點連結)。在「Endpoint Attachment」(端點連結) 清單中,選取為後端系統建立的端點連結。
如要建立公開連線至後端系統,並提高安全性,可以考慮為連線設定靜態傳出 IP 位址,然後設定防火牆規則,只將特定靜態 IP 位址加入許可清單。
如要輸入其他目的地,請按一下「+ 新增目的地」。
- 點選「下一步」。
- 目的地類型:選取「目的地類型」。
-
在「Authentication」(驗證) 部分,輸入驗證詳細資料。
- 選取「Authentication type」(驗證類型),然後輸入相關詳細資料。
HTTP 連線支援下列驗證類型:
- 自訂驗證
- OAuth 2.0 - 用戶端憑證授權
- 基本驗證
- 摘要驗證
- OAuth 2.0 - 授權碼
- 服務帳戶
- 服務帳戶 ID 權杖驗證
- API 金鑰驗證
- 點選「下一步」。
如要瞭解如何設定這些驗證類型,請參閱「設定驗證」。
- 選取「Authentication type」(驗證類型),然後輸入相關詳細資料。
- 查看:查看連線和驗證詳細資料。
- 按一下 [Create] (建立)。
設定驗證機制
根據要使用的驗證方式輸入詳細資料。
- 自訂驗證
執行連接器工作時,可將自訂授權詳細資料新增為要求標頭。
- OAuth 2.0 - 用戶端憑證授權
- 用戶端 ID:用於驗證 HTTP 要求的用戶端 ID。
- 用戶端密鑰:Secret Manager 密鑰,內含用於驗證 HTTP 要求的用戶端密鑰。
- 存取權杖的要求格式:向驗證伺服器擷取存取權杖時,要求所使用的格式。
選取
body,將用戶端 ID 和 Secret 做為要求主體傳遞,或選取header,將其做為編碼標頭傳遞。 - 權杖要求路徑:要附加至驗證伺服器網址的要求路徑,用於擷取存取權杖網址。
- Default Expiration Time:存取權杖的預設到期時間 (以秒為單位)。如果存取權杖回應沒有到期時間,系統就會使用這個時間。如未提供值,權杖會在 6 小時後重新整理。
- 基本驗證
- 使用者名稱:用於提出 HTTP 要求的使用者名稱。
- 密碼:Secret Manager 密鑰,內含所提供使用者名稱的相關聯密碼。
- 摘要驗證
- 使用者名稱:用於提出 HTTP 要求的使用者名稱。
- 密碼:Secret Manager 密鑰,內含所提供使用者名稱的相關聯密碼。
- OAuth 2.0 - 授權碼
- 用戶端 ID:外部應用程式提供的用戶端 ID。
- 範圍:外部應用程式支援的權限範圍。
- 用戶端密鑰:選取 Secret Manager 密鑰。 設定這項授權前,請先建立 Secret Manager 密鑰。
- 密鑰版本:用戶端密鑰的 Secret Manager 密鑰版本。
- 如果後端伺服器支援 PKCE (Proof Key for Code Exchange),您可以選擇啟用。
- 授權網址:輸入外部應用程式的授權網址。
- 存取權杖網址:輸入用於取得外部應用程式存取權杖的網址。
- 服務帳戶
選取這個選項,即可使用您在先前步驟中設定這項連線時提供的服務帳戶進行驗證。請務必提供具備驗證所需相關 IAM 角色和權限的服務帳戶。
- 範圍:從下拉式選單選取必要的 OAuth 2.0 範圍。詳情請參閱「存取權範圍」。
- 服務帳戶 ID 權杖驗證
選取這個選項,即可使用您在上述步驟中提供的服務帳戶所產生的 ID 權杖進行驗證。這項驗證會使用 JSON Web Token (JWT) 進行驗證。ID 權杖提供者會使用服務帳戶簽署及核發 JWT,以便進行驗證。
- 目標對象:輸入 JWT 的預定收件者。
- 標頭名稱:輸入產生的 ID 權杖標頭名稱,用於 HTTP 標頭。如未指定這個欄位的值,系統會將鍵值預設為
Authorization。
- API 金鑰驗證
選取這個選項,即可使用 API 金鑰進行驗證。
- API 金鑰:選取 API 金鑰的 Secret Manager 密鑰。
- Secret version:選取 Secret 版本。
- API 金鑰參數名稱:輸入 API 金鑰的參數名稱。API 金鑰會以鍵/值組合的形式傳送至後端伺服器。您在這裡輸入的值,會做為先前所選 API 金鑰的名稱。
- API 金鑰位置:選取要在要求中新增 API 金鑰的位置。
如果是 Authorization code 驗證類型,建立連線後,您應執行幾個額外步驟來設定驗證。詳情請參閱「建立連線後的額外步驟」。
支援的加密套件
| TLS 版本 | 支援的加密套件 |
|---|---|
| 1.2 |
|
| 1.3 |
|
建立連線後的額外步驟
如果選取 OAuth 2.0 - Authorization code 做為驗證方式,則必須在建立連線後執行下列額外步驟:
- 在「Connections」(連線) 頁面中,找出新建立的連線。
請注意,新連接器的「狀態」會是「需要授權」。
- 按一下「Authorization required」。
系統隨即會顯示「Edit authorization」(編輯授權) 窗格。
- 將「重新導向 URI」值複製到外部應用程式。
- 驗證授權詳細資料。
- 按一下「Authorize」。
如果授權成功,「Connections」(連線) 頁面中的連線狀態會設為「Active」(有效)。
重新授權授權碼
如果您使用 Authorization code 驗證類型,且已在後端 HTTP 應用程式中變更任何設定,則必須重新授權 HTTP 連線。如要重新授權連結,請按照下列步驟操作:
- 在「連線」頁面中,按一下所需連線。
連線詳細資料頁面隨即開啟。
- 按一下「Edit」(編輯),即可編輯連結詳細資料。
- 在「Authentication」部分,驗證「OAuth 2.0 - Authorization code」詳細資料。
視需要進行必要變更。
- 按一下 [儲存]。系統會將您導向連線詳細資料頁面。
- 在「驗證」部分,按一下「編輯授權」。系統會顯示「Authorize」(授權) 窗格。
- 按一下「Authorize」。
如果授權成功,「Connections」(連結) 頁面中的連結狀態會設為「Active」(有效)。
實體、作業和動作
所有 Integration Connectors 都會為已連結應用程式的物件提供抽象層。您只能透過這個抽象層存取應用程式的物件。抽象層會以實體、作業和動作的形式呈現。
- 實體:實體可視為連結應用程式或服務中的物件或屬性集合。實體的定義因連接器而異。舉例來說,在資料庫連接器中,資料表是實體;在檔案伺服器連接器中,資料夾是實體;在訊息系統連接器中,佇列是實體。
不過,連接器可能不支援或沒有任何實體,在這種情況下,
Entities清單會是空白。 - 作業:作業是指可對實體執行的活動。您可以對實體執行下列任一操作:
從可用清單中選取實體後,系統會產生該實體的可用作業清單。如要進一步瞭解作業,請參閱連接器工作的實體作業。不過,如果連接器不支援任何實體作業,
Operations清單就不會列出這類不支援的作業。 - 動作:動作是透過連接器介面提供給整合的第一類函式。動作可讓您變更一或多個實體,且因連接器而異。一般來說,動作會有一些輸入參數和一個輸出參數。不過,連接器可能不支援任何動作,在這種情況下,
Actions清單會是空白。
系統限制
-
HTTP 連接器不支援
multipart/form-data內容類型。 -
HTTP 連接器每秒可處理 100 筆交易 (以節點為單位),並會限制超出此上限的交易。根據預設,Integration Connectors 會為連線分配 2 個節點 (提高可用性)。
如要瞭解 Integration Connectors 的限制,請參閱「限制」。
支援的動作
HTTP 連接器支援下列動作:
HttpRequest 動作
HTTP 連接器保證至少會嘗試將要求傳送至設定的端點一次。這項服務須遵守《Application Integration 服務水準協議 (SLA)》。下表說明 HttpRequest 動作的輸入和輸出參數。
HttpRequest 動作的輸入參數
| 參數名稱 | 資料類型 | 必填 | 說明 |
|---|---|---|---|
| 網址 | 結構 | 否 | 要傳送要求的網址。
網址格式為 <scheme>://<netloc>/<path>;<params>?<query>#<fragment>。
如果您提供 netloc,系統會覆寫建立連線時提供的主機名稱。 |
| 方法 | 字串 | 否 | HTTP 要求方法,例如 GET、POST、DELETE 或 PUT。預設值為 GET。 |
| 標頭 | 結構 | 否 | HTTP 要求標頭。 |
| 內文 | 字串 | 否 | HTTP 要求主體。 |
| RequestHasBytes | 布林值 | 否 | 是否要以位元組形式傳送要求。如果設為 true,您必須在 Body 參數中,以 Base64 編碼字串的形式傳送要求。預設值為 false。 |
| ResponseHasBytes | 布林值 | 否 | 是否以位元組形式接收回應。如果設為 true,您會收到以 Base64 編碼字串形式傳回的回應,並顯示在 ResponseBody 輸出參數中。預設值為 false。 |
| HttpVersion | 字串 | 否 | 提出要求時要使用的 HTTP 版本。支援的值為 1.1 和 2。如果指定第 2 版,系統會進行 ALPN (應用程式層通訊協定協商) 協商,並在伺服器不支援第 2 版時使用第 1.1 版。預設值為 2。 |
| ResponseFormat | 字串 | 否 | 指定連接器回應的格式。支援的值為 v1 和 v2。預設值為 v1。
v1 回應範例: [{ "ResponseBody": "{\n \"status\": 200\n}" }, { "StatusCode": 200.0 }, { "HttpVersion": "2" }, { "ResponseHeaders": { ":status": "200", "content-length": "19" } }] v2 回應範例: [{ "ResponseBody": "{\n \"status\": 200\n}", "StatusCode": 200.0, "HttpVersion": "2", "ResponseHeaders": { ":status": "200", "content-length": "19" } }] |
| FailOnError | 布林值 | 否 | 指定後端應用程式發生錯誤時的連線行為。
預設值為 |
| 逾時 | 整數 | 否 | HTTP 要求的逾時值 (以秒為單位)。預設值和允許的最大值為 150 秒。 |
HttpRequest 動作的輸出參數
| 參數名稱 | 資料類型 | 說明 |
|---|---|---|
| ResponseBody | 字串 | 從 HTTP 伺服器收到的回應。 |
| StatusCode | 整數 | 從 HTTP 伺服器收到的狀態碼。 |
| HttpVersion | 字串 | 為 HTTP 要求協商的版本。 |
| ResponseHeaders | 結構 | HTTP 回應標頭,格式為 key,value 組合。 |
範例
本節範例說明下列作業:
- 設定要求酬載
- 傳送位元組內容
- 取得位元組內容
下表列出範例情境和連接器工作中的對應設定:
| 工作 | 設定 |
|---|---|
| 設定要求酬載 |
這個範例會向 |
| 傳送位元組內容 |
如要傳送位元組 (例如檔案) 內容,您必須將
這個範例會向 |
| 取得位元組內容 |
如要從伺服器取得位元組 (Base64 字串),您必須將
這個範例會向 |
錯誤代碼
本節說明使用 HTTP 連線時可能出現的錯誤訊息。
| 錯誤訊息 | 原因 |
|---|---|
| 連線至 HTTP 伺服器時發生錯誤 | SSL 握手失敗或 HTTP 伺服器端點不正確,因此 HTTP 連線無法與伺服器建立連線。 |
| 收到 HTTP 伺服器傳回的錯誤回應 | 您嘗試連線的 HTTP 伺服器傳回錯誤回應,狀態碼為 4xx 或 5xx。回應範例:
{ "error": { "code": 400, "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "metadata": { "Body": "{\"thisIsResponseJSON\":\"someValue\"}" "Error": "Error response received from the HTTP server", "Headers": "{\":status\":[\"400\"], \"access-control-allow-credentials\":[\"true\"]}", "StatusCode": "400", "connection_type": "Http" } } ], "message": "Unable to execute HTTP Request", "status": "FAILED_PRECONDITION" } } |
| 擷取存取權杖時發生錯誤 | 擷取 OAuth Client Credentials Grant 驗證類型的存取權杖時發生錯誤。 |
| 摘要驗證錯誤 | 連接器執行階段未收到摘要驗證,或驗證類型不受支援。 |
| 錯誤 400 | HTTP 伺服器傳回錯誤回應,狀態碼為 400。詳情請參閱回應主體。 |
使用 Terraform 建立連線
您可以使用 Terraform 資源建立新連線。
如要瞭解如何套用或移除 Terraform 設定,請參閱「基本 Terraform 指令」。
如要查看用於建立連線的 Terraform 範本範例,請參閱範本範例。
使用 Terraform 建立這項連線時,必須在 Terraform 設定檔中設定下列變數:
| 參數名稱 | 資料類型 | 必填 | 說明 |
|---|---|---|---|
| proxy_enabled | BOOLEAN | 否 | 勾選這個核取方塊,即可為連線設定 Proxy 伺服器。 |
在整合作業中使用 HTTP 連線
建立連線後,您可以在 Apigee Integration 和 Application Integration 中使用該連線。您可以透過連接器工作,在整合中使用連線。
- 如要瞭解如何在 Apigee Integration 建立及使用連接器工作,請參閱「連接器工作」。
- 如要瞭解如何在 Application Integration 建立及使用連接器工作,請參閱「連接器工作」。
- 如要瞭解如何在 HTTP 連接器工作中,將 JSON 酬載視為字串處理,請參閱「在 HTTP 連接器工作中,將 JSON 酬載視為字串處理」。