API Proxy 設定參考資料

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

身為使用 Apigee Edge 的開發人員，您的主要開發活動涉及 為 API 或後端服務設定 API Proxy 並設為 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 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/ 目錄內。這個目錄中的預設檔案是 default.xml，不過如果您要使用 條件式目標。

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

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 中 檢視，選取 專案 >上傳新修訂版本)。

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

   上傳新的 Proxy 設定後，Edge 會遞增修訂版本編號 並在「修訂版本摘要」檢視畫面中顯示相關資訊。

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

8. 部署新的修訂版本。

若需更多資訊，請參閱： 教學課程：如何透過 UI 和 Management API 下載 Proxy Apigee 社群。

API Proxy 結構

API Proxy 包含下列設定：

API Proxy 目錄結構 和內容

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

設定檔和目錄 API Proxy 的結構

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

• 基礎設定
• ProxyEndpoint
• TargetEndpoint
  • TLS/SSL 目標端點設定
• 政策
• 流程
• 資源

基礎設定

/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 設定 Elements

如何設定 RouteRules

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

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

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

直接網址叫用

ProxyEndpoint 也可以直接叫用後端服務。直接網址叫用會略過任何 名為 Target Endpoints 設定，位於 /apiproxy/targets 下方因此 TargetEndpoint 是選用的 API Proxy 設定，但在實務上卻是直接叫用 也不建議使用 ProxyEndpoint 傳送。

舉例來說，下列 RouteRule 會將 HTTP 呼叫傳送至 http://api.mycompany.com/v2。

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

條件式路徑

可鏈結 RouteRules，在執行階段支援動態轉送。傳入要求可設為 會轉送至已命名的 TargetEndpoint 設定、直接傳輸到 URL 或這兩者的組合 偵測次數包括 HTTP 標頭、郵件內容、查詢參數 天、語言代碼等。

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

舉例來說，下列 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 以支援要求訊息沒有的情境。 需要轉送至 TargetEndpoint。當 ProxyEndpoint 執行 必要處理作業，例如使用 JavaScript 呼叫外部服務 從查詢擷取至 API 服務的資料」鍵/值儲存庫。

例如，下列程式碼定義了空值的路徑：

<RouteRule name="GoNowhere"/>

條件式空值路徑相當實用。在以下範例中，將空 Route 設定為 當 HTTP 標頭 request.header.X-DoNothing 的值不是 null。

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

請記住，RouteRules 可以鏈結，因此條件式 null Route 通常會是 元件。

使用條件式空值路徑以實際支援快取。使用 而您可以設定 API Proxy 以執行 從快取提供項目時，空值路徑。

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

TargetEndpoint

TargetEndpoint 相當於 ProxyEndpoint 的傳出。TargetEndpoint 的作用 將要求和回應傳送至後端服務或 API

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

目標端點設定

/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>

目標端點設定 Elements

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

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

在 TargetEndpoint 中僅設定其中一個項目。

TLS/SSL 目標端點設定

Target Endpoints 通常需要使用異質後端管理 HTTPS 連線 基礎架構因此，系統支援多種 TLS/SSL 配置設定。

TLS/SSL 目標端點設定元素

<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>

如需詳細的操作說明，請參閱設定 TLS 從邊緣到後端 (Cloud 與私有雲)

使用 流程變數，以動態方式設定 TLS/SSL 值

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

如下列範例所示，<SSLInfo> 標記在 TargetEndpoint 設定，值可在執行階段提供，例如，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 與目標負載平衡

Target Endpoints 利用三個負載，支援多個已命名 TargetServer 之間的負載平衡 平衡演算法

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

政策

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

政策設定元素

政策附件

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

如上所示：

政策會以處理步驟附加至流程。政策名稱會用於 參考要在處理步驟時強制執行的政策。政策附件的格式： 包括：

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

政策會按照連結至 Flow 的順序執行。例如：

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

政策附件設定 Elements

流程

ProxyEndpoint 和 TargetEndpoint 會定義要求和回應訊息的管道 和資料處理之間處理管道包含要求流程和回應流程。每項要求 流程和回應流程可細分為 PreFlow，一或多個選用的「條件式」或 「已命名」資料流以及 PostFlow 程序

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

此外，您可以將 PostClientFlow 新增至 ProxyEndpoint，後者會在 系統會將回應傳回給提出要求的用戶端應用程式。只有 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 處理管道會按照下列順序執行流程：

要求管道：

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

回應管道：

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

只有含政策連結的流程必須在 ProxyEndpoint 或 Proxy 端點中設定 TargetEndpoint 設定。PreFlow 和 PostFlow 僅可在 ProxyEndpoint 或 Proxy 端點或 必須在 PreFlow 或 PostFlow 期間強制執行政策時的目標端點設定 和資料處理之間

與條件式流程相比，PreFlow 和 PostFlow 元素的排序與 API Proxy 一律會在管道中的適當時機執行每個 Proxy， 不論端點出現在端點設定中的哪個位置。

條件式流程

ProxyEndpoint 和 Target Endpoints 支援無限數量的條件流程 (還有 稱為「已命名的流程」

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 會強制執行條件式流程的順序。條件式流程 則是由上至下執行第一個條件式資料流，其條件評估為 系統會執行 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 轉換 可以使用政策附加至流程這些程式碼會出現在「指令碼」中API 的區段 新的 Proxy 編輯器

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

資源可儲存在 API Proxy、環境或機構中。無論是哪種情況 系統已依政策名稱參照資源。API 服務會透過移動 API 來解析名稱 從 Proxy、環境到機構層級

任何環境中的政策均可參照在機構層級儲存的資源。 儲存於環境層級的資源可由該環境中的政策參照。A 罩杯 儲存在 API Proxy 層級的資源，只能由該 API Proxy 中的政策參照。