JavaScript 政策

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

優勢

這項政策可讓您新增自訂 JavaScript 程式碼，程式碼會在 API Proxy 流程環境內執行。在自訂 JavaScript 程式碼中，您可以使用 Apigee Edge JavaScript 物件模型的物件、方法和屬性。物件模型可讓您取得、設定及移除 Proxy 流程環境中的變數。您也可以使用物件模型隨附的基本加密編譯函式。

About

JavaScript 政策的用途很多，舉例來說，您可以取得並設定流程變數、執行自訂邏輯並執行錯誤處理、從要求或回應擷取資料、動態編輯後端目標網址等。這項政策可讓您實作其他標準 Edge 政策未涵蓋的自訂行為。事實上，您可以使用 JavaScript 政策來實現由其他政策實作的許多相同行為，例如 AssignMessage 和 ExtractVariable。

我們不建議設定 JavaScript 政策的其中一個用途。訊息記錄政策更適合用來記錄至第三方記錄平台 (例如 Splunk、Sumo 和 Loggly)，且您藉由在 PostClientFlow 中執行訊息記錄政策 (系統會在回應傳回用戶端後執行該政策) 改善 API Proxy 效能。

JavaScript 政策可讓你指定要執行的 JavaScript 來源檔案，或是透過 <Source> 元素直接在政策設定中加入 JavaScript 程式碼。 不論是哪一種方式，執行政策的步驟時都會執行 JavaScript 程式碼。如為來源檔案選項，原始碼一律儲存在 Proxy 組合中的標準位置：apiproxy/resources/jsc。或者，您也可以將原始碼儲存在環境或機構層級的資源檔案中。如需操作說明，請參閱「資源檔案」一節。您也可以透過 Apigee UI Proxy 編輯器上傳 JavaScript。

JavaScript 來源檔案一律有 .js 副檔名。

如要瞭解目前支援的 JavaScript 版本，請參閱支援的軟體和支援的版本。

影片

請觀看短片，瞭解如何使用 JavaScript 政策建立自訂政策擴充功能。

範例

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite">
    <DisplayName>target-rewrite</DisplayName>
    <Properties/>
    <ResourceURL>jsc://js-example.js</ResourceURL>
</Javascript>

元素參照

元素參考資料說明 JavaScript 政策的元素和屬性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" 
        continueOnError="false" enabled="true" timeLimit="200" 
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>

</Javascript>

<JavaScript> 屬性

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

下列屬性專屬於這項政策，

下表說明所有政策父項元素的通用屬性：

<DisplayName> 元素

除了 name 屬性外，您還可以使用不同的自然語言名稱，在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>

<IncludeURL> 元素

指定要以 <ResourceURL> 或 <Source> 元素指定的主要 JavaScript 檔案依附元件載入的 JavaScript 程式庫檔案。系統會按照政策中列出的順序評估指令碼。您的程式碼可以使用 JavaScript 物件模型的物件、方法和屬性。

加入多個 JavaScript 依附元件資源，以及額外的 <IncludeURL> 元素。

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

範例

請參閱「範例」部分中的基本範例。

<Property> 元素

指定您可以在執行階段從 JavaScript 程式碼存取的屬性。

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

屬性

範例

請參閱範例一節中的範例。

<ResourceURL> 元素

指定要在 API 流程中執行的主要 JavaScript 檔案。您可以將這個檔案儲存在 API Proxy 範圍 (API Proxy 套件的 /apiproxy/resources/jsc 之下或 API Proxy 編輯器「Navigator」窗格的「Scripts」區段內)，或是在機構或環境範圍中供多個 API Proxy 重複使用，如資源檔案中所述。您的程式碼可以使用 JavaScript 物件模型的物件、方法和屬性。

<ResourceURL>jsc://my-javascript.js</ResourceURL>

範例

請參閱「範例」部分中的基本範例。

<Source> 元素

允許您將 JavaScript 直接插入政策的 XML 設定。當政策在 API 流程中執行時，系統就會執行插入的 JavaScript 程式碼。

範例

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

<SSLInfo> 元素

指定用來為 JavaScript 政策建立的所有 HTTP 用戶端執行個體設定 TLS 的屬性。

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>

為 HTTP 用戶端設定 TLS 的程序與為 TargetEndpoint/TargetServer 設定 TLS 的程序相同。 詳情請參閱「設定從 Edge 到後端的 TLS」。

使用須知

JavaScript 政策不含任何實際程式碼。相反地，JavaScript 政策會參照 JavaScript「資源」，並在執行 JavaScript 的 API 流程中定義步驟。您可以透過管理 UI Proxy 編輯器上傳指令碼，也可以在在本機開發的 API Proxy 中，將指令碼加入 /resources/jsc 目錄。

對 JavaScript 政策程式碼進行偵錯

使用 print() 函式，將偵錯資訊輸出至追蹤工具中的交易輸出面板。如需瞭解詳情和範例，請參閱使用 JavaScript print() 陳述式進行偵錯。

如何在 Trace 中查看輸出陳述式：

1. 開啟追蹤工具，然後針對包含您 JavaScript 政策的 Proxy 啟動追蹤工作階段。
2. 呼叫 Proxy。
3. 在追蹤記錄工具中，按一下「Output from all Transactions」(所有交易的輸出內容) 開啟輸出面板。

   

4. 你的列印對帳單會顯示在這個面板中。

您可以使用 print() 函式將偵錯資訊輸出至追蹤記錄工具。這個函式可直接透過 JavaScript 物件模型使用。詳情請參閱「使用 print() 陳述式對 JavaScript 進行偵錯」。

流程變數

根據預設，這項政策不會填入任何變數；不過，您可以藉由呼叫結構定義物件的方法，在 JavaScript 程式碼中設定 (及 get) 流程變數。典型的模式如下：

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

情境物件是 Apigee Edge JavaScript 物件模型的一部分。

錯誤參考資料

本節說明當這項政策觸發錯誤時，傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。如果您開發的錯誤規則來處理錯誤，請務必瞭解這些資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時，可能會發生這些錯誤。

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

錯誤變數

當這項政策在執行階段觸發錯誤時，系統會設定這些變數。詳情請參閱「政策錯誤須知」。

錯誤回應範例

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

故障規則示例

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

結構定義

每個政策類型都是由 XML 結構定義 (.xsd) 定義。如需參考，GitHub 提供政策結構定義。

相關主題

• JavaScript 物件模型
• 如需操作說明、政策範例和 JavaScript 範例，請參閱使用 JavaScript 編寫程式設計 API Proxy 一文。

Apigee 社群文章

您可以前往 Apigee 社群找到下列相關文章：

• 如何處理 JavaScript 中的多重值標頭？