API Proxy 設定參考資料

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

如果您是使用 Apigee Edge 的開發人員，主要開發活動包括設定 API Proxy，做為 API 或後端服務的 Proxy。本文是建構 API Proxy 時可用的所有設定元素參考資料。

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

編輯 Proxy 設定最常見的方法如下：

• 使用 Edge UI 中的 XML 編輯器
• 按照「本機開發 Proxy 設定」一文所述，下載設定並在本機編輯。

在本機開發 Proxy 設定

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

本節說明如何使用 UI 下載現有的 Proxy 設定、編輯設定，然後上傳回 Edge 進行部署。您也可以使用 apigeetool 下載及部署新的 Proxy 設定 (分別使用 fetchproxy 和 deployproxy 指令)。

如要透過 UI 在本機編輯 Proxy 設定，請按照下列步驟操作：

1. 在 Edge 使用者介面中下載目前的 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 設定檔前，您應先切換至這個目錄，因為您不希望 /myappdir 目錄包含在 ZIP 檔案中。ZIP 檔案中的頂層目錄必須是 /apiproxy。

6. 重新封存 Proxy 設定檔，包括新檔案或變更的檔案。您可以使用 zip 等公用程式，如下列範例所示：

   zip my-new-proxy.zip -r .

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

   ZIP 檔案名稱沒有特殊規定，舉例來說，您不需要遞增修訂版本號碼或在檔案名稱中指定日期，但這麼做有助於偵錯或來源控制。

   上傳新的 Proxy 設定時，Edge 會自動遞增修訂版本號碼。

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 目錄結構和內容

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

API Proxy 的設定檔和目錄結構

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

• 基本設定
• ProxyEndpoint
• TargetEndpoint
  • TLS/SSL TargetEndpoint 設定
• 政策
• 流程
• 資源

基礎設定

/apiproxy/weatherapi.xml

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

設定範例：

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

基礎設定元素

ProxyEndpoint

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

/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 設定 元素

如何設定 RouteRules

具名 TargetEndpoint 是指 /apiproxy/targets 下的設定檔，RouteRule 會在 ProxyEndpoint 處理要求後，將要求轉送至該設定檔。

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

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

直接叫用網址

ProxyEndpoint 也可以直接叫用後端服務。直接叫用網址會略過 /apiproxy/targets 下的任何具名 TargetEndpoints 設定。因此，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 設定，或兩者兼具。

條件式 RouteRule 的運作方式與 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>

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

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

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

TargetEndpoint

TargetEndpoint 相當於 ProxyEndpoint 的輸出端。TargetEndpoint 的功能類似後端服務或 API 的用戶端，會傳送要求並接收回應。

API Proxy 不一定要有 TargetEndpoint。ProxyEndpoints 可設定為直接呼叫網址。沒有 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 設定 元素

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

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

請在 TargetEndpoint 中只設定其中一個。

TLS/SSL TargetEndpoint 設定

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

傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) TargetEndpoint 設定元素

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>

<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 (Cloud 和 Private Cloud)」。

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

您也可以動態設定 TLS/SSL 詳細資料，以支援彈性的執行階段需求。 舉例來說，如果您的 Proxy 連線至兩個可能不同的目標 (測試目標和正式目標)，您可以讓 API Proxy 以程式輔助方式偵測呼叫的環境，並動態設定適當的金鑰儲存區和信任儲存區參照。如要進一步瞭解這個情境，請參閱 Apigee 社群文章「Dynamic SSLInfo for TargetEndpoint using variable reference」，當中也提供可部署的 API Proxy 範例。

在下列範例中，說明如何在 TargetEndpoint 設定中設定 <SSLInfo> 標記，值可在執行階段提供，例如透過 Java Callout、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 憑證過期，或系統設定變更而需要更新憑證的情況。在 Edge for Private Cloud 安裝中，使用靜態值或流程變數設定 TLS/SSL 時，您可能需要重新啟動 Message Processor。

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

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

舉例來說，下方顯示的 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

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

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

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

如要稍後變更參照，指向其他金鑰儲存區，請使用下列 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 搭配目標負載平衡

TargetEndpoints 支援使用三種負載平衡演算法，在多個具名 TargetServer 之間進行負載平衡。

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

政策

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

政策設定元素

政策附件

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

如上所示：

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

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

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

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

政策附加設定 元素

流程

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

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

此外，您可以在 ProxyEndpoint 中新增 PostClientFlow，在回應傳回給要求用戶端應用程式後執行。只有 MessageLogging 政策和 Google Stackdriver Logging 擴充功能可以附加至這個流程。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：

要求管道：

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

回覆管道：

1. 目標回應前置流程
2. 目標回應條件流程 (選用)
3. Target Response PostFlow
4. Proxy Response PreFlow
5. Proxy 回應條件流程 (選用)
6. Proxy Response 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>

流程設定元素

步驟處理

Apigee Edge 會強制執行條件式 Flow 的循序排序。條件流程會由上而下執行。系統會執行條件評估結果為 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 轉換。這些指令碼會顯示在管理 UI 中 API 代理編輯器的「Scripts」部分。

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

資源可以儲存在 API Proxy、環境或機構中。在上述兩種情況中，資源都會在政策中依名稱參照。API 服務會依序從 API Proxy、環境和機構層級解析名稱。

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