採用 JavaScript 的 Programming API Proxy

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

在本主題中,您將瞭解如何使用 JavaScript 在回應訊息中動態新增 HTTP 標頭,以及如何剖析 JSON 回應並將部分屬性傳回至要求應用程式。

下載並試用程式碼範例

關於這個食譜集範例

本教戰手冊範例說明您在 JavaScript 中實作 API 行為的 API Proxy 模式。JavaScript 範例旨在向您說明如何使用簡單的變數和訊息內容。您可以參考範例,瞭解如何 getset 變數。第二個範例說明如何剖析 JSON 並從結果建構訊息。

以下兩個 JavaScript 範例位於 API Proxy 中:

  • setHeaders.js:這個 JavaScript 會取得在叫用 API Proxy 時設定的幾個變數值。JavaScript 會將這些變數新增至回應訊息,讓您可以查看所發出每個要求的值。
  • minimize.js:這個 JavaScript 示範如何處理訊息內容。這個範例的目的在於,服務傳回的資料通常超過所需量。因此,JavaScript 會剖析回應訊息、擷取幾個有趣的屬性,然後使用這些屬性建構回應訊息的內容。

setHeader.js 的程式碼:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

minimize.js 的程式碼:

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

您可以透過結構定義物件存取 JavaScript 中的流程變數。這個物件是 Edge JavaScript 物件模型的一部分。如要進一步瞭解物件模型,請參閱 JavaScript 物件模型一文。

事前準備

探索這個教戰手冊範例之前,建議您也熟悉下列基本概念:

  • 何謂政策,以及如何將政策附加至 Proxy。如需有關政策的詳盡說明,請參閱「什麼是政策?」一文。
  • Proxy 流程的結構,如設定流程一文所述。流程可讓您指定 API Proxy 執行政策的順序。在這個範例中,系統會建立多項政策並新增至 API Proxy 流程中。
  • API Proxy 專案在檔案系統中的組織方式,請參閱 API Proxy 設定參考資料
  • 具備 XML、JSON 和 JavaScript 的工作知識。在這個範例中,您要使用位於檔案系統的 XML 檔案來建立 API Proxy 及其政策。

如果您已下載程式碼範例,可以在 javascript-cookbook 範例資料夾中找到這個主題討論的所有檔案。下列各節將詳細說明程式碼範例。

瞭解 Proxy 流程

如要讓 JavaScript 在 API Proxy 中執行,您必須使用名為「步驟」的政策連結,將 JavaScript 附加至流程。JavaScript 類型的政策 (注意大小寫) 只會包含 JavaScript 檔案名稱的參照。您可以使用 ResourceURL 元素,將政策指向 JavaScript 檔案。

舉例來說,下列政策會參照名為 setHeader.js 的 JavaScript 檔案。

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

您可以將這項政策附加至 API Proxy 流程,就像附加其他政策類型一樣。將這項政策附加至 API Proxy 流程,就能指定 JavaScript 的執行位置。如此一來,您就可以執行透過 API Proxy 「流動」訊息時,執行與要求訊息或回應訊息互動的 JavaScript。在本例中,由於政策執行了兩項操作,因此這兩個 JavaScript 都會在回應流程中執行:設定回應訊息的 HTTP 標頭,以及將 Apigee Edge 傳回給提出要求應用程式的回應訊息「最小化」。

如果您在管理 UI 中開啟這項流程設定,就會看到下方的流程設定。

在「Navigator 窗格」中,依序選取「Proxy Endpoints」>「default」>「PostFlow」

以下顯示名為「default」的 ProxyEndpoint 對應的 XML 設定。

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

以下是流程元素的摘要。

  • <Request> - <Request> 元素包含數個 <Step> 元素。每個步驟都會呼叫您在本主題中其他部分建立的其中一項政策。這些政策會將 JavaScript 附加至 API Proxy 流程,政策連結的位置會決定 JavaScript 的執行時機。
  • <Response> - <Response> 元素也包含 <Steps>。這些步驟也呼叫了負責處理目標最終回應的政策 (在此範例中為 Apigee 模擬服務目標;請留意 /apiproxy/targets/default.xml 底下的 HTTPTargetConnection 設定)。
  • <HTTPProxyConnection>:指定主機和 URI 路徑,定義應用程式呼叫這個 API 的網路位址。
  • <RouteRule>:這個元素會指定 ProxyEndpoint 叫用的 TargetEndpoint 設定。

將 JavaScript 程式碼新增至 Proxy

JavaScript (例如 Python 指令碼、Java JAR 檔案、XSLT 檔案等) 會以「資源」的形式儲存。當您剛開始使用 JavaScript 時,最簡單的方法是將 JavaScript 檔案儲存在 API Proxy 中。在此之前,您應盡可能開發通用且可重複使用的 JavaScript,然後儲存在「環境」或「機構」層級。這樣您就不必在多個 API Proxy 中儲存相同的 JavaScript 檔案,因為這類 Proxy 可能很快就會變得無法管理。

如要瞭解如何在機構和環境層級儲存資源,請參閱「資源檔案」。

立即體驗

如需部署及呼叫 Proxy 的操作說明,請參閱 JavaScript 教戰手冊 README

匯入及部署 API Proxy

完成變更後,您可以在管理 UI 的 API Proxy 建構工具工具中儲存 API Proxy。

您也可以在 /api-platform-samples/doc-samples/javascript-cookbook 目錄中執行下列指令。

$ sh deploy.sh

測試 JavaScript

/api-platform-samples/doc-samples/javascript-cookbook 目錄中執行下列指令。

$ sh invoke.sh

在殼層指令碼中,curl 旗標 -v 可用來查看 JavaScript 修改回應訊息的 HTTP 標頭。

您可以按照下列步驟直接提出要求:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook 

如果 JavaScript 正確執行,您會看到如下的回應:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

您現在可以修改 JavaScript 來嘗試新內容、重新部署 API Proxy,並提交相同的要求來驗證結果。請務必部署包含 JavaScript 的 API Proxy,您的變更才會生效。

指令碼錯誤

編寫 JavaScript 時,您可能不會看到錯誤。以下是 API Proxy 發出的 JavaScript 錯誤格式。

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

使用 JavaScript 的時機

在 Apigee Edge 中,實作特定功能的方法通常不只一種。請盡可能使用立即可用的政策,並避免以 JavaScript 編寫所有 API Proxy 邏輯。雖然 Apigee Edge 利用經過編譯的 JavaScript 來提升效能,但 JavaScript 的成效不太可能與政策相同。JavaScript 可能較難維護及偵錯。請將 JavaScript 保留下來,以提供符合您需求的功能。

如果對自訂功能的效能有疑慮,請盡可能使用 Java。

摘要

在本教戰手冊主題中,您已瞭解如何在 API Proxy 設定中加入 JavaScript,以便實作自訂行為。範例實作的自訂行為示範如何取得和變數,以及如何剖析 JSON 及建構自訂回應訊息。