端點屬性參考資料

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本主題說明可在 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="request.retain.headers">User-Agent,Referer,Accept-Language</Property>
      <Property name="retain.queryparams">apikey</Property>
    </Properties>
  </HTTPTargetConnection>
</TargetEndpoint>

TargetEndpoint 傳輸屬性規格

屬性名稱 預設值 說明
allow.post.without.content.length false 讓您傳送沒有內文的 POST 要求。
allow.put.without.content.length false 讓您傳送沒有內容的 PUT 要求。
allow.tls.session.resumption 是 如果是 true (預設)，用戶端會在建立與目標的新連線時重複使用 TLS 工作階段。如果不想重複使用 TLS 工作階段，請將其設為 false。重複使用工作階段通常代表連線時間較短，但某些目標可能不支援重複使用工作階段，或無法順利執行重複使用工作階段。
keepalive.timeout.millis 60000 連線集區中目標連線的連線閒置逾時時間。如果集區中的連線閒置時間超過指定限制，系統就會關閉連線。
connect.timeout.millis

3000

目標連線逾時。如果發生連線逾時，Apigee 會傳回 HTTP 503 狀態碼。在某些情況下，如果在 TargetServer 定義中使用 LoadBalancer 且發生逾時，系統可能會傳回 HTTP 504 狀態碼。
ignore.allow.header.for.405

是

可讓您將 405 狀態碼傳回用戶端。啟用標記後，Apigee 會傳回 405 而非 502 狀態碼。
io.timeout.millis 55000

如果在指定的毫秒數內沒有可讀取的資料，或是套接字在指定的毫秒數內無法寫入資料，系統會將該交易視為逾時。

  • 如果在讀取 ingress 的 HTTP 要求時發生逾時，系統會重新調整 408 Request Timeout。如果在寫入目標要求時發生逾時情形，系統就不會傳回 408 Request Timeout。
  • 如果在寫入 HTTP 要求或讀取 HTTP 回應時發生逾時情形，系統會傳回 504 Gateway Timeout。

請參閱「設定 io.timeout.millis 和 api.timeout」。
supports.http11 是 如果是 true，且用戶端傳送 1.1 要求，則目標也會收到 1.1 要求，否則會將 1.0 要求傳送至目標。
use.proxy 是

如果 Apigee 混合式覆寫檔案包含 HTTP_PROXY 設定，請按照「為 API Proxy 設定轉送 Proxy」一文的說明，使用這個屬性來管理/控制哪些 Proxy 不應使用 Proxy 設定。

如果設為 false，API Proxy 會略過 Apigee 混合式覆寫檔案中指定的 HTTP Proxy 設定，以便在 Proxy 中設定目標連線。
use.proxy.tunneling 是

如果將這個值設為 true，並指定 Proxy 設定，則會根據「為 API Proxy 設定轉送 Proxy 服務」一文所述，覆寫 Apigee 混合式檔案，然後將目標連線設為使用指定的通道。如果目標使用 TLS/SSL，系統會忽略這項屬性，並一律透過通道傳送訊息。
request.streaming.enabled false

根據預設 (false)，HTTP 要求酬載會讀入緩衝區，而可在酬載上運作的政策會如預期運作。如果酬載比緩衝區大小 (在 Apigee 中為 10 MB) 大，您可以將此屬性設為 true。在 true 時，HTTP 要求酬載不會讀入緩衝區，而是會原樣串流至目標端點。在這種情況下，系統會略過所有在 TargetEndpoint 要求流程中對酬載運作的政策。另請參閱「串流要求和回應」。
response.streaming.enabled false

根據預設 (false)，HTTP 回應酬載會讀入緩衝區，而可在酬載上運作的政策會正常運作。如果酬載大於緩衝區大小 (在 Apigee 中為 10 MB)，您可以將這個屬性設為 true。如果為 true，系統就不會將 HTTP 回應酬載讀入緩衝區，而是會將其原樣串流至 ProxyEndpoint 回應流程。在這種情況下，系統會略過所有在 TargetEndpoint 回應流程中對酬載運作的政策。另請參閱「串流要求和回應」。
success.codes 不適用

根據預設，Apigee 會將 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 不適用 根據預設，Apigee 會為收到的郵件設定壓縮類型 (gzip、deflate 或無)。如果從用戶端接收的要求使用 gzip 壓縮，Apigee 就會使用 gzip 壓縮將要求轉送至目標。如果從目標接收的回應使用的是 deflate，Apigee 就會使用 deflate 將回應轉送至用戶端。支援的值如下：
  • gzip：一律使用 gzip 壓縮傳送訊息
  • deflate：一律使用 deflate 壓縮方式傳送訊息
  • none：一律傳送未經壓縮的訊息

另請參閱：Apigee 是否支援使用 GZIP/deflate 壓縮功能進行壓縮/解壓縮？
request.retain.headers.
enabled		 是 根據預設，Apigee 會一律保留傳出訊息的所有 HTTP 標頭。若設為 true，則會在傳出要求上設定連入要求上的所有 HTTP 標頭。
request.retain.headers 不適用 定義要求中的特定 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		 是 根據預設，Apigee 會一律保留傳出訊息的所有 HTTP 標頭。將其設為 true 時，系統會在將外寄回應傳送至 ProxyEndpoint 之前，先在外寄回應上設定目標服務的內送回應中所列的所有 HTTP 標頭。
response.retain.headers 不適用 定義回應中的特定 HTTP 標頭，應在傳遞至 ProxyEndpoint 之前，先在外連回應上設定。舉例來說，如要傳送 Expires 標頭，請將 response.retain.headers 的值設為 Expires。多個 HTTP 標頭會以逗號分隔的清單形式指定，例如 Expires,Set-Cookie。此屬性會覆寫 response.retain.headers.enabled。如果 response.retain.headers.enabled 設為 false，則在 response.retain.headers 屬性中指定的任何標頭仍會設在傳出郵件上。
retain.queryparams.
enabled		 是 根據預設，Apigee 一律會保留傳出要求的所有查詢參數。設定為 true 時，內送要求中的所有查詢參數都會設為目標服務的傳出要求。
retain.queryparams 不適用 定義要設定在外出要求中的特定查詢參數。舉例來說，如要從要求訊息中加入查詢參數 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>
  </HTTPProxyConnection>
</ProxyEndpoint>

要求標頭

傳入 HTTP 要求包含用戶端傳送的 HTTP 標頭。如果用戶端傳送名稱符合 X-Apigee-* 模式的標頭，系統會從傳入要求中移除這些標頭。此名稱模式為 Apigee 保留。

ProxyEndpoint 運輸屬性規格

屬性名稱 預設值 說明
X-Forwarded-For false 如果設為 true，虛擬主機的 IP 位址會新增至外送要求，做為 HTTP X-Forwarded-For 標頭的值。
request.streaming.
enabled		 false 根據預設 (false)，HTTP 要求酬載會讀入緩衝區，而可在酬載上運作的政策會正常運作。如果酬載大於緩衝區大小 (在 Apigee 中為 10 MB)，您可以將此屬性設為 true。在 true 時，系統不會將 HTTP 要求酬載讀入緩衝區，而是會將酬載原封不動地串流至 TargetEndpoint 要求流程。在這種情況下，系統會略過任何在 ProxyEndpoint 要求流程中針對酬載運作的政策。另請參閱「串流要求和回應」。
response.streaming.
enabled		 false 根據預設 (false)，HTTP 回應酬載會讀入緩衝區，而可在酬載上運作的政策會正常運作。如果酬載比緩衝區大小 (在 Apigee 中為 10 MB) 大，您可以將此屬性設為 true。當 true 時，HTTP 回應酬載不會讀入緩衝區，而是會原封不動地串流至用戶端。在這種情況下，系統會略過所有在 ProxyEndpoint 回應流程中對酬載運作的政策。另請參閱「串流要求和回應」。
compression.algorithm 不適用

根據預設，Apigee 會尊重收到的郵件所設的壓縮類型 (gzip、deflate 或無)。舉例來說，如果用戶端提交使用 gzip 壓縮的請求，Apigee 會使用 gzip 壓縮方式將要求轉送至目標。您可以設定壓縮演算法，藉此明確套用 TargetEndpoint 或 ProxyEndpoint 上的這項屬性。支援的值如下：

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

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

設定個別 API 代理程式逾時時間 (以毫秒為單位)

您可以設定 API Proxy (即使已啟用串流)，讓這些 Proxy 在指定時間後逾時，並顯示 504 Gateway Timeout 狀態。

舉例來說，如要將 Proxy 設為在 180000 毫秒 (三分鐘) 後逾時，請將下列屬性新增至 HTTPProxyConnection：

<Property name="api.timeout">180000</Property>

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

請參閱「設定 io.timeout.millis 和 api.timeout」。
HTTPHeader.allowDuplicates 不適用

使用這項設定允許重複的標頭 (適用於特定標頭)。

<HTTPProxyConnection>
  <Properties>
     <Property name="HTTPHeader.allowDuplicates">Content-Type,Authorization</Property>
  </Properties>
</HTTPProxyConnection>
HTTPHeader.multiValued 不適用

使用這項設定允許重複的標頭 (適用於特定標頭)。

<HTTPProxyConnection>
  <Properties>
    <Property name="HTTPHeader.multiValued">Content-Type,Authorization</Property>
  </Properties>
</HTTPProxyConnection>

設定 io.timeout.millis 和 api.timeout

io.timeout.millis 和 api.timeout 的作業相關聯。針對每項對 API Proxy 的要求：

  1. Ingress (又稱為內部負載平衡器) 會將逾時值傳送至訊息處理器。這個逾時值的預設值為 300 秒，無法設定。
  2. 訊息處理器接著會設定 api.timeout：
    1. 如果在 Proxy 層級未設定 api.timeout，請使用 Ingress 設定的逾時時間。
    2. 如果 api.timeout 是在 Proxy 層級設定，請將其設為 Message Processor 的 Ingress 逾時時間或 api.timeout 值 (以較小者為準)。

  3. api.timeout 的值會指定 API 代理程式從 API 要求執行至回應的時間上限。

    在 API Proxy 中的每項政策執行完畢後，或在訊息處理器將要求傳送至目標端點之前，訊息處理器會計算 (api.timeout - 自要求開始起算的經過時間)。

    如果值小於零，表示處理要求的時間上限已到期，且訊息處理器會傳回 504 Gateway Timeout。

  4. io.timeout.millis 的值會指定目標端點回應所需的時間上限。

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

    如果在寫入 HTTP 要求或讀取 HTTP 回應時發生逾時情形，系統會傳回 504 Gateway Timeout。