JavaScript ポリシー

概要

このポリシーを使用すると、API プロキシフローの処理中にカスタム JavaScript コードを実行できます。カスタム JavaScript コードでは、Apigee Edge JavaScript オブジェクト モデルのオブジェクト、メソッド、プロパティを使用できます。このオブジェクト モデルを使用すると、プロキシフローの処理中に変数を取得、設定、削除できます。オブジェクト モデルで提供される基本的な暗号機能を使用することもできます。

説明

JavaScript ポリシーには数多くのユースケースがあります。たとえば、フロー変数の取得と設定、カスタム ロジックの実行と障害処理の実施、リクエストやレスポンスからのデータの抽出、バックエンド ターゲット URL の動的編集などがあります。また、標準の Edge ポリシーに含まれていないカスタム動作を実装することもできます。実際に、JavaScript ポリシーを使用して、AssignMessage や ExtractVariable などの他のポリシーにより実装されるのと同じ動作を数多く実現できます。

JavaScript ポリシーでのロギングはおすすめできません。Message Logging ポリシーは、Splunk、Sumo、Loggly などのサードパーティのロギング プラットフォームへのロギングに適しています。レスポンスがクライアントに返された後に実行する PostClientFlow で Message Logging を実行することによって、API プロキシのパフォーマンスが向上します。

基本的に、JavaScript ポリシーは、実行する JavaScript ソースファイルの名前を、ポリシーが接続されているステップを実行するときに指定します。ソースファイルは常に、プロキシ バンドル内の標準の場所 apiproxy/resources/jsc に保存されます。あるいは、ソースコードを環境レベルあるいは組織レベルのリソース ファイルに保存することもできます。手順については、リソース ファイルをご覧ください。管理 UI プロキシ エディタを介して 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>
</Javascript>

<Javascript> 属性

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

以下の属性は、このポリシーに固有のものです。

次の表に、すべてのポリシーの親要素に共通する属性を示します。

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

<IncludeURL> 要素

<ResourceURL> 要素で指定されたメインの 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>

例

サンプル セクションの基本的な例をご覧ください。

<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 の構成をご覧ください。

HTTP クライアントの作成の詳細については、JavaScript での HTTP クライアントの実装をご覧ください。

使用上の注意

JavaScript ポリシーに実際のコードは含まれません。その代わりに、JavaScript ポリシーは JavaScript の「リソース」を参照し、JavaScript を実行する API フローにステップを定義します。Management UI のプロキシ エディタを通じてスクリプトをアップロードするか、ローカルで開発している API プロキシの /resources/jsc ディレクトリにスクリプトを含めることができます。

JavaScript ポリシーコードのデバッグ

print() 関数を使用して、デバッグ情報を Trace ツールのトランザクション出力パネルに出力します。詳細と例については、JavaScript の print() ステートメントを使用したデバッグをご覧ください。

print ステートメントを Trace で表示するには、次の手順を実行します。

1. Trace ツールを開き、JavaScript ポリシーを含むプロキシのトレース セッションを開始します。
2. プロキシを呼び出します。
3. Trace ツールで、[Output from all Transactions] をクリックして出力パネルを開きます。

   

4. print ステートメントはこのパネルに表示されます。

print() 関数を使用して、デバッグ情報を Trace ツールに出力できます。この関数は、JavaScript オブジェクト モデルで直接使用できます。詳しくは、print() ステートメントで JavaScript をデバッグするをご覧ください。

フロー変数

このポリシーは、デフォルトでは変数に何も入力しません。ただし、JavaScript コードでフロー変数を設定（および取得）できます。その場合は、コンテキスト オブジェクトでメソッドを呼び出します。一般的なパターンは以下のようになります。

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

コンテキスト オブジェクトは、Apigee Edge JavaScript オブジェクト モデルの一部です。

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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 Edge 用の本格的な JavaScript アプリをビルドしてデプロイする手順については、JavaScript での HTTP クライアントの実装をご覧ください。

Apigee コミュニティの記事

次の関連記事は、Apigee コミュニティでご覧いただけます。

• JavaScript で複数値ヘッダーを処理する方法