Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

API Proxy 設定參考資料

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

身為 Apigee 開發人員，您的主要開發活動是設定 API Proxy，做為 API 或後端服務的 Proxy。本文列出建構 API Proxy 時可用的所有設定元素，

如果您正在學習如何建構 API Proxy，建議先從「建構簡單的 API Proxy」主題開始。

使用下列任一方法編輯 API Proxy 設定：

使用 Apigee UI 或 API。
下載 API Proxy 設定套件、手動編輯，然後將新設定上傳至 Apigee，詳情請參閱「下載及上傳 API Proxy 設定套件」。

API Proxy 設定目錄結構

API Proxy 設定目錄結構如下所示：

顯示目錄結構，其中 apiproxy 是根目錄。apiproxy 目錄下方直接列出 policies、proxies、resources 和 targets 目錄，以及 weatherapi.xml 檔案。

API Proxy 設定包含下列內容：

基本設定	API Proxy 的主要設定。
ProxyEndpoint	傳入 HTTP 連線 (從要求應用程式到 Apigee)、要求和回應流程，以及政策附件的設定。
TargetEndpoint	輸出 HTTP 連線 (從 Apigee 到後端服務)、要求和回應流程，以及政策附件的設定。
流程	ProxyEndpoint 和 TargetEndpoint 要求與回應管道，可附加政策。
政策	符合 Apigee 政策結構定義的 XML 格式設定檔。
資源	政策參照的指令碼、JAR 檔案和 XSLT 檔案，用於執行自訂邏輯。

基本設定

`/apiproxy/weatherapi.xml`

API Proxy 的基本設定，用於定義 API Proxy 的名稱。機構內的名稱不得重複。

範例設定：

<APIProxy name="weatherapi">
</APIProxy>

基本設定元素

名稱	說明	預設	是否必要
`APIProxy`
`name`	API Proxy 名稱，在機構內不得重複。名稱只能使用下列字元： `A-Za-z0-9_-`	不適用	是
`revision`	API Proxy 設定的修訂版本號碼。您不需要明確設定修訂版本號碼，因為 Apigee 會自動追蹤 API Proxy 的目前修訂版本。	不適用	否
`ConfigurationVersion`	這個 API Proxy 遵循的 API Proxy 設定結構定義版本。目前唯一支援的值是 majorVersion 4 和 minorVersion 0。這項設定日後可能會用於啟用 API Proxy 格式的演進功能。	4.0	否
`Description`	API Proxy 的文字說明。如果提供說明，Apigee 使用者介面就會顯示該說明。	不適用	否
`DisplayName`	使用者友善名稱，可能與 API Proxy 設定的 `name` 屬性不同。	不適用	否
`Policies`	這個 API Proxy 的 `/policies` 目錄中的政策清單。通常只有使用 Apigee UI 建立 API Proxy 時，才會看到這個元素。這只是資訊清單設定，旨在提供 API Proxy 內容的能見度。	不適用	否
`ProxyEndpoints`	這個 API Proxy 的 `/proxies` 目錄中的 Proxy 端點清單。一般來說，只有使用 Apigee UI 建立 API Proxy 時，才會看到這個元素。這只是資訊清單設定，旨在提供 API Proxy 內容的能見度。	不適用	否
`Resources`	API Proxy 的 `/resources` 目錄中的資源清單 (JavaScript、Python、Java、XSLT)。一般來說，只有使用 Apigee UI 建立 API Proxy 時，才會看到這個元素。這只是資訊清單設定，旨在提供 API Proxy 內容的能見度。	不適用	否
`Spec`	識別與 API Proxy 相關聯的 OpenAPI 規格。這個值會設為規格商店中的網址或路徑。	不適用	否
`TargetServers`	此 API Proxy 任何目標端點中參照的目標伺服器清單。一般來說，只有使用 Apigee 建立 API Proxy 時，才會看到這個元素。這只是資訊清單設定，旨在提供 API Proxy 內容的能見度。	不適用	否
`TargetEndpoints`	這個 API Proxy 的 `/targets` 目錄中的目標端點清單。一般來說，只有在使用 Apigee UI 建立 API Proxy 時，才會看到這個元素。這只是資訊清單設定，旨在提供 API Proxy 內容的能見度。	不適用	否

ProxyEndpoint

下圖顯示要求/回應流程：

顯示用戶端呼叫 HTTP 服務。要求會先經過 Proxy 端點和目標端點，然後由 HTTP 服務處理。回應會先經過目標端點和 Proxy 端點，再傳回給用戶端。

`/apiproxy/proxies/default.xml`

ProxyEndpoint 設定會定義 API Proxy 的連入 (面向用戶端) 介面。設定 Proxy 端點時，您會設定網路，定義用戶端應用程式 (應用程式) 應如何叫用 Proxy API。

下列 ProxyEndpoint 設定範例會儲存在 /apiproxy/proxies 下方：

<ProxyEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <Properties/>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

基本 Proxy 端點的必要設定元素包括：

ProxyEndpoint 設定元素

名稱說明預設是否必要

ProxyEndpoint

name Proxy 端點的名稱。如果定義多個 Proxy 端點 (極少數情況)，則必須在 API Proxy 設定中保持唯一。名稱只能使用下列字元：A-Za-z0-9._\-$ %。不適用是

PreFlow 定義要求或回應 PreFlow 流程中的政策。不適用是

Flows

定義要求或回應條件式流程中的政策。

不適用

是

PostFlow

定義要求或回應的 PostFlow 流程中的政策。

不適用

是

HTTPProxyConnection 定義與 API Proxy 相關聯的網路位址和 URI 路徑。

BasePath

必要字串，用於準確識別 Apigee 用來將傳入訊息路由至適當 API Proxy 的 URI 路徑。

BasePath 是附加至 API Proxy 基準網址 (例如 http://apifactory-test.apigee.net) 的 URI 片段 (例如 /weather)。BasePath 在環境中必須是唯一的。產生或匯入 API Proxy 時，系統會驗證唯一性。

在基本路徑中使用萬用字元

您可以在 API Proxy 的基本路徑中使用一或多個「*」萬用字元。舉例來說，如果基本路徑為 /team/*/members，用戶端就能呼叫 https://[host]/team/blue/members 和 https://[host]/team/green/members，您不必建立新的 API Proxy 來支援新團隊。請注意，系統不支援 /**/。

重要事項：Apigee「不」支援使用萬用字元「*」做為基本路徑的第一個元素。舉例來說，系統「不」支援 /*/search。如果基本路徑以「*」開頭，Apigee 識別有效路徑的方式可能會導致非預期的錯誤。

是

Properties

您可以將一組選用的 HTTP 設定定義為 <ProxyEndpoint> 的屬性。可用的屬性包括：

request.queryparams.ignore.content.type.charset

使用 request.queryparams.ignore.content.type.charset 屬性，告知 Proxy 在處理要求網址時忽略 Content-Type 標頭的 charset 參數。例如：

<Properties>
  <Property name="request.queryparams.ignore.content.type.charset">true</Property>
</Properties>

下表顯示範例輸出內容，具體取決於 charset 屬性的設定，以及 Content-Type 標頭的 charset 參數是否存在。

資源設定	標頭值	輸出範例
`charset=false`	未設定「`charset`」參數	john.doe+test@gmail.com
`charset=false`	`charset=utf-8`	john.doe test@gmail.com
`charset=true`，且標頭中沒有 `charset` 參數。	未設定「`charset`」參數	john.doe+test@gmail.com
`charset=true`	`charset=utf-8` 參數集	john.doe+test@gmail.com

request.payload.parse.limit
使用 request.payload.parse.limit 屬性設定要求流程中可處理的酬載大小上限 (以 MB 為單位)。

例如：
```
<Properties>
  <Property name="request.payload.parse.limit">30M</Property>
</Properties>
```
可設定的最小限制為 10M，最大限制為 30M。如未設定這個屬性，預設限制為 1000 萬。

詳情請參閱「訊息酬載大小」。

不適用

否

FaultRules

定義 Proxy 端點對錯誤的反應方式。錯誤規則會指定兩個項目：

條件：根據預先定義的錯誤類別、子類別或名稱，指定要處理的錯誤
一或多項政策，用於定義相應條件的錯誤規則行為

請參閱「處理錯誤」。

不適用

否

DefaultFaultRule

處理未由其他錯誤規則明確處理的任何錯誤 (系統、傳輸、訊息或政策)。

請參閱「處理錯誤」。

不適用

否

RouteRule 定義 ProxyEndpoint 要求管道處理後，傳入要求訊息的目的地。通常 RouteRule 會指向具名目標端點、IntegrationEndpoint 或網址。

Name 必要屬性，可為 RouteRule 提供名稱。名稱只能使用下列字元：A-Za-z0-9._\-$ %。舉例來說，Cat2 %_ 是法定姓名。不適用是

Condition (選用) 執行階段用於動態轉送的條件陳述式。舉例來說，條件式 RouteRule 可用於啟用內容轉送，支援後端版本控管。不適用否

TargetEndpoint

這是選用字串，用於識別具名的 TargetEndpoint 設定。具名目標端點是指在相同 API Proxy 的 /targets 目錄下定義的任何目標端點。

命名目標端點時，請指出要求訊息在 ProxyEndpoint 要求管道處理後，應轉送至何處。請注意，這是選用設定。

Proxy 端點可能會直接呼叫網址。舉例來說，以 HTTP 用戶端角色運作的 JavaScript 或 Java 資源，可能會執行目標端點的基本職責，也就是將要求轉送至後端服務。

不適用

否

URL 選用字串，用於定義 Proxy 端點呼叫的輸出網路位址，略過可能儲存在 /targets 下的任何 TargetEndpoint 設定。不適用否

如何設定 RouteRules

具名目標端點是指 /apiproxy/targets 下的設定檔，RouteRule 會在 Proxy 端點處理要求後，將要求轉送至該設定檔。

舉例來說，下列 RouteRule 會參照設定 /apiproxy/targets/myTarget.xml：

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

直接叫用網址

Proxy 端點也可以直接叫用後端服務。直接叫用網址會略過 /apiproxy/targets 下的任何具名 TargetEndpoint 設定。因此，TargetEndpoint 是選用的 API Proxy 設定，但實際上不建議從 Proxy 端點直接叫用。

舉例來說，下列 RouteRule 會對 http://api.mycompany.com/v2 發出 HTTP 呼叫。

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

條件式路徑

RouteRules 可以串連，在執行階段支援動態轉送。根據 HTTP 標頭、訊息內容、查詢參數或情境資訊 (例如時間、語言代碼等)，將傳入要求直接路由至網址，或路由至具名 TargetEndpoint 設定，或路由至兩者的組合。

條件式 RouteRule 的運作方式與 Apigee 上的其他條件式陳述式類似。請參閱「條件參考資料」和「流程變數參考資料」。

舉例來說，下列 RouteRule 組合會先評估傳入要求，驗證 HTTP 標頭的值。如果 HTTP 標頭 routeTo 的值為 TargetEndpoint1，要求就會轉送至名為 TargetEndpoint1 的目標端點。如果沒有，系統會將傳入要求轉送至 http://api.mycompany.com/v2。

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

空值路徑

您可以定義空值 RouteRule，支援要求訊息不需要轉送至目標端點的情況。如果 Proxy 端點會執行所有必要的處理作業，例如使用 JavaScript 呼叫外部服務，或從 Apigee 鍵/值存放區的查閱作業中擷取資料，這項功能就非常實用。

舉例來說，下列程式碼會定義空值路徑：

<RouteRule name="GoNowhere"/>

有條件的空值路徑可能很有用。在下列範例中，系統會設定空值路徑，在 HTTP 標頭 request.header.X-DoNothing 的值不是 null 時執行。

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

請注意，RouteRule 可以串連，因此條件式空值 Route 通常是設計用來支援條件式轉送的一組 RouteRule 的其中一個元件。

條件式空值 Route 的實用用途是支援快取。使用 Cache 政策設定的變數值，您可以將 API Proxy 設為在從快取提供項目時，執行空值路徑。

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

顯示用戶端呼叫 HTTP 服務。要求會先經過 Proxy 端點和目標端點，然後由 HTTP 服務處理。回應會先經過目標端點和 Proxy 端點，再傳回給用戶端。

目標端點是 Proxy 端點的對外等效項目。目標端點會做為後端服務或 API 的用戶端，傳送要求並接收回應。

API Proxy 不一定要有任何目標端點。Proxy 端點可設定為直接呼叫網址。沒有目標端點的 API Proxy 通常包含 Proxy 端點，可直接呼叫後端服務，或設定為使用 Java 或 JavaScript 呼叫服務。

TargetEndpoint 設定

`/targets/default.xml`

目標端點會定義從 Apigee 到其他服務或資源的出站連線。

以下是 TargetEndpoint 設定範例：

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <EventFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
    <Authentication/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

TargetEndpoint 設定元素

目標端點可以透過下列其中一種方式呼叫目標：

適用於 HTTP 或 HTTPS 呼叫的 HTTPTargetConnection
本機 Proxy 對 Proxy 鏈結的 LocalTargetConnection

在目標端點中，只能設定其中一個。

名稱	說明	預設	是否必要
`TargetEndpoint`
`name`	目標端點名稱，在 API Proxy 設定中不得重複。ProxyEndpoint RouteRule 會使用目標端點名稱，將要求導向輸出處理程序。名稱只能使用下列字元：`A-Za-z0-9._\-$ %`。	不適用	是
`PreFlow`	定義要求或回應 PreFlow 流程中的政策。	不適用	是
`Flows`	定義要求或回應條件式流程中的政策。	不適用	是
`PostFlow`	定義要求或回應的 PostFlow 流程中的政策。	不適用	是
`EventFlow`	定義回應的 EventFlow 流程中的政策。EventFlow 用於串流伺服器推送事件。詳情請參閱「串流伺服器傳送事件」。	不適用	否
`HTTPTargetConnection`	與子項元素一起指定透過 HTTP 存取的後端資源。如果您使用 HTTPTargetConnection，請勿設定其他類型的目標連線 (ScriptTarget 或 LocalTargetConnection)。附註：`<LocalTargetConnection>` 元素支援名為「訊息範本」的動態字串替代功能。您可以使用 `<Authentication>` 子元素，向 Google 服務或在特定 Google Cloud 產品 (例如 Cloud Functions 和 Cloud Run) 上執行的自訂服務發出已通過驗證的呼叫。如要使用 `<Authentication>` 元素，請按照「使用 Google 驗證」一文所述的步驟進行設定及部署。設定完成後，這項政策會為您建立驗證權杖，並將其新增至服務要求。另請參閱 `<Authentication>` 元素用法。
`URL`	定義後端服務的網路位址，目標端點會將要求訊息轉送至該位址。	不適用	否
`LoadBalancer`	定義一或多個具名的 TargetServer 設定。具名的 TargetServer 設定可用於負載平衡，定義 2 個以上的端點設定連線。您也可以使用目標伺服器，將 API Proxy 設定與具體後端服務端點網址分離。	不適用	否
`Properties`	您可以將一組選用的 HTTP 設定定義為 `<TargetEndpoint>` 的屬性。使用 `response.payload.parse.limit` 屬性設定回應流程中可處理的酬載大小上限 (以 MB 為單位)。例如： <Properties> <Property name="response.payload.parse.limit">15M</Property> </Properties> 可設定的最小限制為 10M，最大限制為 30M。如未設定這個屬性，預設限制為 1000 萬。詳情請參閱「訊息酬載大小」。	不適用	否
`SSLInfo`	(選用) 在目標端點上定義 TLS/SSL 設定，控管 API Proxy 與目標服務之間的 TLS/SSL 連線。請參閱「TLS/SSL TargetEndpoint Configuration」。注意：`<SSLInfo>` 元素支援稱為「訊息範本」的動態字串替代功能。	不適用	否
`LocalTargetConnection`	與子項元素搭配使用，可指定要在本機連線的資源，略過負載平衡和訊息處理器等網路特性。如要指定目標資源，請加入 APIProxy 子項元素 (含 ProxyEndpoint 元素) 或 Path 子項元素。詳情請參閱「鏈結多個 API Proxy」。如果您使用 LocalTargetConnection，請勿設定其他類型的目標連線 (HTTPTargetConnection 或 ScriptTarget)。
`APIProxy`	指定要用做要求目標的 API Proxy 名稱。目標 Proxy 必須與傳送要求的 Proxy 位於相同機構和環境。這是 Path 元素的替代方案。	不適用	否
`ProxyEndpoint`	與 APIProxy 搭配使用，可指定目標 Proxy 的 Proxy 端點名稱。	不適用	否
`Path`	指定 API Proxy 的端點路徑，做為要求目標。目標 Proxy 必須與傳送要求的 Proxy 位於相同機構和環境。這是 APIProxy 的替代方案。	不適用	否
`FaultRules`	定義目標端點對錯誤的反應方式。錯誤規則會指定兩個項目：條件：根據預先定義的錯誤類別、子類別或名稱，指定要處理的錯誤一或多項政策，用於定義相應條件的錯誤規則行為請參閱「處理錯誤」。	不適用	否
`DefaultFaultRule`	處理未由其他 FaultRule 明確處理的任何錯誤 (系統、傳輸、訊息或政策)。請參閱「處理錯誤」。	不適用	否

`<Authentication>` 元素用法

<TargetEndpoint> 中的 <Authentication> 元素用法與 ServiceCallout 政策中的 <Authentication> 元素用法相同。在 <TargetEndpoint> 和 ServiceCallout 中，<Authentication> 都是 <HttpTargetConnection> 的子元素。詳情請參閱 ServiceCallout 政策參考資料中的「驗證」元素。

`<Authentication>` 元素錯誤參考資料

如果您使用 <Authentication> 元素，可以在 ServiceCallout 政策文件的「錯誤」部分中，找到部署和執行階段錯誤的可能錯誤訊息和疑難排解提示。

`<Authentication>` 元素範例

以下範例說明如何呼叫部署在 Cloud Run 上的服務做為目標，並使用 Authentication 元素產生驗證呼叫所需的 OpenID Connect 權杖：

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
      <Properties/>
      <URL>https://cloudrun-hostname.a.run.app/test</URL>
      <Authentication>
          <GoogleIDToken>
             <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
          </GoogleIDToken>
     </Authentication>
  </HTTPTargetConnection>
</TargetEndpoint>

以下範例說明如何使用 Authentication 元素產生驗證呼叫所需的 OpenID Connect 權杖，藉此呼叫指向 Cloud Run 的 TargetService。HeaderName 元素會將產生的不記名權杖新增至名為 X-Serverless-Authorization 的標頭，並傳送至目標系統。如果存在 Authorization 標頭，則會保留不變，並一併傳送至要求。

<TargetEndpoint name="TargetEndpoint-1">
   <HTTPTargetConnection>
     <Authentication>
        <HeaderName>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
            <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
      <LoadBalancer>
         <Server name="cloud-run-target" />
      </LoadBalancer>
   </HTTPTargetConnection>
</TargetEndpoint>

以下範例說明如何呼叫指向 Google Secret Manager 服務的 TargetService。在本範例中，GoogleAccessToken 元素會產生 Google 驗證權杖，以驗證目標要求：

<HTTPTargetConnection>
   <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
</HTTPTargetConnection>

以下範例說明如何自動設定 GoogleIDToken 的目標對象。如果 useTargetUrl 為 true，且參照的變數無法解析為有效變數，系統會將目標網址 (不含查詢參數) 做為目標對象。假設要求路徑為 /foobar，目標伺服器網址為 https://xyz.com，GoogleIDToken 的對象會自動設為 https://xyz.com/foobar。

Apigee Hybrid 使用者： 如果您使用 Apigee Hybrid，請注意 useTargetUrl 屬性適用於 Apigee Hybrid 1.8 以上版本。

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience ref='myvariable' useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
    <LoadBalancer>
      <Server name="TS" />
    </LoadBalancer>
  </HTTPTargetConnection>
</TargetEndpoint>

TLS/SSL TargetEndpoint 設定

目標端點通常需要管理與異質後端基礎架構的 HTTPS 連線。因此，系統支援多項 TLS/SSL 設定。

重要事項：公開憑證授權單位 (CA) 將停止在最新的公開信任 SSL/TLS 憑證中加入「擴展金鑰用途」(EKU) clientAuth。這項全產業的變更會影響 Apigee 平台中的 Apigee 雙向傳輸層安全標準 (mTLS) 設定。

Apigee 要求用戶端憑證必須有 clientAuth EKU，才能進行 mTLS 握手。如果沒有這個 EKU，南北向 (用戶端到 Apigee) 和南向 (Apigee 到後端) 流量的 mTLS 連線都會失敗。如需問題、時間表和建議解決方案的詳細說明，請參閱這篇網誌文章。

TLS/SSL TargetEndpoint 設定元素

名稱	說明	預設	是否必要
`SSLInfo`	`<SSLInfo>` 區塊可用於單向和雙向 TLS/SSL。
`Enabled`	設為 `true` 時，表示目標連線應根據這個 `<SSLInfo>` 區塊中指定的任何其他參數，使用 SSL 通訊協定。如果設為 `false`，表示目標連線不應使用 SSL。不過，如果封閉的 `<HTTPTargetConnection>` 區塊包含評估為以 `https://` 開頭字串的 `<URL>` 元素，即使 `<Enabled>` 為 false，系統仍會使用 SSL 協定。在這種情況下，系統會忽略整個 `<SSLInfo>` 區塊。反之，如果 `<URL>` 元素開頭為 `http://`，即使 `<Enabled>` 為 true，系統也不會使用 SSL 通訊協定。	false	否
`Enforce`	在 Apigee 與目標後端之間強制執行嚴格的 SSL。如果設為 `true`，系統會針對憑證無效、憑證過期、自簽憑證、主機名稱不符的憑證，以及根憑證不受信任的目標，連線失敗。系統會傳回 `4xx` 或 `5xx` 的失敗代碼。如果未設定或設為 `false`，連線至有問題憑證的目標後端時，結果取決於 `<IgnoreValidationErrors>` 的設定 (請參閱下文)。在特定情況下，如果 `<IgnoreValidationErrors>` 設為 `true`，可能會出現成功的回應 (`2xx`)。您可以使用功能旗標 `SSLInfo.Enforce`，在環境層級覆寫 `Enforce` 欄位。請參閱「指定環境層級的 SSL 強制執行」。	`false`	否
`TrustStore`	含有受信任根伺服器憑證的金鑰儲存庫。如果遠端對等互連傳送的憑證鏈結終止於這個 KeyStore 中包含的憑證，Apigee 就會將遠端對等互連視為信任對象。	不適用	否
`ClientAuthEnabled`	如果設為 `true`，則會在 Apigee 和遠端對等互連 (API 用戶端或目標後端) 之間啟用雙向 TLS (也稱為相互 TLS 或 mTLS)。啟用雙向 TLS 時，通常需要在 Apigee 上設定信任儲存區和金鑰儲存區。	`false`	否
`KeyStore`	含有用於用戶端外送驗證的私密金鑰的金鑰儲存區	不適用	是 (如果 ClientAuthEnabled 為 true)
`KeyAlias`	用於外送用戶端驗證的私密金鑰別名	不適用	是 (如果 ClientAuthEnabled 為 true)
`IgnoreValidationErrors`	指出是否忽略驗證錯誤。如果後端系統使用 SNI 並傳回主體識別名稱 (DN) 與主機名稱不符的憑證，系統無法忽略錯誤，連線會失敗。附註：如果 `<Enforce>` 設為 `true`，系統會忽略 `<IgnoreValidationErrors>` 的值。	`false`	否
`Ciphers`	支援外送 TLS/SSL 的密碼。如未指定任何密碼，系統會允許 JVM 可用的所有密碼。如要限制密碼，請新增下列元素，列出支援的密碼： <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers>	不適用	否
`Protocols`	出站 TLS/SSL 支援的通訊協定。如未指定通訊協定，則允許 JVM 可用的所有通訊協定。如要限制通訊協定，請明確指定。舉例來說，如要只允許 TLS v1.2 或 TLS v1.3： <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols> 注意：Apigee Hybrid 不支援 TLS 1.0 的南向連線。	不適用	否
`CommonName`	Apigee 會檢查這裡的值，是否與遠端對等互連憑證上的 CN (一般名稱) 或 SAN (主體別名) 相符。	不適用	否

指定環境層級的 SSL 強制執行

如果 SSLInfo.Enforce 設為 true 或 false，指定的值會覆寫 TargetEndpoint 或 TargetServer 設定中 <SSLInfo> 區塊指定的任何細微強制執行選項。

如果未設定 SSLInfo.Enforce，系統會根據個別 <SSLInfo> 區塊中 <Enforce> 元素指定的值，判斷是否強制執行 SSL。詳情請參閱「TLS/SSL TargetEndpoint configuration」(TLS/SSL TargetEndpoint 設定)。

在以下範例中，SSLInfo.Enforce 會設為 true。在產生的輸出內容中，您可以看到系統在指定環境中強制執行 SSL。

VALUE=true
curl -Ss -v -X PUT \
    "https://apigee.googleapis.com/v1/organizations/MYORG/environments/MYENV" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer TOKEN" \
    -d '{
        "name": "MYENV",
        "properties": {
            "property": [{
                "name": "features.SSLInfo.Enforce",
                "value": "'"$VALUE"'"
            }]
        }
    }'

輸出內容：

{
  ...
  "properties": {
    "property": [
      {
        "name": "features.SSLInfo.Enforce",
        "value": "true"
      }
    ]
  },
  ...
}

已啟用傳出用戶端驗證的目標端點範例

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <Enforce>true</Enforce>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

如需詳細操作說明，請參閱「傳輸層安全標準 (TLS) 設定選項」。

使用流程變數動態設定 TLS/SSL 值

您也可以動態設定 TLS/SSL 詳細資料，以支援彈性的執行階段需求。舉例來說，如果您的 Proxy 連線至兩個可能不同的目標 (測試目標和正式環境目標)，您可以讓 API Proxy 以程式輔助方式偵測呼叫的環境，並動態設定適當金鑰儲存區和信任儲存區的參照。使用變數參照的 TargetEndpoint 動態 SSLInfo Apigee 社群文章更詳細地說明這個情境，並提供可部署的 API Proxy 範例。

在下列範例中，我們說明如何在 TargetEndpoint 設定中設定 <SSLInfo> 標記。您可以在執行階段提供值，例如透過 Java Callout、JavaScript 政策或 AssignMessage 政策。使用包含要設定值的訊息變數。

變數只能用於下列元素。

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

使用參照動態設定 TLS/SSL 值

設定使用 HTTPS 的目標端點時，您必須考慮 TLS/SSL 憑證過期，或系統設定變更而需要更新憑證的情況。

詳情請參閱「處理過期憑證」。

不過，您可以視需要設定目標端點，改為使用金鑰儲存區或信任儲存區的參照。使用參照的優點是，您可以更新參照，指向其他金鑰儲存區或信任儲存區，藉此更新 TLS/SSL 憑證，而不必重新啟動訊息處理器。

舉例來說，以下是使用金鑰儲存區參照的目標端點：

<SSLInfo>
  <Enabled>true</Enabled>
  <ClientAuthEnabled>false</ClientAuthEnabled>
  <KeyStore>ref://keystoreref</KeyStore>
  <KeyAlias>myKeyAlias</KeyAlias>
</SSLInfo>

使用下列 POST API 呼叫建立名為 keystoreref 的參照：

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/references" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>'

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述。如要瞭解本範例使用的 curl 選項，請參閱「使用 curl」。如要瞭解可使用的環境變數，請參閱「為 Apigee API 要求設定環境變數」。

參照會指定金鑰儲存區的名稱和類型。

使用下列 GET API 呼叫查看參照：

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

如要稍後變更參照，指向其他金鑰儲存區，請確保別名名稱相同，並使用下列 PUT 呼叫：

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/references/keystoreref" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'

TargetEndpoint 搭配目標負載平衡

目標端點支援使用三種負載平衡演算法，在多個具名目標伺服器之間進行負載平衡。

如需詳細操作說明，請參閱「跨後端伺服器負載平衡」。

IntegrationEndpoint

IntegrationEndpoint 是專門執行 Apigee 整合的目標端點。如果您已設定 IntegrationEndpoint，Apigee 會將 request 物件傳送至 Apigee 的 Integration Platform 執行。如要執行整合，除了設定 IntegrationEndpoint 之外，您也必須在 Proxy 流程中新增 SetIntegrationRequest 政策。

您可以在 IntegrationEndpoint 設定中設定 <AsyncExecution> 元素，將整合服務設為同步或非同步執行。詳情請參閱「同步與非同步執行」。執行整合作業後，Apigee 會將回應儲存在回應訊息中。

注意：您需要驗證權杖才能執行 IntegrationEndpoint。不過，IntegrationEndpoint 定義中沒有明確的 <Authentication> 元素。Apigee 會在幕後將驗證權杖新增至要求。如要讓 IntegrationEndpoint 順利完成驗證，您必須使用具備執行整合作業所需 IAM 角色的服務帳戶，部署 API Proxy。如要瞭解必要角色，請參閱「整合的 IAM 角色」。如要進一步瞭解如何部署 API Proxy，請參閱「在 Apigee 上部署」。

設定 IntegrationEndpoint

如要將整合端點設為目標端點，請在 ProxyEndpoint 設定中新增 IntegrationEndpoint 元素。以下是 ProxyEndpoint 設定範例：

<ProxyEndpoint name="default">
    <Description/>
    <FaultRules/>
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>my-set-integration-request-policy</Name>
            </Step>
        </Request>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow"/>
    <HTTPProxyConnection>
        <BasePath>/integration-endpoint-test</BasePath>
        <Properties/>
    </HTTPProxyConnection>
    <RouteRule name="default">
        <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint>
    </RouteRule>
</ProxyEndpoint>

在 ProxyEndpoint 設定範例中，Apigee 會執行下列工作：

在 PreFlow 中，執行名為 my-set-integration-request-policy 的政策，設定整合要求物件和整合流程變數。
使用 my-int-endpoint 做為目標端點，如 RouteRule 中所指定。
讀取 my-set-integration-request-policy 建立的整合要求物件。
使用 SetIntegrationRequest 政策設定的要求物件和流程變數，將要求傳送至 Apigee 的整合平台。
將整合的回應儲存至回應訊息。

含有 <IntegrationEndpoint> 宣告的 XML 檔案會位於 APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/ 目錄中。如果您使用 Develop > API Proxies > CREATE NEW > Integration target 選項建立 API Proxy，Apigee 會將宣告儲存在 /apiproxy/integration-endpoints/default.xml 檔案中。如果從 UI 建立整合端點 XML，可以為 XML 檔案提供自訂名稱。

以下範例顯示 XML 檔案中的 <IntegrationEndpoint> 元素宣告：

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>false</AsyncExecution>
</IntegrationEndpoint>

IntegrationEndpoint 設定元素

名稱	說明	預設	是否必要
`IntegrationEndpoint`
`name`	IntegrationEndpoint 的名稱。名稱只能使用以下字元： `A-Za-z0-9._\-$ %`	不適用	是
`AsyncExecution`	布林值，用於指定整合功能應以同步或非同步模式執行。詳情請參閱「同步與非同步執行」。	false	否

同步與非同步執行作業

您可以將整合功能設定為以同步或非同步模式執行。如要瞭解同步和非同步執行模式之間的差異，請參閱 <AsyncExecution>。

在 </IntegrationEndpoint> 中使用 <AsyncExecution> 元素，指定同步或非同步執行。如果將 <AsyncExecution> 設為 true，整合作業會非同步執行。如果將其設為 false，整合功能就會同步執行。

以下範例會將 AsyncExecution 設為 true：

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>true</AsyncExecution>
</IntegrationEndpoint>

政策

API Proxy 中的 /policies 目錄包含所有可附加至 API Proxy 中流程的政策。

政策設定元素

名稱	說明	預設	是否必要
`Policy`
`name`	政策的內部名稱。名稱只能使用以下字元：`A-Za-z0-9._\-$ %`。不過，Apigee 使用者介面會強制執行其他限制，例如自動移除非英數字元。視需要使用 `<DisplayName>` 元素，在 Apigee UI 代理程式編輯器中，以其他自然語言名稱標示政策。	不適用	是
`enabled`	設為 `true` 可強制執行政策。設為 `false` 即可關閉這項政策。即使政策仍附加至流程，系統也不會強制執行。	`true`	否
`continueOnError`	設為 `false`，在政策失敗時傳回錯誤。這是大多數政策的預期行為。設為 `true`，即使政策失敗，流程執行作業仍會繼續。	`false`	否
`async`	注意：這項屬性不會讓政策以非同步方式執行。在大多數情況下，請保留預設值 `false`。如果設為 `true`，政策執行作業會卸載至其他執行緒，讓主執行緒可處理額外要求。離線處理完成後，主執行緒會返回並完成訊息流程的處理作業。在某些情況下，將 async 設為 `true` 可提升 API Proxy 效能。不過，過度使用非同步作業可能會導致執行緒切換次數過多，進而影響效能。如要在 API Proxy 中使用非同步行為，請參閱 JavaScript 物件模型。	`false`	否

政策附加

下圖顯示 API Proxy 流程的執行順序：

顯示用戶端呼叫 HTTP 服務。要求會遇到 Proxy 端點和目標端點，其中各包含觸發政策的步驟。HTTP 服務傳回回應後，目標端點和 Proxy 端點會處理該回應，然後再傳回給用戶端。與要求一樣，回應會由步驟中的政策處理。

如上所示：

政策會以處理步驟的形式附加至流程。政策名稱用於參照要以處理步驟強制執行的政策。政策附件的格式如下：

<Step><Name>MyPolicy</Name></Step>

系統會按照政策附加至流程的順序強制執行政策。例如：

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

政策附加設定元素

名稱	說明	預設	是否必要
`Step`
`Name`	這個步驟定義要執行的政策名稱。	不適用	是
`Condition`	決定是否強制執行政策的條件陳述式。如果政策有相關聯的條件，則只有在條件陳述式評估為 true 時，政策才會執行。	不適用	否

流程

ProxyEndpoint 和 TargetEndpoint 會定義要求和回應訊息處理的管道。處理管道包含要求流程和回應流程。每個要求流程和回應流程都會細分為 PreFlow、一或多個選用的條件或具名流程，以及 PostFlow。

PreFlow：一律會執行。在任何條件式流程之前執行。
PostFlow：一律會執行。在任何條件式流程後執行。

此外，您可以在 Proxy 端點中新增 PostClientFlow，在回應傳回給要求用戶端應用程式後執行。只有 MessageLogging 政策可以附加至這個流程。PostClientFlow 可減少 API Proxy 延遲，並提供資訊供記錄，這些資訊要等到回應傳回給用戶端後才會計算，例如 client.sent.start.timestamp 和 client.sent.end.timestamp。這個流程主要用於測量回應訊息的開始和結束時間戳記之間的時間間隔。

以下是附加訊息記錄政策的 PostClientFlow 範例。

...
  <PostFlow name="PostFlow">
      <Request/>
      <Response/>
  </PostFlow>
  <PostClientFlow>
      <Request/>
      <Response>
          <Step>
              <Name>Message-Logging-1</Name>
          </Step>
      </Response>
  </PostClientFlow>
  ...

API Proxy 處理管道會依下列順序執行 Flow：

要求管道：

Proxy 要求 PreFlow
Proxy 要求條件流程 (選用)
Proxy Request PostFlow
目標要求 PreFlow
目標要求條件流程 (選用)
目標要求 PostFlow

回覆管道：

目標回應 PreFlow
目標回應條件流程 (選用)
目標回應 PostFlow
Proxy 回應 PreFlow
Proxy 回應條件流程 (選用)
Proxy 回應 PostFlow
PostClientFlow 回應 (選填)

只有附加政策的流程需要在 ProxyEndpoint 或 TargetEndpoint 設定中設定。只有在 PreFlow 或 PostFlow 處理期間需要強制執行政策時，才需在 ProxyEndpoint 或 TargetEndpoint 設定中指定 PreFlow 和 PostFlow。

與條件流程不同的是，PreFlow 和 PostFlow 元素的順序並不重要，API Proxy 一律會在管道中的適當時間點執行每個元素，無論這些元素出現在端點設定中的哪個位置。

條件式流程

Proxy 端點和目標端點支援無數個條件式流程 (也稱為「具名流程」)。

API Proxy 會測試條件流程中指定的條件，如果符合條件，API Proxy 就會執行條件流程中的處理步驟。如果條件不符，系統會略過條件流程中的處理步驟。系統會依據 API Proxy 中定義的順序評估條件流程，並執行第一個符合條件的流程。

定義條件流程後，您就能根據下列項目，在 API Proxy 中套用處理步驟：

要求 URI
HTTP 動詞 (GET/PUT/POST/DELETE)
查詢參數、標頭和表單參數的值
其他許多類型的健康狀況

舉例來說，下列條件式流程指定只有在要求資源路徑為 /accesstoken 時，才會執行。任何路徑為 /accesstoken 的傳入要求都會導致執行此流程，以及附加至流程的任何政策。如果要求路徑不含 /accesstoken 後置字串，流程就不會執行 (但可能會執行其他條件式流程)。

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request>
  </Flow>
</Flows>

流程設定元素

名稱	說明	預設	是否必要
`Flow`	由 Proxy 端點或目標端點定義的要求或回應處理管道
`Name`	流程的專屬名稱。	不適用	是
`Condition`	條件式陳述式，可評估一或多個變數，結果為 true 或 false。除了預先定義的 PreFlow 和 PostFlow 類型，所有流程都必須定義執行條件。不過，如果在流程序列結尾加入沒有條件的單一流程，該流程就會在流程序列結尾充當「Else」陳述式。	不適用	是
`Request`	與「要求」訊息處理程序相關聯的管道	不適用	否
`Response`	與「回應」訊息處理作業相關聯的管道	不適用	否

步驟處理

Apigee 會強制執行條件式流程的順序。條件流程會由上而下執行。系統會執行條件評估結果為 true 的第一個條件式流程，且只會執行一個條件式流程。

舉例來說，在下列 Flow 設定中，任何未包含路徑尾碼 /first 或 /second 的連入要求，都會導致 ThirdFlow 執行，強制執行名為 Return404 的政策。

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

資源

「資源」(用於 API Proxy 的資源檔案) 是指可使用政策附加至流程的指令碼、程式碼和 XSL 轉換。這些內容會顯示在 Apigee UI 的 API Proxy 編輯器「Scripts」部分。

如要瞭解支援的資源類型，請參閱「管理資源」。

資源可以儲存在 API Proxy、環境或機構中。在上述任一情況下，資源都會在政策中依名稱參照。Apigee 會從 API Proxy、環境到機構層級，依序解析名稱。

儲存在機構層級的資源可供任何環境中的政策參照。環境層級儲存的資源可供該環境中的政策參照。儲存在 API Proxy 層級的資源只能由該 API Proxy 中的政策參照。