API Proxy 設定參考資料

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

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

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

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

• 在 Edge UI 中使用 XML 編輯器
• 下載設定並在本機編輯，如 Proxy 設定的本機開發所述。

本機 Proxy 設定開發

您可以下載 Proxy 設定，在本機上編輯。完成後，請將結果上傳至邊緣。這個方法可讓您將 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/ 目錄中編輯 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 目錄結構與內容

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

API Proxy 的設定檔和目錄結構

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

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

基本設定

/apiproxy/weatherapi.xml

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

範例設定：

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

基礎設定元素

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

如何設定 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>

目標端點

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 中設定其中一項。

TLS/SSL TargetEndpoint 設定

TargetEndpoint 通常需要透過異質的後端基礎架構管理 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>

啟用輸出用戶端驗證的 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 流程的所有政策。

政策設定元素

政策附件

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

如上所示：

政策會做為「流程」的處理步驟附加，政策名稱用於參照即將在處理步驟中執行的政策。政策附件的格式如下：

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

政策會按照政策附加至「流程」的順序執行。例如：

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

政策附件設定元素

流程

ProxyEndpoint 和 TargetEndpoint 會定義用於要求及回應訊息的管道。處理管道包含要求流程和回應流程。每個要求流程和回應流程都會細分為 PreFlow、一或多個「conditional」或「named」流程，以及 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. 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>   

流程設定元素

步驟處理

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 層級的資源。