反模式：在 API Proxy 中無法正確存取多值 HTTP 標頭

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

HTTP 標頭是名稱值組合，可讓用戶端應用程式和後端服務分別傳遞要求與回應的其他資訊。以下是一些簡單的範例：

  • 授權要求標頭會將使用者憑證傳送至伺服器：
    Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
  • Content-Type 標頭代表傳送的要求/回應內容類型：
    Content-Type: application/json

視標頭欄位定義而定，HTTP 標頭可以有一或多個值。多重值標頭將採用半形逗號分隔值。以下列舉幾個包含多個值的標頭範例：

  • Cache-Control: no-cache, no-store, must-revalidate
  • Accept: text/html, application/xhtml+xml, application/xml;q=0.9, */*;q=0.8
  • X-Forwarded-For: 10.125.5.30, 10.125.9.125

Apigee Edge 可讓開發人員在任何邊緣政策或條件流程中使用流程變數輕鬆存取標頭。以下是可用於在 Edge 中存取特定要求或回應標頭的變數清單：

流程變數：

  • message.header.header-name
  • request.header.header-name
  • response.header.header-name
  • message.header.header-name.N
  • request.header.header-name.N
  • response.header.header-name.N

JavaScript 物件：

  • context.proxyRequest.headers.header-name
  • context.targetRequest.headers.header-name
  • context.proxyResponse.headers.header-name
  • context.targetResponse.headers.header-name

以下為 AssignMessage 政策範例，說明如何讀取要求標頭的值並儲存至變數：

<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
  <AssignVariable>
    <Name>reqUserAgent</Name>
    <Ref>request.header.User-Agent</Ref>
  </AssignVariable>
</AssignMessage>

反模式

以只傳回第一個值的方式存取 Edge 政策中的 HTTP 標頭值不正確，如果特定 HTTP 標頭含有多個值，便可能發生問題。

以下各節將舉例說明標頭存取方式。

範例 1：使用 JavaScript 程式碼讀取多值「接受」標頭

請注意，Accept 標頭包含多個值，如下所示：

Accept: text/html, application/xhtml+xml, application/xml

以下 JavaScript 程式碼可讀取 Accept 標頭中的值：

// Read the values from Accept header
var acceptHeaderValues = context.getVariable("request.header.Accept");

上述 JavaScript 程式碼只會傳回 Accept 標頭的第一個值，例如 text/html。

範例 2：讀取 AssignMessage 或 IncreaseFault 政策中的多值 Access-Control-Allow-Headers 標頭

請注意，Access-Control-Allow-Headers 標頭包含多個值，如下所示：

Access-Control-Allow-Headers: content-type, authorization

以下是 AssignMessage 或 riseFault 政策設定 Access-Control-Allow-Headers 標頭的部分程式碼：

<Set>
  <Headers>
    <Header name="Access-Control-Allow-Headers">{request.header.Access-Control-Request-Headers}</Header>
  </Headers>
</Set>

上述程式碼只使用要求標頭 Access-Control-Allow-Headers 中的第一個值來設定標頭 Access-Control-Allow-Headers，在本範例中為 content-type。

影響程度

  1. 請注意，在上述兩個範例中，系統只會傳回多值標頭中的第一個值。如果之後在 API Proxy 流程中或後端服務中為了執行某些函式或邏輯而使用這些值，可能會導致非預期的結果或結果。
  2. 在存取要求標頭值並傳遞至目標伺服器時，後端可能無法正確處理 API 要求，因此可能會提供不正確的結果。
  3. 如果用戶端應用程式需要使用 Edge 回應的特定標頭值，可能也會無法正確處理，並顯示不正確的結果。

最佳做法

  1. 使用適當的內建流程變數：request.header.header_name.values.count、request.header.header_name.N、response.header.header_name.values.count、response.header.header_name.N。

    接著反覆執行 JavaScript 或 Java 呼叫政策，擷取特定標頭中的所有值。

    範例：讀取多值標頭的 JavaScript 程式碼範例

    for (var i = 1; i <=context.getVariable('request.header.Accept.values.count'); i++)
{
  print(context.getVariable('request.header.Accept.' + i));
}

    舉例來說，application/xml;q=0.9, */*;q=0.8 會顯示為含有上述程式碼的值。

    如果要使用分號做為分隔符號來分割標頭值，請使用 string.split(";") 將這些值分隔成值。

  2. 在 riseFault 或 AssignMessage 政策中，對流程變數 request.header.header_name.values 使用 substring() 函式，以讀取特定標頭的所有值。

    範例：以半形逗號分隔的 PromoteFault 或 AssignMessage 政策範例 (用於讀取多個值標頭)

    <Set>
  <Headers>
   <Header name="Access-Control-Allow-Headers">{substring(request.header.Access-Control-Request-Headers.values,1,-1)}</Header>
  </Headers>
</Set>

其他資訊