JavaScript 政策

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

此政策允许您添加在 API 代理流上下文中执行的自定义 JavaScript 代码。在自定义 JavaScript 代码中，您可以使用 Apigee Edge JavaScript 对象模型的对象、方法和属性。对象模型让您可在代理流上下文中获取、设置和移除变量。您还可以使用随对象模型提供的基本加密函数。

简介

JavaScript 政策有许多用例。例如，您可以获取和设置流变量，执行自定义逻辑并执行故障处理，从请求或响应中提取数据，动态编辑后端目标网址，等等。通过此政策，您可以实现任何其他标准 Edge 政策均未涵盖的自定义行为。实际上，您可以使用 JavaScript 政策来实现其他政策实施的许多行为，如 AssignMessage 和 ExtractVariable。

对于 JavaScript 政策，我们不建议的用例是日志记录。消息日志记录政策更适合记录到 Splunk，Sumo 和 Loggly 等第三方日志记录平台，并且您可通过在 PostClientFlow 中执行消息日志记录政策来提高 API 代理性能。PostClientFlow 在将响应发送回客户端后执行。

JavaScript 政策让您可以指定要执行的 JavaScript 源文件，或者您可以使用 <Source> 元素直接在政策的配置中添加 JavaScript 代码。无论采用哪种方式，JavaScript 代码在执行政策关联的步骤时都会执行。对于源文件选项，源代码始终存储在代理软件包中的标准位置：apiproxy/resources/jsc。或者，您也可以将源代码存储在环境或组织级层的资源文件中。如需了解相关说明，请参阅资源文件。您还可以通过 Apigee 界面代理编辑器上传 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 属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>

<IncludeURL> 元素

指定要作为使用 <ResourceURL> 或 <Source> 元素指定的主要 JavaScript 文件的依赖项加载的 JavaScript 库文件。脚本将按政策中的列出顺序进行评估。您的代码可以使用 JavaScript 对象模型的对象、方法和属性。

使用附加 <IncludeURL> 元素添加多个 JavaScript 依赖项资源。

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

示例

请参阅示例部分中的“基本示例”。

<Property> 元素

指定可在运行时从 JavaScript 代码访问的属性。

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

属性

示例

请参阅示例部分中的示例。

<ResourceURL> 元素

指定将在 API 流中执行的主要 JavaScript 文件。您可以在 API 代理范围（API 代理软件包的 /apiproxy/resources/jsc 下方或 API 代理编辑器导航工具窗格的“脚本”部分中）或组织或环境范围中存储此文件，以便在多个 API 代理中重复使用，如资源文件中所述。您的代码可以使用 JavaScript 对象模型的对象、方法和属性。

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

示例

请参阅示例部分中的“基本示例”。

<Source> 元素

允许您将 JavaScript 直接插入到政策的 XML 配置中。插入的 JavaScript 代码在 API 流中执行时执行。

示例

<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 的过程相同。如需了解详情，请参阅配置从边缘到后端的 TLS。

使用说明

JavaScript 政策不包含实际代码。相反，JavaScript 政策会引用 JavaScript“资源”，并在执行 JavaScript 的 API 流中定义步骤。您可以通过管理界面代理编辑器上传脚本，也可以将其添加到本地开发的 API 代理的 /resources/jsc 目录中。

调试 JavaScript 政策代码

使用 print() 函数将调试信息输出到 Trace 工具中的事务输出面板。如需了解详情和示例，请参阅使用 JavaScript print() 语句进行调试。

要在 Trace 中查看 print 语句，请执行以下操作：

1. 打开 Trace 工具并为包含 JavaScript 政策的代理启动跟踪会话。
2. 调用代理。
3. 在 Trace 工具中，点击从所有事务输出以打开输出面板。

   

4. 您的 print 语句将显示在此面板中。

您可以使用 print() 函数将调试信息输出到 Trace 工具。此函数可直接通过 JavaScript 对象模型提供。如需了解详情，请参阅“使用 print() 语句调试 JavaScript”。

流变量

默认情况下，此政策不会填充任何变量；但是，您可以通过在上下文对象上调用方法，在 JavaScript 代码中设置（和获取）流变量。典型模式如下所示：

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

上下文对象是 Apigee Edge JavaScript 对象模型的一部分。

错误参考信息

本部分介绍了在此政策触发错误时返回的错误代码和错误消息，以及 Edge 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

故障变量

当此政策在运行时触发错误时，将设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

错误响应示例

{
  "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 代理编程。

Apigee 社区文章

您可以在 Apigee 社区中找到以下相关文章：

• 如何在 JavaScript 中处理多值标头？