API Proxy 設定參考資料

您正在查看 Apigee Edge 說明文件。
參閱 Apigee X 說明文件
資訊

身為使用 Apigee Edge 的開發人員,您的主要開發活動包括將 API Proxy 設定為 API 或後端服務的 Proxy。本文件提供建構 API Proxy 時可用所有設定元素的參考資料。

如果您瞭解如何建構 API Proxy,建議您先從「建構簡單的 API Proxy」主題開始。

編輯 Proxy 設定最常見的方式如下:

本機開發 Proxy 設定

您可以下載 Proxy 設定,以便在本機電腦上編輯。完成後,請將結果上傳至 Edge。這個做法可讓您將 Proxy 設定整合至原始碼控管、版本管理和其他共用工作流程中。此外,如要在本機上處理 Proxy 設定,您可以使用自己的 XML 編輯器和驗證工具。

本節說明如何透過 UI 下載現有的 Proxy 設定並加以編輯,然後將其上傳回 Edge 進行部署。另外,您也可以使用 apigeetool 下載及部署新的 Proxy 設定,分別設為使用 fetchproxydeployproxy 指令。

如何使用 UI 在本機編輯 Proxy 設定:

  1. 在 Edge UI 中下載目前的 Proxy 設定。(在 API Proxy 檢視畫面中,請依序選取「Project」>「Download Revision」。)
  2. 在本機電腦上,建立新目錄,並將下載的 ZIP 檔案展開。

    如要展開 ZIP 檔案,您可以使用 unzip 等公用程式,如以下範例所示:

    mkdir myappdir
    unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

    ZIP 檔案展開的內容應與 API Proxy 結構中所述的結構類似。

  3. 視需要編輯來源檔案。如需 Proxy 設定中來源檔案的說明,請參閱 API Proxy 的設定檔和目錄結構

    舉例來說,如要在 API Proxy 中啟用健康狀態監控功能,請編輯 /apiproxy/targets/ 目錄中的 TargetEndpoint 設定檔。這個目錄中的預設檔案為 default.xml,但如果您使用條件式目標,檔案可能會有不同的名稱。

    在這種情況下,如果 TargetEndpoint 設定檔及其目錄不存在,請建立設定檔。

  4. 完成 Proxy 設定檔編輯後,請務必儲存變更。
  5. 切換至您在展開 ZIP 檔案時建立的新目錄 (展開的設定檔根目錄)。

    舉例來說,如果您將檔案展開至 /myappdir 目錄,請變更為該目錄,如以下範例所示:

    cd myappdir

    重新封存 Proxy 設定檔前,請先移至這個目錄,因為您不希望在 ZIP 檔案中納入 /myappdir 目錄。ZIP 檔案中的頂層目錄必須是 /apiproxy

  6. 重新封存 Proxy 設定檔,包括新增或變更過的檔案。您可以使用 zip 等公用程式,如以下範例所示:
    zip my-new-proxy.zip -r .

    ZIP 檔案中的頂層目錄必須是 /apiproxy

    ZIP 檔案名稱沒有特殊規定。例如,您不需要增加修訂版本編號或在檔案名稱中指定日期,但這麼做在偵錯或來源控制時相當實用。

    邊緣會在上傳時,為您增加新的 Proxy 設定修訂版本編號。

  7. 使用 Edge UI 上傳新的 Proxy 設定。(在 API Proxy 檢視畫面中,依序選取「Project」>「Upload a New Revision」)。

    如果發生錯誤 (例如 Bundle is invalid. Empty bundle.),請確認 ZIP 檔案的頂層目錄為 /apiproxy。如果不是,請從展開的目錄,重新封存 Proxy 設定檔。

    上傳新的 Proxy 設定後,Edge 會增加修訂版本編號,並在「修訂版本摘要」檢視畫面中顯示。

    將新的修訂版本透過 UI 上傳後,Edge 不會為您部署新的修訂版本。

  8. 部署新的修訂版本。

詳情請參閱 Apigee 社群中的教學課程:如何使用 UI 與 Management API 下載 Proxy

API Proxy 結構

API Proxy 包含以下設定:

基礎設定 API Proxy 的主要配置設定。請參閱基本設定
Proxy 端點設定 傳入 HTTP 連線 (從要求應用程式到 Apigee Edge)、要求和回應流程,以及政策附件的設定。請參閱「ProxyEndpoint」。
TargetEndpoint 設定 傳出 HTTP 連線 (從 Apigee Edge 傳送至後端服務)、要求和回應流程,以及政策附件的設定。請參閱 TargetEndpoint
流程 可以附加政策的 ProxyEndpoint 和 TargetEndpoint 要求和回應管道。請參閱流程一文。
政策 符合 Apigee Edge 政策結構定義的 XML 格式設定檔。請參閱政策的相關說明。
資源 政策參照的指令碼、JAR 檔案和 XSLT 檔案,用於執行自訂邏輯。請參閱「資源」。

API Proxy 目錄結構和內容

上表中的元件是由下列目錄結構的設定檔所定義:

顯示 apiproxy 為根目錄的目錄結構。緊接在 apiproxy 目錄下,有政策、Proxy、資源和目標目錄,以及 weatherapi.xml 檔案。

API Proxy 的設定檔和目錄結構

本節說明 API Proxy 的設定檔和目錄結構。

基礎設定

/apiproxy/weatherapi.xml

API Proxy 的基礎設定,用於定義 API Proxy 的名稱。機構中的名稱不得重複。

範例設定:

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

基礎設定元素

名稱 說明 預設 必填與否
APIProxy
name API Proxy 的名稱,在機構中不得重複。名稱中只能使用下列字元:A-Za-z0-9_- 不適用
revision API Proxy 設定的修訂版本編號。您不必明確設定修訂版本編號,因為 Apigee Edge 會自動追蹤 API Proxy 目前的修訂版本。 不適用
ConfigurationVersion 這個 API Proxy 符合的 API Proxy 設定結構定義版本。目前唯一支援的值是 mainVersion 4 和 subVersion 0。日後可能會使用這項設定支援 API Proxy 格式。 4.0
Description API Proxy 的文字說明。如有提供說明,說明會顯示在邊緣管理 UI 中。 不適用
DisplayName 易記的名稱可能與 API Proxy 設定的 name 屬性不同。 不適用
Policies 這個 API Proxy /policies 目錄中的政策清單。通常只有在 API Proxy 透過邊緣管理 UI 建立時,您才會看到這個元素。這只是一項「資訊清單」設定,用意是讓您掌握 API Proxy 的內容。 不適用
ProxyEndpoints 這個 API Proxy /proxies 目錄中的 ProxyEndpoint 清單。通常只有在 API Proxy 透過邊緣管理 UI 建立時,您才會看到這個元素。這只是一項「資訊清單」設定,用意是讓您掌握 API Proxy 的內容。 不適用
Resources 這個 API Proxy /resources 目錄中的資源清單 (JavaScript、Python、Java、XSLT)。通常只有在 API Proxy 透過邊緣管理 UI 建立時,您才會看到這個元素。這只是一項「資訊清單」設定,用意是讓您掌握 API Proxy 的內容。 不適用
Spec 識別與 API Proxy 相關聯的 OpenAPI 規格。這個值設為網址或規格儲存庫中的路徑。

注意:規格儲存庫僅適用於 New Edge 服務。如要進一步瞭解規格儲存庫,請參閱管理和共用規格一文。
不適用
TargetServers 這個 API Proxy 任何 TargetEndpoint 中參照的 TargetServer 清單。通常只有在 API Proxy 透過邊緣管理 UI 建立時,您才會看到這個元素。這只是一項「資訊清單」設定,用意是讓您掌握 API Proxy 的內容。 不適用
TargetEndpoints 這個 API Proxy /targets 目錄中的 TargetEndpoint 清單,通常只有在 API Proxy 透過邊緣管理 UI 建立時,您才會看到這個元素。這只是一項「資訊清單」設定,用意是讓您掌握 API Proxy 的內容。 不適用

ProxyEndpoint

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

顯示呼叫 HTTP 服務的用戶端。要求會先經過 Proxy 端點和目標端點,然後才會由 HTTP 服務處理。回應會先通過目標端點,然後依序通過 Proxy 端點,再將回應傳回用戶端。

/apiproxy/proxies/default.xml

ProxyEndpoint 設定會定義 API Proxy 的傳入 (用戶端) 介面。設定 ProxyEndpoint 時,您會設定網路設定,藉此定義用戶端應用程式 (「應用程式」) 叫用 Proxy API 的方式。

下列的 ProxyEndpoint 設定範例會儲存在 /apiproxy/proxies 下:

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

基本 ProxyEndpoint 中的必要設定元素如下:

ProxyEndpoint 設定元素

名稱 說明 預設 必填與否
ProxyEndpoint
name ProxyEndpoint 的名稱。在已定義多個 ProxyEndpoint 的情況下,API Proxy 設定中不得重複。名稱中只能使用下列字元:A-Za-z0-9._\-$ % 不適用
PreFlow 定義要求或回應的 PreFlow 流程中的政策。 不適用
Flows
定義要求或回應的條件式流程中的政策。
不適用
PostFlow
定義要求或回應的 PostFlow 流程中的政策。
不適用
HTTPProxyConnection 定義與 API Proxy 相關聯的網路位址和 URI 路徑
BasePath

這個必要字串可以專門用於識別 Apigee Edge 用來將傳入訊息轉送至適當的 API Proxy 所用的 URI 路徑。

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

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

您可以在 API Proxy 基本路徑中使用一或多個「*」萬用字元。舉例來說,/team/*/members 的基本路徑可讓用戶端呼叫 https://[host]/team/blue/membershttps://[host]/team/green/members,而且無須建立新的 API Proxy 來支援新團隊。請注意,系統不支援 /**/。

重要事項:Apigee 不支援使用萬用字元「*」做為基本路徑的第一個元素。舉例來說,系統「不」支援 /*/search 這類欄位。如果使用「*」啟動基本路徑,可能會因為 Edge 識別有效路徑的方式而發生非預期的錯誤。

/
VirtualHost

將 API Proxy 與環境的特定基本網址建立關聯。VirtualHost 是一種具名的設定,可為環境定義一或多個網址。

針對 ProxyEndpoint 定義的已命名 VirtualHosts 會決定公開 API Proxy 的網域和通訊埠,以及應用程式用來叫用 API Proxy 的網址。

根據預設,系統會為環境定義兩個已命名的 VirtualHosts:defaultsecure。機構也可以定義自訂網域。為確保 API Proxy 只能透過 HTTPS 使用,例如將 HTTPProxyConnection 中的 VirtualHost 設為 secure

預設
Properties 一組選用的 HTTP 配置設定可以定義為 <ProxyEndpoint> 的屬性。 不適用
FaultRules
定義 ProxyEndpoint 如何回應錯誤。錯誤規則指定兩個項目:
  • 一種條件,用於根據預先定義的類別、子類別或錯誤名稱指定需要處理的錯誤
  • 針對相應條件定義錯誤規則行為的一或多項政策

請參閱「處理錯誤」。

不適用
DefaultFaultRule

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

請參閱「處理錯誤」。

不適用
RouteRule 定義 ProxyEndpoint 要求管道處理後傳入要求訊息的目的地。RouteRule 通常會指向已命名的 TargetEndpoint 設定,但也可以直接指向網址。
Name 必要屬性,可提供 RouteRule 的名稱。名稱中只能使用下列字元:A-Za-z0-9._\-$ %。例如 Cat2 %_ 是法定名稱, 不適用
Condition 選用的條件陳述式。這個陳述式適用於執行階段的動態轉送。條件式 RouteRules 相當實用,例如可用於啟用內容式轉送功能來支援後端版本管理。 不適用
TargetEndpoint

選用字串,用於識別已命名的 TargetEndpoint 設定。已命名的 TargetEndpoint 是 /targets 目錄下,於相同 API Proxy 中定義的任何 TargetEndpoint。

您可以為 TargetEndpoint 命名,藉此指定 ProxyEndpoint 要求管道處理完畢後,應轉送要求訊息的位置。請注意,此為選用設定。

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

不適用
網址 選用字串,用於定義 ProxyEndpoint 呼叫的傳出網路位址,略過可能儲存在 /targets 中的任何 TargetEndpoint 設定。 不適用

如何設定 RouteRules

已命名的 TargetEndpoint 是指 /apiproxy/targets 下的設定檔,在 ProxyEndpoint 處理後,RouteRule 會轉送要求。

舉例來說,以下 RouteRule 是指 /apiproxy/targets/myTarget.xml 設定:

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

直接網址叫用

ProxyEndpoint 也可以直接叫用後端服務。直接網址叫用會略過 /apiproxy/targets 下任何已命名的 TargetEndpoint 設定。因此,TargetEndpoint 為選擇性的 API Proxy 設定,但並不建議透過 ProxyEndpoint 直接叫用。

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

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

條件式路徑

RouteRules 可以鏈結以支援執行階段的動態轉送。傳入要求可根據 HTTP 標頭、訊息內容、查詢參數,或是時段、語言代碼等情境資訊,轉送至指定的 TargetEndpoint 設定,或直接轉送至網址。

條件式轉送規則的運作方式與 Apigee Edge 中的其他條件陳述式類似。請參閱條件參考資料變數參考資料

舉例來說,下列 RouteRule 組合會先評估傳入要求,藉此驗證 HTTP 標頭的值。如果 HTTP 標頭 routeTo 的值為 TargetEndpoint1,系統就會將要求轉送至名為 TargetEndpoint1 的 TargetEndpoint。如果沒有,系統會將傳入要求轉送至 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 定義為支援不需要將要求訊息轉送至 TargetEndpoint 的情況。當 ProxyEndpoint 執行所有必要的處理作業時,例如使用 JavaScript 呼叫外部服務,或從對 API 服務的鍵/值儲存庫中擷取資料,這種做法非常實用。

例如,以下範例定義空值路徑:

<RouteRule name="GoNowhere"/>

條件式空值路徑相當實用。在以下範例中,如果 HTTP 標頭 request.header.X-DoNothing 的值不是 null,則系統將執行空值路徑。

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

請注意,RouteRules 可以鏈結,因此條件式空值路徑通常是一組用於支援條件轉送的 RouteRules 中的一個元件。

條件式空值路徑的實際用途將有助於快取。您可以使用快取政策設定的變數值,設定 API Proxy 在從快取提供項目時執行空值路徑。

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

TargetEndpoint

顯示呼叫 HTTP 服務的用戶端。要求會先經過 Proxy 端點和目標端點,然後才會由 HTTP 服務處理。回應會先通過目標端點,然後依序通過 Proxy 端點,再將回應傳回用戶端。

TargetEndpoint 是對應於 ProxyEndpoint 的傳出。TargetEndpoint 函式會做為用戶端,傳送至後端服務或 API,可用來傳送要求及接收回應。

API Proxy 不需要任何 TargetEndpoint。您可以將 ProxyEndpoint 設為直接呼叫網址。沒有 TargetEndpoint 的 API Proxy 通常包含直接呼叫後端服務的 ProxyEndpoint,或是設為使用 Java 或 JavaScript 呼叫服務。

TargetEndpoint 設定

/targets/default.xml

TargetEndpoint 會定義從 Apigee Edge 傳送至其他服務或資源的傳出連線。

以下是 TargetEndpoint 設定範例:

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

TargetEndpoint Configuration 元素

TargetEndpoint 可以透過下列其中一種方式呼叫目標:

  • HTTP(S) 呼叫的 HTTPTargetConnection
  • 用於本機 Proxy 對 Proxy 鏈結的 LocalTargetConnection
  • 用於呼叫 Edge 託管 Node.js 指令碼的 ScriptTarget

在 TargetEndpoint 中僅設定其中一項。

名稱 說明 預設 必填與否
TargetEndpoint
name TargetEndpoint 的名稱,在 API Proxy 設定中不得重複。在 ProxyEndpoint RouteRule 中會使用 TargetEndPoint 的名稱來直接要求傳出處理。名稱中只能使用下列字元:A-Za-z0-9._\-$ % 不適用
PreFlow 定義要求或回應的 PreFlow 流程中的政策。 不適用
Flows
定義要求或回應的條件式流程中的政策。
不適用
PostFlow
定義要求或回應的 PostFlow 流程中的政策。
不適用
HTTPTargetConnection

使用其子元素來指定透過 HTTP 存取的後端資源。

如果使用 HTTPTargetConnection,請勿設定其他類型的目標連線 (ScriptTarget 或 LocalTargetConnection)。

URL 定義 TargetEndpoint 將要求訊息轉送至哪個後端服務的網路位址。 不適用
LoadBalancer

定義一或多個已命名的 TargetServer 設定。已命名的 TargetServer 設定可用於定義 2 個以上的端點設定連線的負載平衡。

您也可以使用 TargetServers 將 API Proxy 設定與具體的後端服務端點網址分離。

請參閱「跨後端伺服器負載平衡」。

不適用
Properties 一組選用的 HTTP 配置設定可以定義為 <TargetEndpoint> 的屬性。 不適用
SSLInfo 您可以選擇在 TargetEndpoint 上定義 TLS/SSL 設定,藉此控管 API Proxy 和目標服務之間的 TLS/SSL 連線。請參閱「TLS/SSL 目標端點設定」。 不適用
LocalTargetConnection 透過其子元素,指定要在本機連接的資源,略過負載平衡和訊息處理工具等網路特性。

如要指定目標資源,請加入 APIProxy 子元素 (含有 ProxyEndpoint 元素) 或路徑子項元素。

詳情請參閱將 API Proxy 鏈結在一起

如果使用 LocalTargetConnection,請勿設定其他類型的目標連線 (HTTPTargetConnection 或 ScriptTarget)。

APIProxy 指定要做為要求目標的 API Proxy 名稱。目標 Proxy 所在的機構與環境必須與 Proxy 傳送要求相同。此為使用路徑元素的替代做法。 不適用
ProxyEndpoint 與 APIProxy 搭配使用,藉此指定目標 Proxy 的 ProxyEndpoint 名稱。 不適用
Path 指定 API Proxy 的端點路徑,做為要求的目標。目標 Proxy 的機構和環境必須與 Proxy 傳送要求相同的機構和環境。這是使用 APIProxy 的替代方法。 不適用
FaultRules
定義 TargetEndpoint 如何回應錯誤。錯誤規則指定兩個項目:
  • 一種條件,用於根據預先定義的類別、子類別或錯誤名稱指定需要處理的錯誤
  • 針對相應條件定義錯誤規則行為的一或多項政策

請參閱「處理錯誤」。

不適用
DefaultFaultRule

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

請參閱「處理錯誤」。

不適用
ScriptTarget
ResourceURL

定義資源類型 (節點) 和實作 TargetEndpoint 功能的主要 Node.js 指令碼名稱,

<ResourceURL>node://server.js</ResourceURL>

API Proxy 資源檔案必須包含該指令碼。請參閱「將 Node.js 新增至現有的 API Proxy」。

如果使用 ScriptTarget,請勿設定其他類型的目標連線 (HTTPTargetConnection 或 LocalTargetConnection)。

不適用
EnvironmentVariable

視需要將環境變數傳送至主要 Node.js 指令碼。

請參閱「瞭解 Node.js 模組的 Edge 支援」。

不適用
Arguments

視需要將引數傳送至主要 Node.js 指令碼。

請參閱「瞭解 Node.js 模組的 Edge 支援」。

不適用

TLS/SSL 目標端點設定

TargetEndpoint 通常需要透過異質後端基礎架構管理 HTTPS 連線。因此,系統支援一些 TLS/SSL 配置設定。

TLS/SSL 目標端點設定元素

名稱 說明 預設 必填與否
SSLInfo
Enabled 指出端點是否已啟用 TLS/SSL。如果 <URL> 指定 HTTPS 通訊協定,則預設值為 true;如果 <URL> 指定 HTTP,則預設值為 false 如果 <URL> 指定 HTTPS,則為 true
TrustStore 包含受信任伺服器憑證的 KeyStore。 不適用
ClientAuthEnabled 開啟外寄用戶端驗證 (雙向 TLS/SSL) 的設定 false
KeyStore 包含用於傳出用戶端驗證的私密金鑰的 KeyStore 不適用 是 (如果 ClientAuthEnabled 為 true)
KeyAlias 用於外送用戶端驗證的私密金鑰金鑰別名 不適用 是 (如果 ClientAuthEnabled 為 true)
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 的所有通訊協定。

如要限制通訊協定,請新增下列元素,列出支援的通訊協定:

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>
不適用
CommonName

如有指定,系統會驗證目標憑證通用名稱所用的值。 這個值僅適用於 TargetEndpoint 和 TargetServer 設定。但不適用於 VirtualHost 設定。

根據預設,指定的值會與目標憑證的一般名稱「完全」相符。 舉例來說,如果使用 *.myhost.com 做為 <CommonName> 的值,只有在目標憑證已指定與 *.myhost.com 完全相同的值時,才會比對目標主機名稱並進行驗證。

或者,Apigee 也可使用 wildcardMatch 屬性與萬用字元進行比對。

舉例來說,如果指定以下 <CommonName> 元素後,系統會在目標憑證中指定為 abc.myhost.com 的常用名稱相符並通過驗證:

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

不適用

啟用傳出用戶端驗證的 TargetEndpoint 範例

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

如需詳細操作說明,請參閱「設定從 Edge 傳送至後端的 TLS (雲端和私人雲端)」。

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

您也可以動態設定 TLS/SSL 詳細資料,支援彈性的執行階段需求。 舉例來說,如果您的 Proxy 連線至兩個可能不同的目標 (測試目標和實際工作環境目標),您就能讓 API Proxy 透過程式偵測其呼叫的環境,並動態設定對適當 KeyStore 和信任儲存庫的參照。以下 Apigee 社群文章會詳細說明這種情境,並提供可部署的 API Proxy 範例:https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html

以下舉例說明如何在 TargetEndpoint 設定中指定 <SSLInfo> 標記,並在執行階段提供值,例如透過 Java 呼叫、JavaScript 政策或指派訊息政策。使用含有要設定值的訊息變數。

只有下列元素可以使用變數。

<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 的 TargetEndpoint 時,必須考量傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 憑證過期時的情況,或是變更系統設定時,您必須更新憑證。在私有雲的安裝邊緣中,使用靜態值或流程變數來設定 TLS/SSL 時,你可能必須重新啟動訊息處理器。

詳情請參閱「更新 TLS 憑證」。

不過,您可以選擇將 TargetEndpoint 設為使用對 KeyStore 或信任儲存庫的參照。使用參照的好處是,您可以將參照更新為指向其他 KeyStore 或信任儲存庫,以便更新 TLS/SSL 憑證,而不必重新啟動訊息處理者。

例如,下圖是一個使用對 KeyStore 參照的 TargetEndpoint:

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

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

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

參照會指定 KeyStore 的名稱及其類型。

使用下列 GET API 呼叫來查看參考資料:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

如要在之後將參照變更為其他 KeyStore,以確保別名相同的名稱,請使用下列 PUT 呼叫:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

採用目標負載平衡功能的 TargetEndpoint

TargetServer 透過三種負載平衡演算法,為多個已命名的 TargetServer 提供負載平衡功能。

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

政策

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

政策設定元素

名稱 說明 預設 必填與否
Policy
name

政策的內部名稱。名稱中只能使用 A-Za-z0-9._\-$ % 個字元。不過,Edge 管理 UI 會強制執行其他限制,例如自動移除非英數字元的字元。

您可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中,以不同的自然語言名稱為政策加上標籤。

不適用
enabled

設為 true 可強制執行政策。

設為 false 即可「關閉」這項政策。即使這項政策仍與流程相關聯,也不會強制執行。

true
continueOnError

設為 false 即可在政策失敗時傳回錯誤。這是大部分政策的預期行為。

設為 true 即可讓資料流執行程序,即使政策失敗也不受影響。

false
async

注意:這項屬性不會讓政策以非同步方式執行。 在大多數情況下,請保留預設值 false

設為 true 時,政策執行作業會卸載至其他執行緒,讓主執行緒釋出空間來處理其他要求。離線處理完成後,主要執行緒會返回並完成訊息流程處理作業。在某些情況下,將非同步設定為 true 可以提升 API Proxy 效能。不過,過度同步處理執行緒作業的執行緒數量過多,都有可能會對效能造成負面影響。

如要在 API Proxy 中使用非同步行為,請參閱「JavaScript 物件模型」。

false

政策附件

下圖顯示 API Proxy 流程執行序列:

會顯示呼叫 HTTP 服務的用戶端。要求會遇到 ProxyEndpoint 和 TargetEndpoint,前者包含觸發政策的步驟。HTTP 服務傳回回應後,TargetEndpoint 會先處理回應,然後才透過 ProxyEndpoing 處理回應,再將回應傳回用戶端。與要求一樣,回應會依政策逐步處理。

如上所示:

政策會以處理步驟附加至流程。這項政策的名稱會用來參照要強制執行為處理步驟的政策。政策附件的格式如下:

<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:一律執行。在任何條件式流程後執行。

另外,您也可以將 PostClientFlow 新增至 ProxyEndpoint,這項作業會在回應傳回要求的用戶端應用程式後執行。只有 MessageLogging 政策Google Stackdriver Logging 擴充功能可附加至此流程。PostClientFlow 可縮短 API Proxy 延遲時間,提供在傳回回應至用戶端之後才會計算的記錄資訊,例如 client.sent.start.timestampclient.sent.end.timestamp。這個流程主要用於測量回應訊息開始與結束時間戳記之間的時間間隔。

觀看步驟簡介影片

影片:觀看這部短片,瞭解如何使用 PostClientFlow 中的訊息記錄功能。

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

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

API Proxy 處理管道會以下列順序執行 Flow:

要求管道:

  1. Proxy 要求預處理
  2. Proxy 要求條件式流程 (選用)
  3. Proxy 要求 PostFlow
  4. 目標要求預先處理
  5. 目標要求條件式流程 (選用)
  6. 目標要求 PostFlow

回應管道:

  1. 目標回應預測
  2. 目標回應條件式流程 (選用)
  3. 目標回應 PostFlow
  4. Proxy 回應預測
  5. Proxy 回應條件式流程 (選用)
  6. Proxy 回應 PostFlow
  7. PostClientFlow 回應 (選填)

您只需在 ProxyEndpoint 或 TargetEndpoint 設定中,設定含有政策附件的流程。只有在需要在預先 Flow 或 PostFlow 處理期間強制執行政策時,才能在 ProxyEndpoint 或 TargetEndpoint 設定中指定 PreFlow 和 PostFlow。

與條件式流程相比,PreFlow 和 PostFlow 元素的排序並不重要,API Proxy 一律會在管道中的適當時間點執行,無論這些元素在端點設定中的顯示位置為何。

條件式流程

ProxyEndpoint 和 TargetEndpoint 支援不限數量的條件式流程 (也稱為「已命名的流程」)。

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 由 ProxyEndpoint 或 TargetEndpoint 定義的要求或回應處理管道
Name Flow 的專屬名稱。 不適用
Condition 條件陳述式,用於評估一或多個變數,以便評估為 True 或 False。除了預先定義的 PreFlow 和 PostFlow 類型之外,所有的 Flow 都必須定義其執行條件。 不適用
Request 與要求訊息處理相關聯的管道 不適用
Response 與回應訊息處理相關聯的管道 不適用

步驟處理

Apigee Edge 會強制執行條件式流程的依序排列。條件式流程會從上到下執行。系統會執行第一個條件為 true 的條件式流程,且只會執行一個條件流程。

舉例來說,在下列流程設定中,任何不含路徑後置字串 /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 轉換,可以使用政策附加至 Flows。這些指令碼會顯示在管理 UI 中 API Proxy 編輯器的「指令碼」部分。

如要瞭解支援的資源類型,請參閱「資源檔案」一節。

資源可儲存在 API Proxy、環境或機構中。在每個案例中,資源都會由政策中的名稱參照。API 服務會將名稱從 API Proxy 遷移至環境,並遷移至機構層級,藉此解析名稱。

在任何環境中,政策都能參照儲存在機構層級的資源。 該環境中的政策可以參照儲存在環境層級的資源。只有位於 API Proxy 層級的資源,才能由該 API Proxy 中的政策參照。