端點屬性參考資料

本頁內容適用於 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 狀態碼。在某些情況下，當 LoadBalancer 用於 TargetServer 定義，且發生逾時時，可能會傳回 HTTP 504 狀態碼。 注意：在某些情況下，Apigee 會自動重試連線最多三次。 因此，重試總時間可能會超過為 connect.timeout.millis 設定的時間。
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 Hybrid 覆寫檔案包含 HTTP_PROXY 設定 (如「為 API Proxy 設定轉送 Proxy」一文所述)，請使用這個屬性管理/控管哪些 Proxy 不應使用 Proxy 設定。 如果設為 false，API Proxy 會略過 Apigee Hybrid 覆寫檔案中指定的 HTTP Proxy 設定，以用於 Proxy 中設定的目標連線。
use.proxy.tunneling	是	如果設為 true，且已在 Apigee Hybrid 覆寫檔案中指定 Proxy 設定 (如「為 API Proxy 設定轉送 Proxy」一文所述)，則目標連線會設為使用指定的通道。如果目標使用 TLS/SSL，系統會忽略這項屬性，並一律透過通道傳送訊息。
response.payload. parse.limit	10M	預設值 (10M)。使用 response.payload.parse.limit 屬性設定回應流程中可處理的酬載大小上限 (以 MB 為單位)。可設定的最小限制為 10M，最大限制為 30M。如未設定這項屬性，預設限制為 1000 萬。 另請參閱訊息酬載大小。
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 或 none)。如果要求是從用戶端收到，且使用 gzip 壓縮等方式，Apigee 會使用 gzip 壓縮將要求轉送至目標。如果從目標收到的回應使用 deflate，Apigee 會使用 deflate 將回應轉送給用戶端。支援的值如下： gzip：一律使用 gzip 壓縮傳送訊息 deflate：一律使用 deflate 壓縮傳送訊息 無：一律傳送未經壓縮的訊息 另請參閱：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 時，目標服務傳送的入站回應中，所有 HTTP 標頭都會設為出站回應，然後傳遞至 ProxyEndpoint。
response.retain.headers	不適用	定義應在傳遞至 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	是	根據預設，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 要求流程中對酬載執行的任何政策。另請參閱「串流要求和回應」。
request.payload. parse.limit	10M	預設值 (10M)。使用 request.payload.parse.limit 屬性設定要求流程中可處理的酬載大小上限 (以 MB 為單位)。可設定的最小限制為 10M，最大限制為 30M。如未設定這項屬性，預設限制為 1000 萬。 另請參閱訊息酬載大小。
response.streaming. enabled	false	根據預設 (false)，HTTP 回應負載會讀取至緩衝區，且可對負載執行的政策會正常運作。如果酬載大於緩衝區大小 (在 Apigee 中為 10 MB)，您可以將這個屬性設為 true。如果是 true，HTTP 回應負載不會讀取到緩衝區，而是會以串流形式原封不動地傳送至用戶端。在這種情況下，系統會略過在 ProxyEndpoint 回應流程中對酬載執行的任何政策。另請參閱「串流要求和回應」。
compression.algorithm	不適用	根據預設，Apigee 會遵守收到的訊息所設定的壓縮類型 (gzip、deflate 或 none)。舉例來說，如果用戶端提交的要求使用 gzip 壓縮，Apigee 會使用 gzip 壓縮將要求轉送至目標。您可以在 TargetEndpoint 或 ProxyEndpoint 上設定這項屬性，明確套用壓縮演算法。支援的值如下： gzip：一律使用 gzip 壓縮傳送訊息 deflate：一律使用 deflate 壓縮傳送訊息 無：一律傳送未經壓縮的訊息 另請參閱：Apigee 是否支援使用 GZIP/deflate 壓縮進行壓縮/解壓縮？
api.timeout	不適用	設定個別 API Proxy 的逾時時間 (以毫秒為單位) 您可以設定 API Proxy (包括啟用串流的 Proxy)，在指定時間後以 504 Gateway Timeout 狀態逾時。 重要事項： 指定的逾時時間必須短於標準訊息處理器逾時時間 (300 秒)。 舉例來說，如要將 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. 如果api.timeout未在 Proxy 層級設定，請使用 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。