API Proxy 設定參考資料

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件

使用 Apigee Edge 的開發人員必須設定 API Proxy,做為 API 或後端服務的 Proxy。本文件提供建構 API Proxy 時可用的所有設定元素。

如要瞭解如何建構 API Proxy,建議您先參閱「建構簡單的 API Proxy」主題。

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

本機 Proxy 設定開發

您可以下載 Proxy 設定,在本機上編輯。完成後,請將結果上傳至邊緣。這個方法可讓您將 Proxy 設定整合至來源控制、版本管理和其他共用工作流程。此外,在本機執行 Proxy 設定時,您可以使用自己的 XML 編輯器和驗證工具。

本節說明如何使用 UI 下載現有的 Proxy 設定並進行編輯,然後將檔案重新上傳至 Edge 進行部署。您也可以使用 apigeetool 下載及部署新的 Proxy 設定 (分別使用 fetchproxydeployproxy 指令)。

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

  1. 在 Edge UI 中下載目前的 Proxy 設定。(在「API Proxy」檢視畫面中,依序選取「專案」>「下載修訂版本」)。
  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

    您不想將 /myappdir 目錄加入 ZIP 檔案,請在重新封存 Proxy 設定檔之前變更這個目錄。ZIP 檔案中的頂層目錄必須是 /apiproxy

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

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

    ZIP 檔案名稱沒有任何特殊規定。例如,您不需要遞增修訂版本名稱或指定檔案名稱的日期,但很適合用於偵錯或來源控制。

    Edge 上傳時,會為您增加新 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. 部署新的修訂版本。

詳情請參閱「教學課程:如何透過 UI 下載管理 API」,以及 Apigee 社群中的 Management API。

API Proxy 結構

API Proxy 包含下列設定:

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

API Proxy 目錄結構與內容

上表中的元件是透過以下目錄結構中的設定檔定義:

顯示 apiProxy 的根目錄。api API 目錄之下會直接列出政策、Proxy、資源和目標目錄,以及天氣 API.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 設定結構定義版本。目前唯一支援的值是 majorVersion 4 和 smallVersion 0。日後推出的設定可能會用來啟用 API Proxy 格式。 4.0
Description API Proxy 的文字說明。如有提供說明,就會顯示在邊緣管理 UI 中。
DisplayName 容易使用的名稱,可能會與 API Proxy 設定的 name 屬性不同。
Policies 這個 API Proxy 的 /policies 目錄中的政策清單。通常只有在透過邊緣管理 UI 建立 API Proxy 時,才會看到這個元素。這只是「資訊清單」設定,旨在讓使用者直接瞭解 API Proxy 的內容。
ProxyEndpoints 這個 API Proxy 的 /proxies 目錄中的 ProxyEndpoint 清單。通常只有在透過邊緣管理 UI 建立 API Proxy 時,才會看到這個元素。這只是「資訊清單」設定,旨在讓使用者直接瞭解 API Proxy 的內容。
Resources 這個 API Proxy 的 /resources 目錄中的資源清單 (JavaScript、Python、Java、XSLT)。通常只有在透過邊緣管理 UI 建立 API Proxy 時,才會看到這個元素。這只是「資訊清單」設定,旨在讓使用者瞭解 API Proxy 的內容。
Spec 識別與 API Proxy 相關聯的 OpenAPI 規格。這個值會是網址或是規格儲存庫中的路徑。

注意:規格儲存庫僅適用於新版 Edge 服務。如要進一步瞭解規格儲存庫,請參閱「管理和共用規格」。
TargetServers 這個 API Proxy 的任何目標端點中參照的目標 Server 清單。通常只有在透過邊緣管理 UI 建立 API Proxy 時,才會看到這個元素。這只是「資訊清單」設定,旨在讓使用者直接瞭解 API Proxy 的內容。
TargetEndpoints 這個 API Proxy 的 /targets 目錄中的目標 Endpoints 清單。通常只有在透過邊緣管理 UI 建立 API Proxy 時,才會看到這個元素。這只是「資訊清單」設定,旨在讓使用者直接瞭解 API Proxy 的內容。

Proxy 端點

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

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

/apiproxy/proxies/default.xml

ProxyEndpoint 設定定義了 API Proxy 的傳入 (用戶端) 介面。設定 ProxyEndpoint 時,您將進行網路設定,定義用戶端應用程式 (「應用程式」) 應如何叫用 Proxy。

下列 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 的名稱。API API 設定中不得重複,但在少數情況下,必須定義多個 ProxyEndpoint。名稱中允許的字元僅限下列字元:A-Za-z0-9._\-$ %
PreFlow 在要求或回應的 PreFlow 流程中定義政策。
Flows
在要求或回應的條件流程中定義政策。
PostFlow
在要求或回應的 PostFlow 流程中定義政策。
HTTPProxyConnection 定義與 API Proxy 相關聯的網路位址和 URI 路徑
BasePath

唯一識別 Apigee Edge 使用的 URI 路徑的必要字串,用於將傳入訊息轉送至適當的 API Proxy。

BasePath 是附加至 API Proxy 基本網址 (例如 http://apifactory-test.apigee.net) 的 URI 片段 (例如 /weather)。基本路徑在環境中不得重複。系統會在產生或匯入 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。機構也可以定義自訂網域。如要確保只透過 HTTPS 取得 API Proxy,請將 HTTPProxyConnection 中的 VirtualHost 設為 secure

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

請參閱處理錯誤

DefaultFaultRule

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

請參閱處理錯誤

RouteRule 定義在 ProxyEndpoint 要求管道處理完成後的傳入要求訊息目的地。通常,RouteRule 會指向已命名的 TargetEndpoint 設定,但也可以直接指向網址。
Name 必要屬性,提供 RouteRule 的名稱。名稱中允許的字元僅限下列字元:A-Za-z0-9._\-$ %。舉例來說,Cat2 %_ 是法定名稱。
Condition 選用條件陳述式,用於在執行階段進行動態轉送。舉例來說,條件式 RouteRules 可用於支援以內容為基礎的轉送來支援後端版本管理。
TargetEndpoint

可識別已命名目標端點設定的選用字串。目標目標端點是 /targets 目錄下同一個 API Proxy 中定義的任何目標端點。

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

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

網址 選用字串,用於定義 ProxyEndpoint 所呼叫的傳出網路位址,並略過可能儲存在 /targets 下的 TargetEndpoint 設定

如何設定 RouteRules

目標 TargetEndpoint 參照 /apiproxy/targets 中的設定檔,在 ProxyRuleProxy 處理完要求後,Route Rules 會將要求轉送至該設定檔。

舉例來說,下列 RouteRule 參照 /apiproxy/targets/myTarget.xml 設定:

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

直接叫用網址

ProxyEndpoint 也可以直接叫用後端服務。直接網址叫用會略過任何在 /apiproxy/targets 下指定的目標端點設定。因此,TargetEndpoint 是選用的 API Proxy 設定,但在實際運作時,我們不建議直接叫用 ProxyEndpoint。

舉例來說,下列 RouteRule 會呼叫 http://api.mycompany.com/v2

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

條件路徑

您可以將 RouteRules 鏈結起來,以便在執行階段支援動態轉送。系統會根據 HTTP 標頭、訊息內容、查詢參數或時段、語言代碼等背景資訊,將傳入要求轉送至已命名的 Target 設定,或同時採用這兩者的組合。

條件式 RouteRules 的運作方式與 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 定義為支援情境訊息,這樣就不需要將要求訊息轉送至目標端點。如果 Proxy Endpoints 執行所有必要的處理程序,例如使用 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>

目標端點

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

TargetEndpoint 相當於 Proxy 端點。TargetEndpoint 函式可做為後端服務或 API 的用戶端:用戶端會傳送要求並接收回應。

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

目標端點設定

/targets/default.xml

TargetEndpoint 會定義從 Apigee Edge 到其他服務或資源之間的輸出連線。

以下是目標端點設定範例:

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

TargetEndpoint 設定元素

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

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

請在 TargetEndpoint 中設定其中一項。

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

其子項元素透過 HTTP 指定後端資源觸及率。

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

URL 定義目標端點將要求訊息轉送的後端服務網路位址。
LoadBalancer

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

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

請參閱在後端伺服器之間進行負載平衡一文。

Properties 一組選擇性 HTTP 配置設定可以定義為 <TargetEndpoint> 的屬性。
SSLInfo 在目標端點上定義 TLS/SSL 設定,以控管 API Proxy 與目標服務之間的傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 連線。請參閱「傳輸層安全標準 (TLS)/SSL TargetEndpoint 設定」一文。
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 設定

TargetEndpoint 通常需要透過異質的後端基礎架構管理 HTTPS 連線。因此可支援多種傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 配置設定。

TLS/SSL TargetEndpoint 設定元素

名稱 說明 預設 必填與否
SSLInfo
Enabled 指出端點是否已啟用傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL)。如果 <URL> 指定 HTTPS 通訊協定,則預設值為 true;如果 <URL> 指定 HTTP,則預設值為 false 如果 <URL> 指定 HTTPS,則為 true
TrustStore 含有受信任伺服器憑證的 KeyStore。
ClientAuthEnabled 啟用外寄用戶端驗證 (雙通道傳輸層安全標準 (TLS)/SSL) 的設定 false
KeyStore 含有用於傳出用戶端驗證的私密金鑰庫 是 (如果 ClientAuthEnabled 為 true)
KeyAlias 用於傳出用戶端驗證的私密金鑰金鑰別名 是 (如果 ClientAuthEnabled 為 true)
Ciphers

支援的傳輸層安全標準 (TLS)/傳輸層安全標準 (TLS)/加密方式。如果未指定加密,系統允許使用 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>

啟用輸出用戶端驗證的 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 的後端至後端 (Cloud 和私有雲)

使用流程變數動態設定傳輸層安全標準 (TLS)/SSL 值

您也可以動態設定傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 詳細資料,以支援彈性的執行階段需求。 舉例來說,如果您的 Proxy 連結到兩個可能不同的目標 (測試目標和實際工作環境目標),您就能透過 API Proxy 用程式輔助的方式偵測呼叫的環境,並動態設定適當的 KeyStore 和 Truststore 來源。以下 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 或 Truststore 的「參照」。使用參照的優點在於,您可以更新參照,指向其他 KeyStore 或 Truststore 來更新 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

TargetEndpoint 使用三個負載平衡演算法,以多個多個目標伺服器的方式支援負載平衡。

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

政策

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

政策設定元素

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

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

或者,您也可以使用 <DisplayName> 元素,在管理使用者介面 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、一或多個「conditional」或「named」流程,以及 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 處理管道會按照下列順序執行流程:

要求管道:

  1. Proxy 要求 PreFlow
  2. Proxy 要求條件式流程 (選用)
  3. ProxyF 要求 PostFlow
  4. 目標要求前置字串
  5. 目標要求條件流程 (選用)
  6. 要求後 PostFlow

回應管道:

  1. 目標回覆優先順序
  2. 目標回應條件流程 (選用)
  3. 目標回應 PostFlow
  4. Proxy 回應 PreFlow
  5. Proxy 回應條件流程 (選用)
  6. ProxyF 回應 PostFlow
  7. PostClientFlow 回應 (選填)

只有使用政策附件的流程必須在 ProxyEndpoint 或 TargetEndpoint 設定中進行設定。只有在 PreFlow 或 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 AProxyEndpoint 或 TargetEndpoint 定義的要求或回應處理管道
Name 資料流的專屬名稱。
Condition 評估一或多個變數的條件評估結果為 True 或 False 的情況。除了預先定義的 PreFlow 和 PostFlow 類型之外,所有資料流都必須定義執行作業的條件。
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 的資源檔案) 是可透過政策附加至 Flow 的指令碼、程式碼和 XSL 轉換。這些項目會顯示在管理使用者介面中 API Proxy 編輯器的「指令碼」部分。

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

資源可儲存在 API Proxy、環境或機構中。每種情況下,在政策中都會以名稱參照資源。API 服務從 API Proxy 移至環境層級後,即可解析名稱。

機構層級儲存的資源可套用至任何環境中的政策。儲存在該環境中的資源可由該環境中的政策參照。只有這個 API Proxy 中的政策可以參照儲存在 API Proxy 層級的資源。