端點屬性參考資料

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本主題說明可在 TargetEndpoint 和 ProxyEndpoint 設定中設定的傳輸屬性，以控管訊息和連線行為。如要全面瞭解 TargetEndpoint 和 ProxyEndpoint 設定，請參閱 API Proxy 設定參考資料。

TargetEndpoint 傳輸屬性

TargetEndpoint 設定中的 HTTPTargetConnection 元素會定義一組 HTTP 傳輸屬性。您可以使用這些屬性設定傳輸層級的設定。

屬性會設定在 TargetEndpoint HTTPTargetConnection 元素上，如下所示：

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <Properties>
      <Property name="supports.http10">true</Property>
      <Property name="request.retain.headers">User-Agent,Referer,Accept-Language</Property>
      <Property name="retain.queryparams">apikey</Property>
    </Properties>
    <CommonName>COMMON_NAME_HERE</CommonName>
  </HTTPTargetConnection>
</TargetEndpoint>

TargetEndpoint 傳輸屬性 規格

資源名稱 預設值 說明
keepalive.timeout.millis 60000 連線集區中目標連線的連線閒置逾時時間。如果集區中的連線閒置時間超過指定限制，系統就會關閉連線。
connect.timeout.millis

3000

目標連線逾時。如果發生連線逾時，Edge 會傳回 HTTP 503 狀態碼。在某些情況下，如果 LoadBalancer 用於 TargetServer 定義，且發生逾時，系統可能會傳回 HTTP 504 狀態碼。
io.timeout.millis 55000

如果在指定毫秒數內沒有可讀取的資料，或是插座未準備好在指定毫秒數內寫入資料，交易就會視為逾時。

  • 如果在寫入 HTTP 要求時發生逾時，系統會傳回 408, Request Timeout。
  • 如果在讀取 HTTP 回應時發生逾時，系統會傳回 504, Gateway Timeout。

這個值一律應小於 虛擬主機的 proxy_read_timeout 屬性值。

這個值應小於 Router 用於與 訊息處理器 通訊的逾時時間。詳情請參閱「設定路由器逾時」。

詳情請參閱「設定 Edge 的 io.timeout.millis 和 api.timeout」。
supports.http10 true 如果是 true，且用戶端傳送 1.0 要求，目標也會收到 1.0 要求。否則會將 1.1 要求傳送至目標。
supports.http11 true 如果這是 true，且用戶端傳送 1.1 要求，系統也會將 1.1 要求傳送至目標，否則會將 1.0 要求傳送至目標。
use.proxy true 如果設為 true，且 http.properties 中指定了 Proxy 設定 (僅限於地端部署)，則目標連線會設為使用指定的 Proxy。
use.proxy.tunneling true 如果設為 true，且在 http.properties 中指定了 Proxy 設定 (僅限地端部署)，則目標連線會設為使用指定的通道。如果目標使用 TLS/SSL，系統會忽略這項屬性，並一律透過通道傳送訊息。
enable.method.override false 針對指定的 HTTP 方法，在傳送至目標服務的要求中設定 X-HTTP-Method-Override 標頭。例如：<Property name="GET.override.method">POST</Property>
*.override.method N/A 針對指定的 HTTP 方法，在傳出要求中設定 X-HTTP-Method-Override 標頭。例如：<Property name="GET.override.method">POST</Property>
request.streaming.enabled false

根據預設 (false)，HTTP 要求酬載會讀取至緩衝區，且可對酬載執行的政策會正常運作。如果酬載大於緩衝區空間 (10 MB)，您可以將這個屬性設為 true。如果為 true，系統不會將 HTTP 要求酬載讀取至緩衝區，而是直接串流至目標端點。在這種情況下，系統會略過在 TargetEndpoint 要求流程中對酬載運作的任何政策。另請參閱「串流要求和回應」。
response.streaming.enabled false

根據預設 (false)，HTTP 回應酬載會讀取至緩衝區，且可對酬載執行的政策會正常運作。如果酬載大於緩衝區空間 (10 MB)，您可以將這個屬性設為 true。如果是 true，HTTP 回應負載不會讀取到緩衝區，而是會以原始串流的形式傳送至 ProxyEndpoint 回應流程。在這種情況下，系統會略過在 TargetEndpoint 回應流程中對酬載執行的任何政策。另請參閱「串流要求和回應」。
success.codes N/A

根據預設，Apigee Edge 會將 HTTP 代碼 4XX 或 5XX 視為錯誤，並將 HTTP 代碼 1XX、2XX、3XX 視為成功。這個屬性可明確定義成功代碼，例如 2XX, 1XX, 505 會將任何 100、200 和 505 HTTP 回應代碼視為成功。

設定這項屬性會覆寫預設值。因此，如要將 HTTP 代碼 400 新增至預設成功代碼清單，請將這項屬性設為：

<Property name="success.codes">1XX,2XX,3XX,400</Property>

如果只希望將 HTTP 代碼 400 視為成功代碼，請將屬性設為：

<Property name="success.codes">400</Property>

將 HTTP 代碼 400 設為唯一成功代碼後，系統會將代碼 1XX、2XX 和 3XX 視為失敗。
compression.algorithm N/A 根據預設，Apigee Edge 會使用與用戶端要求相同的壓縮類型，將要求轉送至目標。如果要求是從用戶端收到，且使用 gzip 壓縮等方式，Apigee Edge 會使用 gzip 壓縮將要求轉送至目標。如果從目標收到的回應使用 deflate，Apigee Edge 會使用 deflate 將回應轉送給用戶端。支援的值如下：
  • gzip：一律使用 gzip 壓縮傳送訊息
  • deflate：一律使用 deflate 壓縮傳送訊息
  • 無：一律傳送未經壓縮的訊息

另請參閱： Apigee 是否支援使用 GZIP/deflate 壓縮進行壓縮/解壓縮？
request.retain.headers.
enabled		 true 根據預設，Apigee Edge 一律會保留外送訊息的所有 HTTP 標頭。設為 true 時，傳入要求中的所有 HTTP 標頭都會設為傳出要求。
request.retain.headers N/A 定義應在傳送至目標服務的外送要求中設定的特定 HTTP 要求標頭。舉例來說，如要直通 User-Agent 標頭，請將 request.retain.headers 的值設為 User-Agent。多個 HTTP 標頭會指定為以半形逗號分隔的清單，例如 User-Agent,Referer,Accept-Language。這項屬性會覆寫 request.retain.headers.enabled。如果 request.retain.headers.enabled 設定為 false，系統仍會在傳送的郵件中設定 request.retain.headers 屬性中指定的任何標頭。
response.retain.headers.
enabled		 true 根據預設，Apigee Edge 一律會保留外送訊息的所有 HTTP 標頭。設為 true 時，目標服務傳送的入站回應中所有 HTTP 標頭，都會在傳遞至 ProxyEndpoint 前，設為出站回應。
response.retain.headers N/A 定義應在傳遞至 ProxyEndpoint 之前，於外送回應中設定的回應特定 HTTP 標頭。舉例來說，如要直通 Expires 標頭，請將 response.retain.headers 的值設為 Expires。多個 HTTP 標頭會指定為以半形逗號分隔的清單，例如 Expires,Set-Cookie。這項屬性會覆寫 response.retain.headers.enabled。如果 response.retain.headers.enabled 設為 false，系統仍會在外寄郵件中設定 response.retain.headers 屬性中指定的任何標頭。
retain.queryparams.
enabled		 true 根據預設，Apigee Edge 一律會保留輸出要求的所有查詢參數。如果設為 true，系統會將傳入要求中的所有查詢參數，設定在傳送至目標服務的要求中。
retain.queryparams N/A 定義要在外送要求中設定的特定查詢參數。舉例來說，如要從要求訊息中加入查詢參數 apikey，請將 retain.queryparams 設為 apikey。多個查詢參數會指定為以半形逗號分隔的清單，例如 apikey,environment。這項屬性會覆寫 retain.queryparams.enabled。

ProxyEndpoint 傳輸屬性

ProxyEndpoint HTTPTargetConnection 元素會定義一組 HTTP 傳輸屬性。這些屬性可用於設定傳輸層級的設定。

ProxyEndpoint HTTPProxyConnection 元素的屬性設定如下：

<ProxyEndpoint name="default">
  <HTTPProxyConnection>
    <BasePath>/v1/weather</BasePath>
    <Properties>
      <Property name="request.streaming.enabled">true</Property>
    </Properties>
    <VirtualHost>default</VirtualHost>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
</ProxyEndpoint>

如要進一步瞭解虛擬主機，請參閱「關於虛擬主機」。

ProxyEndpoint 傳輸屬性 規格

資源名稱 預設值 說明
X-Forwarded-For false 如果設為 true，虛擬主機的 IP 位址會新增至外送要求，做為 HTTP X-Forwarded-For 標頭的值。
request.streaming.
enabled		 false 根據預設 (false)，HTTP 要求酬載會讀取至緩衝區，且可對酬載執行的政策會正常運作。如果酬載大於緩衝區空間 (10 MB)，您可以將這個屬性設為 true。如果為 true，HTTP 要求酬載不會讀取至緩衝區，而是會以串流形式原封不動地傳送至 TargetEndpoint 要求流程。在本例中，系統會略過在 ProxyEndpoint 要求流程中對酬載運作的任何政策。另請參閱「串流要求和回應」。
response.streaming.
enabled		 false 根據預設 (false)，HTTP 回應酬載會讀取至緩衝區，且可對酬載執行的政策會正常運作。如果酬載大於緩衝區空間 (10 MB)，您可以將這個屬性設為 true。如果為 true，系統不會將 HTTP 回應負載讀取至緩衝區，而是依原樣串流至用戶端。在這種情況下，系統會略過在 ProxyEndpoint 回應流程中對酬載執行的任何政策。另請參閱「串流要求和回應」。
compression.algorithm N/A

根據預設，Apigee Edge 會採用收到的任何訊息所設定的壓縮類型。舉例來說，如果用戶端提交的要求使用 gzip 壓縮，Apigee Edge 會使用 gzip 壓縮將要求轉送至目標。您可以在 TargetEndpoint 或 ProxyEndpoint 上設定這項屬性，明確套用壓縮演算法。支援的值如下：

  • gzip：一律使用 gzip 壓縮傳送訊息
  • deflate：一律使用 deflate 壓縮傳送訊息
  • 無：一律傳送未經壓縮的訊息

另請參閱： Apigee 是否支援使用 GZIP/deflate 壓縮進行壓縮/解壓縮？
api.timeout N/A

設定個別 API Proxy 的逾時時間

您可以設定 API Proxy (包括啟用串流的 Proxy)，在指定時間後以 504 Gateway Timeout 狀態逾時。主要用途是為執行時間較長的 API Proxy 提供服務。舉例來說，假設您需要特定 Proxy 在 3 分鐘後逾時，以下是 api.timeout 的使用方式。

  1. 首先，請務必將負載平衡器、路由器和訊息處理器設定為在三分鐘後逾時。
  2. 然後將相關 Proxy 設定為在三分鐘後逾時。以毫秒為單位指定值。例如：<Property name="api.timeout">180000</Property>
  3. 但請注意，提高系統逾時可能會導致效能問題，因為所有沒有 api.timeout 設定的 Proxy 都會使用新的較高負載平衡器、路由器和訊息處理器逾時。因此，請設定其他不需要較長逾時時間的 API Proxy，以使用較短的逾時時間。舉例來說，下列程式碼會將 API Proxy 設為在 1 分鐘後逾時：
    <Property name="api.timeout">60000</Property>

您無法使用變數設定這項屬性。

如果客戶無法修改 Edge 逾時，只要逾時時間短於標準 Edge 訊息處理器逾時時間 (57 秒)，也可以設定 API Proxy 逾時。

詳情請參閱「設定 Edge 的 io.timeout.millis 和 api.timeout」。

為 Edge 設定 io.timeout.millis 和 api.timeout

在 Edge 中，io.timeout.millis 和 api.timeout 的運作方式相關。每次對 API Proxy 提出要求時：

  1. 路由器會將逾時值傳送至訊息處理器。路由器逾時值可以是處理要求的虛擬主機所設定的 proxy_read_timeout 值，也可以是預設的 57 秒逾時值。
  2. 訊息處理器接著會設定 api.timeout：
    1. 如果api.timeout未未在 Proxy 層級設定，請將其設為 Router 逾時。
    2. 如果 api.timeout 是在 Proxy 層級設定，請在訊息處理器上將其設為 Router 逾時或 api.timeout 值中較小的值。

  3. api.timeout 的值指定 API Proxy 從 API 要求到回應的執行時間上限。

    API Proxy 中的每項政策執行完畢後，或訊息處理器將要求傳送至目標端點前，訊息處理器會計算 (api.timeout - 要求開始經過的時間)。如果值小於零，表示處理要求的時間已超過上限，訊息處理器會傳回 504。

  4. io.timeout.millis 的值會指定目標端點必須回應的最長時間。

    在連線至目標端點前，訊息處理器會判斷 (api.timeout - 要求開始經過的時間) 和 io.timeout.millis 兩者中較小的值。然後將 io.timeout.millis 設為該值。

    • 如果在寫入 HTTP 要求時發生逾時，系統會傳回 408, Request Timeout。
    • 如果在讀取 HTTP 回應時發生逾時，系統會傳回 504, Gateway Timeout。

Node.js 應用程式的 ScriptTarget 簡介

ScriptTarget 元素用於將 Node.js 應用程式整合至 Proxy。如要瞭解如何使用 Node.js 和 ScriptTarget，請參閱：

關於 HostedTarget 端點

空白的 <HostedTarget/> 標記會告知 Edge，要以部署至代管目標環境的 Node.js 應用程式做為目標。詳情請參閱「代管目標總覽」。