要求和回應變數

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

向 API Proxy 提出要求時，您可以傳遞下列任何或所有資訊，具體取決於 API Proxy 的設定方式：

  • 要求標頭
  • 查詢參數
  • 表單資料
  • XML 或 JSON 酬載
  • 資源 URI

根據預設，要求中的所有資料都會從 ProxyEndpoint 不變地傳遞至 TargetEndpoint。因此，當 TargetEndpoint 向後端伺服器提出要求時，原始要求中的所有資訊都會傳遞至後端服務。

Apigee 從後端服務收到的回應也是如此。根據預設，回應中收到的所有資料都會原封不動地傳遞至發出要求的應用程式。

如何將要求資料傳遞至後端伺服器？

下圖顯示 API Proxy 定義：

HTTP 用戶端的要求會通過 Proxy 端點，傳送至後端的 TargetEndpoint，最終抵達 HTTP 服務。系統會提供 Proxy 端點和目標端點的範例。

針對這個 API Proxy：

  • API Proxy 虛擬主機： default
  • 環境群組中主機名稱定義的網域： http://www.example.com
  • Proxy 基本路徑： /v1/weather
  • 路由規則指定的 TargetEndpoint： default
  • 目標網址： http://weather.yahooapis.com

用戶端應用程式會使用下列 curl 指令，對 API Proxy 發出 GET 要求：

curl -X GET http://www.example.com/v1/weather/forecastrss?w=12797282

請注意，這項要求包含資源 forecastrss 和一個查詢參數 w。Apigee 會剖析要求，如下所示，並將要求的部分內容指派給流程變數：

{request.verb} {proxy.basepath}/{proxy.pathsuffix}?{request.querystring}

流程變數會設定為下列值：

  • request.verb：GET
  • proxy.basepath：/v1/weather
  • proxy.pathsuffix：forecastrss
  • request.querystring：w=12797282

接著，TargetEndpoint 會使用要求中的資訊，向後端服務提出要求：

{request.verb} {target.basepath}/{proxy.pathsuffix}?{request.querystring}

請注意，要求中指定的資源和查詢參數會自動納入後端伺服器的要求。根據 TargetEndpoint 的定義，要求會採用下列形式：

curl -X GET http://weather.yahooapis.com/forecastrss?w=12797282

與查詢參數一樣，您在 API Proxy 要求中加入的任何標頭或表單參數，都會傳遞至後端伺服器。舉例來說，您提出下列要求，其中包含標頭：

curl -X GET -H 'Content-type:application/xml' http://www.example.com/v1/weather/forecastrss?w=12797282

或以下列格式提出要求，加入標頭和表單資料：

curl -X POST -H "Content-type:application/json" -d \
  '{"email" : "janetutorialxml@example.com",
    "firstName" : "Jane",
    "lastName" : "Tutorial",
    "userName" : "jtutorialxml"
  }' \
  http://www.example.com/v1/register/user

在這兩個範例中，標頭和表單資料都會原封不動地傳遞至後端服務。標頭會以流程變數表示，例如 request.headers.count 和 request.headers.names。表單資料會以流程變數表示，例如 request.formparam.count 和 request.formparam.names。

如何傳回回應資料？

根據預設，Apigee 從後端服務接收的所有回應資料，都會原封不動地傳遞至發出要求的應用程式。如上所述，回應中傳回的資料可透過 Apigee 的流程變數存取。詳情請參閱流程變數參考資料。

在 API Proxy 中存取要求和回應資料

在許多情況下，您會想在將要求資料傳送至後端伺服器前進行修改。例如：

  • 移除 Apigee 用來驗證要求的安全性資訊。後端服務不需要這項資訊。
  • 新增傳送至後端服務的資料，例如追蹤使用者或收集數據分析資料。
  • 根據要求資料有條件地處理要求。舉例來說，API Proxy 可以有多個 TargetEndpoint。要求使用的 TargetEndpoint 取決於要求資料。接著，您要先從要求中移除該資料，再傳送至後端服務。

回應中的資料也是如此。在處理回應時，API 代理程式可能會想修改資料，再傳回給提出要求的應用程式。

存取要求訊息

您可以使用政策存取及變更要求訊息的部分內容。包括：

  • 標頭
  • 查詢參數
  • 表單參數
  • 來源 IP 位址
  • HTTP 訊息主體

在正常流程中，要求處理完畢後，Proxy 會將轉換後的要求傳送至目標。

政策可以檢查要求變數，然後根據這些變數的內容轉換或拒絕要求。政策會設定適當的變數 (例如對應要求標頭的變數)，藉此轉換要求。

存取回覆訊息

政策可以使用適用於回應訊息的變數，存取訊息元件，包括標頭、查詢參數和表單參數、來源 IP 位址、HTTP 訊息主體等。

Proxy 會收到回應訊息，然後根據評估回應的條件套用一系列政策，藉此修改或轉換回應。

政策可以檢查回應變數，然後根據這些變數的內容轉換或拒絕要求。政策會設定適當的變數 (例如對應回應標頭的變數)，藉此轉換回應。

存取流程變數的常見政策

Apigee 定義了多項政策，可用於處理要求和回應資料。這些政策包括：