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

您目前查看的是 Apigee 和 Apigee Hybrid 說明文件。
查看 Apigee Edge 說明文件。

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 中存取特定要求或回應標頭的變數：

流程變數：

  • 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>

反模式

在 Apigee 政策中存取 HTTP 標頭值時，如果只傳回第一個值，就是不正確的做法，如果特定 HTTP 標頭有多個值，可能會導致問題。

以下各節包含標頭存取權的範例。

範例 1：使用 JavaScript 程式碼讀取多值 Accept 標頭

假設 Accept 標頭有多個值，如下所示：

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

以下是從 Accept 標頭讀取值的 JavaScript 程式碼：

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

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

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

假設 Access-Control-Allow-Headers 標頭有多個值，如下所示：

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

以下是 AssignMessage 或 RaiseFault 政策中設定 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. 如果用戶端應用程式依賴 Apigee 回應中的特定標頭值，也可能會處理錯誤並提供不正確的結果。

最佳做法

  1. 參考流程變數的 request.header.header_name.values.string 形式，讀取特定標頭的所有值。

    範例：可用於 RaiseFault 或 AssignMessage 的範例片段，可讀取多值標頭

    <Set>
  <Headers>
    <Header name="Inbound-Headers">{request.header.Accept.values.string}</Header>
  </Headers>
</Set>

  2. 如要個別存取每個不同的值，可以使用適當的內建流程變數：request.header.header_name.values.count、request.header.header_name.N、response.header.header_name.values.count、response.header.header_name.N。

    然後疊代，從 JavaScript 或 JavaCallout 政策中的特定標頭擷取所有值。

    範例：讀取多值標題的 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 會顯示為兩個值。 第一個值是 application/xml;q=0.9，第二個值是 */*;q=0.8。

    如果需要使用半形分號做為分隔符號來分割標頭值，則可以在 JavaScript 呼叫中使用 string.split(";") 分隔不同的值。

  3. 此外，您也可以在流程變數 request.header.header_name.values 的訊息範本中使用 substring() 函式，讀取特定標題的所有值。

    範例：在訊息範本中使用 substring() 讀取完整的多值標頭

    <Set>
  <Headers>
   <Header name="Inbound-Headers">{substring(request.header.Accept.values,1,-1)}</Header>
  </Headers>
</Set>

延伸閱讀