HTTP

HTTP 連接器提供 HTTP 服務的連線能力,讓您使用以 HTTP 為基礎的 API。連接器也支援透過自訂設定建立 SSL/TLS 連線,以及 OAuth 2.0 用戶端憑證授權、基本和摘要等各種驗證機制。

事前準備

使用 HTTP 連接器前,請先完成下列工作:

  • 在 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 專案。

    前往「Connections」(連線) 頁面

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

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

    2. 點選「下一步」。
  4. 在「Connection Details」(連線詳細資料) 部分,完成下列操作:
    1. 連接器:從可用連接器的下拉式清單中,選取「HTTP」。
    2. 連接器版本:從可用版本的下拉式清單中選取連接器版本。
    3. 在「Connection Name」(連線名稱) 欄位中,輸入連線執行個體的名稱。

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

      • 連線名稱可以使用英文字母、數字或連字號。
      • 英文字母必須為小寫。
      • 連線名稱的開頭須為英文字母,結尾則須為英文字母或數字。
      • 連線名稱不得超過 49 個字元。
    4. 視需要輸入連線執行個體的說明。
    5. 視需要啟用「Cloud logging」(Cloud Logging),然後選取記錄層級。記錄層級預設為 Error。
    6. 服務帳戶:選取具備必要角色的服務帳戶。
    7. 如要檢查連線狀態,您可以在「Status Check」(狀態檢查) 欄位中指定端點網址。網址也可以包含端點連結 IP 位址。狀態預設為有效。
    8. 視需要設定連線節點設定:

      • 「Minimum number of nodes」(節點數量下限):輸入連線節點數量下限。
      • Maximum number of nodes (節點數量上限):輸入連線節點數量上限。

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

    9. 使用 Proxy:勾選核取方塊,為連線設定 Proxy 伺服器。
      1. 按一下「+ 新增目的地」。
      2. 選取「Destination Type」(目的地類型)。
        • 主機位址:指定目的地的 IP 位址或主機名稱。

          如要建立後端的私人連線,請按照下列步驟操作:

    10. (選用) 按一下「+ 新增標籤」,以鍵/值組合的形式為連線新增標籤。
    11. 如要使用 SSL,請選取「啟用 SSL」。系統隨即會顯示 SSL 設定詳細資料。
      1. 選取信任存放區類型。可以是「公開」、「私人」或「不安全連線」。
      2. 根據所選信任存放區,選取顯示的憑證。
      3. 如果您使用自行簽署的憑證或私人信任存放區憑證,請將根憑證儲存為 Secret Manager 密鑰,格式為 PEM (隱私強化郵件),然後在「Custom Trust Store」(自訂信任存放區) 中選取所需密鑰。
      4. 如果您使用 mTLS,請在「Key Store」(金鑰儲存庫) 部分選取金鑰儲存庫憑證。
      5. 視需要選取 TLS 版本。
      6. 輸入支援的加密套件。輸入多個加密套件,並以半形逗號分隔。詳情請參閱「支援的加密套件」。
    12. 按一下「Next」。
  5. 在「Destinations」(目的地) 部分,輸入要連線的遠端主機 (後端系統) 詳細資料。
    1. 目的地類型:選取「目的地類型」。
      • 如要指定目的地主機名稱或 IP 位址,請選取「Host address」(主機位址),然後在「host 1」(主機 1) 欄位中輸入位址。
      • 如要建立私人連線,請選取「Endpoint attachment」(端點連結)。在「Endpoint Attachment」(端點連結) 清單中,選取為後端系統建立的端點連結。

      如要建立公開連線至後端系統,並提高安全性,可以考慮為連線設定靜態傳出 IP 位址,然後設定防火牆規則,只將特定靜態 IP 位址加入許可清單。

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

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

      HTTP 連線支援下列驗證類型:

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

    3. 點選「下一步」。
  7. 查看:查看連線和驗證詳細資料。
  8. 按一下 [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),您可以選擇啟用。
    • 授權網址:輸入外部應用程式的授權網址。
    • 存取權杖網址:輸入用於取得外部應用程式存取權杖的網址。

    如果是 Authorization code 驗證類型,建立連線後,您應執行幾個額外步驟來設定驗證。詳情請參閱「建立連線後的額外步驟」。

  • 服務帳戶

    選取這個選項,即可使用您在先前步驟中設定這項連線時提供的服務帳戶進行驗證。請務必提供具備驗證所需相關 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 金鑰的位置。

支援的加密套件

TLS 版本 支援的加密套件
1.2
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
1.3
  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256

建立連線後的額外步驟

如果選取 OAuth 2.0 - Authorization code 做為驗證方式,則必須在建立連線後執行下列額外步驟:

  1. 在「Connections」(連線) 頁面中,找出新建立的連線。

    請注意,新連接器的「狀態」會是「需要授權」。

  2. 按一下「Authorization required」。

    系統隨即會顯示「Edit authorization」(編輯授權) 窗格。

  3. 將「重新導向 URI」值複製到外部應用程式。
  4. 驗證授權詳細資料。
  5. 按一下「Authorize」。

    如果授權成功,「Connections」(連線) 頁面中的連線狀態會設為「Active」(有效)。

重新授權授權碼

如果您使用 Authorization code 驗證類型,且已在後端 HTTP 應用程式中變更任何設定,則必須重新授權 HTTP 連線。如要重新授權連結,請按照下列步驟操作:

  1. 在「連線」頁面中,按一下所需連線。

    連線詳細資料頁面隨即開啟。

  2. 按一下「Edit」(編輯),即可編輯連結詳細資料。
  3. 在「Authentication」部分,驗證「OAuth 2.0 - Authorization code」詳細資料。

    視需要進行必要變更。

  4. 按一下 [儲存]。系統會將您導向連線詳細資料頁面。
  5. 在「驗證」部分,按一下「編輯授權」。系統會顯示「Authorize」(授權) 窗格。
  6. 按一下「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 布林值 否 指定後端應用程式發生錯誤時的連線行為。
  • true:擲回例外狀況。後端擲回的例外狀況會傳播至連線的回應中。
  • false:不會擲回例外狀況。但會在回應中傳回錯誤代碼和錯誤訊息。

預設值為 true。

逾時 整數 否 HTTP 要求的逾時值 (以秒為單位)。預設值和允許的最大值為 150 秒。

HttpRequest 動作的輸出參數

參數名稱 資料類型 說明
ResponseBody 字串 從 HTTP 伺服器收到的回應。
StatusCode 整數 從 HTTP 伺服器收到的狀態碼。
HttpVersion 字串 為 HTTP 要求協商的版本。
ResponseHeaders 結構 HTTP 回應標頭,格式為 key,value 組合。

範例

本節範例說明下列作業:

  • 設定要求酬載
  • 傳送位元組內容
  • 取得位元組內容

下表列出範例情境和連接器工作中的對應設定:

工作 設定
設定要求酬載
  1. 在「Configure connector task」對話方塊中,按一下「Actions」。
  2. 選取「HttpRequest」動作,然後按一下「完成」。
  3. 在「Connectors」(連接器) 工作的「Task Input」(工作輸入) 區段中,按一下 connectorInputPayload,然後在「Default Value」欄位中輸入類似下列的值:
    {
      "Url": {
        "scheme": "https",
        "netloc": "httpbin.org",
        "path": "post",
        "query": "example=A&sort=value",
        "fragment": "exampleFragment"
      },
      "Method": "POST",
      "Headers": {
        "Accept": ["application/json", "application/xml"],
        "a": "b"
      },
      "Body": "{\"thisIsRequestJSON\":\"someValue\"}"
    }
  4. 按一下「儲存」。

這個範例會向 https://httpbin.org/post?example=A&=value#exampleFragment 網址傳送 POST 要求。由於酬載中提供 netloc,因此會覆寫建立連線時提供的主機名稱。

傳送位元組內容

如要傳送位元組 (例如檔案) 內容,您必須將 RequestHasBytes 要求屬性設為 true,並將 body 屬性設為要傳送的 Base64 編碼字串,如下列範例所示。

  1. 在「Configure connector task」對話方塊中,按一下「Actions」。
  2. 選取「HttpRequest」動作,然後按一下「完成」。
  3. 在「Connectors」(連接器) 工作的「Task Input」(工作輸入) 區段中,按一下 connectorInputPayload,然後在「Default Value」欄位中輸入類似下列的值:
    {
      "Url": {
        "scheme": "https",
        "netloc": "httpbin.org",
      },
      "Method": "POST",
      "Headers": {
        "Accept": ["application/json", "application/xml"],
        "a": "b"
      },
      "Body": "SGVsbG8gV29ybGQ=",
      "RequestHasBytes":true
    }
  4. 按一下「儲存」。

這個範例會向 httpbin.org 伺服器傳送 POST 要求,並在要求主體中以 Base64 編碼字串的形式傳送檔案內容。伺服器可以決定如何處理檔案內容。

取得位元組內容

如要從伺服器取得位元組 (Base64 字串),您必須將 ResponseHasBytes 要求屬性設為 true,如下列範例所示。

  1. 在「Configure connector task」對話方塊中,按一下「Actions」。
  2. 選取「HttpRequest」動作,然後按一下「完成」。
  3. 在「Connectors」(連接器) 工作的「Task Input」(工作輸入) 區段中,按一下 connectorInputPayload,然後在「Default Value」欄位中輸入類似下列的值:
    {
      "Url": {
        "scheme": "https",
        "netloc": "httpbin.org",
      },
      "Method": "GET",
      "ResponseHasBytes":true
    }
  4. 按一下「儲存」。

這個範例會向 httpbin.org 伺服器發出 GET 要求,並在要求主體中將 ResponseHasBytes 設為 true。

錯誤代碼

本節說明使用 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 中使用該連線。您可以透過連接器工作,在整合中使用連線。

向 Google Cloud 社群尋求協助

您可以在 Google Cloud 社群的 Cloud 論壇中,發布問題並討論這個連接器。

後續步驟