JavaScript オブジェクト モデル

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

このトピックでは、Apigee Edge JavaScript オブジェクト モデルについて説明します。JavaScript ポリシーを使用してカスタム JavaScript を API プロキシに追加する場合は、このモデルを理解しておく必要があります。

JavaScript オブジェクト モデルについて

JavaScript オブジェクト モデルは、Apigee プロキシフロー内で実行される JavaScript コードで使用可能な関連プロパティを持つオブジェクトを定義します。JavaScript ポリシーを使用して、このカスタムコードを API プロキシフローに追加します。

このモデルで定義されるオブジェクトのスコープは、API プロキシフロー内です。つまり、特定のオブジェクトとプロパティはフロー内の特定の箇所でのみ使用できます。JavaScript が実行されると、実行用のスコープが作成されます。このスコープでは、次のオブジェクト参照が作成されます。

• context: メッセージ コンテキストへのアクセスを提供するオブジェクト
• request: リクエスト オブジェクトへのアクセスを許可する簡略リファレンス
• response: リクエスト オブジェクトへのアクセスを許可する簡略リファレンス
• crypto: さまざまなハッシュ関数を提供する
• print: 出力を返す関数
• properties: ポリシーの構成プロパティへの読み取りアクセスを許可する

context オブジェクト

context オブジェクトのスコープはグローバルです。これは、API プロキシフロー内の任意の場所で使用できます。このオブジェクトには、proxyRequest、proxyResponse、targetRequest、targetResponse の 4 つの子オブジェクトがあります。これらの子オブジェクトのスコープは、環境のリクエストとレスポンスです。つまり、プロキシのリクエストとレスポンス、またはターゲットのリクエストとレスポンスが、スコープになります。たとえば、JavaScript ポリシーがフローのプロキシ エンドポイントの部分で実行される場合、context.proxyRequest オブジェクトと context.proxyResponse オブジェクトはスコープに含まれます。JavaScript がターゲット フローで実行される場合、context.targetRequest オブジェクトと context.targetResponse オブジェクトはスコープに含まれます。

context オブジェクトには、プロパティとメソッドも含まれます。詳しい内容は、このトピックで説明します。たとえば、次の JavaScript コードの例では、context.flow プロパティを使用して、context に対して get/setVariable() メソッドを呼び出します。

if (context.flow=="PROXY_REQ_FLOW") {
     var username = context.getVariable("request.formparam.user");
     context.setVariable("USER.name", username);
}

これらのメソッドでは、フロー変数と直接やり取りします。context.flow プロパティ値は現在のフローのスコープです。プロキシ リクエスト フローでは、この値は定数 PROXY_REQ_FLOW に設定されます。ターゲット レスポンス フローでは、TARGET_RESP_FLOW に設定されます。この定数は、スコープ固有のコードを実行する場合に便利です。getter を使用すると、フロー変数が取得できます。また、setter を使用すると、フロー変数を設定できます。これらの変数は、プロキシフローで提供され、他のポリシーで消費できます。

詳細と例については、コンテキスト オブジェクトのリファレンスをご覧ください。

crypto オブジェクト

crypto オブジェクトでは、JavaScript オブジェクト モデルに基本的な高パフォーマンスの暗号サポートが追加されます。詳細と例については、crypto オブジェクトのリファレンスをご覧ください。

request オブジェクトと response オブジェクト

request オブジェクトと response オブジェクトは、アンビエントのリクエストとレスポンス（プロキシのリクエストとレスポンス、またはターゲット リクエストとレスポンスのいずれか）に関する簡略リファレンスです。これらの変数が参照するオブジェクトは、JavaScript ポリシーが実行されるコンテキストによって異なります。JavaScript がプロキシ エンドポイントのフローで実行されている場合、request 変数と response 変数は context.proxyRequest と context.proxyResponse を参照します。JavaScript がターゲット フローで実行される場合、これらの変数は context.targetRequest と context.targetResponse を参照します。

print() 関数

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

properties オブジェクト

ポリシー構成で Properties 要素を使用している場合、JavaScript コードでは properties 変数を使用してこれらのプロパティの値にアクセスできます。

たとえば、JavaScript 構成に以下が含まれているとします。

<Javascript name='JS-1' >
  <Properties>
    <Property name="number">8675309</Property>
    <Property name="firstname">Jenny</Property>
  </Properties>
  <ResourceURL>jsc://my-code.js</ResourceURL>
</Javascript>

my-code.js では、次のようになります。

  print(properties.firstname);  // prints Jenny
  print(properties.number);  // 8675309

実際には、さまざまな環境やタイミング、あるいは事情に基づいて実行される場合に、構成によりコードの動作が異なる場合があります。

たとえば、以下では「変数名」と JavaScript が情報を出力する形式を指定しています。

<Javascript name='JS-2' >
  <Properties>
    <Property name="output">my_output_variable</Property>
    <Property name="prettyPrint">true</Property>
  </Properties>
  <ResourceURL>jsc://emit-results.js</ResourceURL>
</Javascript>

var result = { prop1: "something", prop2 : "something else" } ;
if (properties.prettyPrint == "true") {
  context.setVariable(properties.output, JSON.stringify(result, null, 2));
}
else {
  context.setVariable(properties.output, JSON.stringify(result));
}

crypto オブジェクトのリファレンス

crypto オブジェクトを使用すると、JavaScript で基本的な暗号ハッシュ関数を実行できます。

crypto オブジェクトのスコープはグローバルです。API プロキシフロー内の任意の場所で使用できます。Crypto では、次のハッシュ オブジェクトを使用できます。

• SHA-1
• SHA256
• SHA512
• MD5

SHA-1 オブジェクトの操作

SHA-1 オブジェクトを作成して更新できます。また、16 進数または base64 値に変換することもできます。

新しい SHA-1 オブジェクトを作成する

var _sha1 = crypto.getSHA1();

SHA-1 オブジェクトを更新する

構文

_sha1.update(value);

パラメータ

• value -（文字列）任意の文字列値。

例

SHA-1 オブジェクトを更新する

_sha1.update("salt_value");

_sha1.update("some text");

SHA-1 オブジェクトを 16 進文字列として返す

var _hashed_token = _sha1.digest();

SHA-1 オブジェクトを base64 文字列として返す

var _hashed_token = _sha1.digest64();

SHA-256 オブジェクトの操作

SHA-256 オブジェクトを作成して更新できます。また、16 進数または base64 値に変換することもできます。

新しい SHA-256 オブジェクトを作成する

var _sha256 = crypto.getSHA256();

SHA-256 オブジェクトを更新する

構文

_sha256.update(value);

パラメータ

• value -（文字列）任意の文字列値。

例

SHA-256 オブジェクトを更新する

_sha256.update("salt_value");

_sha256.update("some text");

SHA-256 オブジェクトを 16 進文字列として返す

var _hashed_token = _sha256.digest();

SHA-256 オブジェクトを base64 文字列として返す

var _hashed_token = _sha256.digest64();

SHA-512 オブジェクトの操作

SHA-512 オブジェクトを作成して更新できます。また、16 進数または base64 値に変換することもできます。

新しい SHA-512 オブジェクトを作成する

var _sha512 = crypto.getSHA512();

SHA-512 オブジェクトを更新する

構文

_sha512.update(value);

パラメータ

• value -（文字列）任意の文字列値。

例

SHA-512 オブジェクトを更新する

_sha512.update("salt_value");

_sha512.update("some text");

SHA-512 オブジェクトを 16 進文字列として返す

var _hashed_token = _sha512.digest();

SHA-512 オブジェクトを base64 文字列として返す

var _hashed_token = _sha512.digest64();

MD5 オブジェクトの操作

MD5 オブジェクトを作成して更新できます。また、16 進数または base64 値に変換することもできます。

新しい MD5 オブジェクトを作成する

var _md5 = crypto.getMD5();

MD5 オブジェクトを更新する

構文

_md5.update(value);

パラメータ

• value -（文字列）任意の文字列値。

例

MD5 オブジェクトを更新する

_md5.update("salt_value");

_md5.update("some text");

MD5 オブジェクトを 16 進の文字列として返す

var _hashed_token = _md5.digest();

MD5 オブジェクトを base64 文字列として返す

var _hashed_token = _md5.digest64();

crypto での日付 / 時刻のサポート

crypto オブジェクトは、日付 / 時刻のフォーマット パターンをサポートしています。

crypto.dateFormat()

日付を文字列形式で返します。

構文

crypto.dateFormat(format, [timezone], [time])

パラメータ

• format -（文字列）このパラメータの基礎となる実装は java.text.SimpleDateFormat です。例: 'YYYY-MM-DD HH:mm:ss.SSS'
• timezone - （文字列、省略可）このパラメータの基板となる実装は java.util.TimeZone です。このパラメータのデフォルトは UTC です。
• time -（数値、省略可）書式設定する Unix タイムスタンプ値。デフォルトは、現在の時刻です。

例

現在の時刻をミリ秒単位まで取得するには、次のように記述します。

var _now = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS');

太平洋標準時の現在時刻を取得するには、次のように記述します。

var _pst = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS','PST');

現在から 10 秒の値を取得する:

var _timeNow = Number(context.getVariable('system.timestamp'));
var tenSeconds = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS','PST', _timeNow + 10 * 1000);

その他の例。java.text.SimpleDateFormat のドキュメントをご覧ください。

var _pst = crypto.dateFormat('M');

var _pst = crypto.dateFormat('EEE, d MMM yyyy HH:mm:ss Z');

var _pst = crypto.dateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ");

getHash() を使用してサポート対象のハッシュ オブジェクトを取得する

例

var _hash1 = crypto.getHash('MD5');

var _hash2 = crypto.getHash('SHA-1');

var _hash3 = crypto.getHash('SHA-256');

var _hash4 = crypto.getHash('SHA-512');

crypto を使用したサンプル

try {
    // get values to use with hash functions
    var salt = context.getVariable("salt") || 'SomeHardCodedSalt';
    var host = context.getVariable("request.header.Host");
    var unhashedToken = "";

    var _timeNow = Number(context.getVariable('system.timestamp'));
    var now = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS','PST', _timeNow);
    unhashed_token = "|" + now + "|" + host

    // generate a hash with the unhashedToken:
    var sha512 = crypto.getSHA512();
    sha512.update(salt);
    sha512.update(unhashedToken);

    // convert to base64
    var base64Token = sha512.digest64();

    // set headers
    context.setVariable("request.header.now", now);
    context.setVariable("request.header.token", base64Token);

} catch(e) {
    throw 'Error in Javascript';
}

コンテキスト オブジェクトのリファレンス

• context オブジェクトの概要
• context オブジェクトのメソッド
• context オブジェクトのプロパティ
• context オブジェクトの子

context オブジェクトは、API プロキシによって実行されるリクエスト / レスポンス トランザクションごとに作成されます。context オブジェクトは、各トランザクションに関連する変数の取得、設定、削除のためのメソッドをエクスポーズします。

これらの変数は、トランザクションに固有のプロパティを定義します。contextで使用できる変数の例としては、時刻、リクエスト側のクライアントのロケール、リクエスト側のクライアントのユーザー エージェント、ターゲット・サービスの URL があります。そのため、context は、これらのプロパティに依存してカスタム動作を実行するロジックを構築する場合に便利です。

フロー変数のリファレンスと ExtractVariables ポリシーをご覧ください。

context オブジェクトの概要

次の表に、context オブジェクトとその子オブジェクトの内容、および互いにバインドされるプロパティの一覧を示します。

context オブジェクトのメソッド

context.getVariable()

事前定義変数またはカスタム変数の値を取得します。

構文

context.getVariable("variable-name");

例

現在の年の値を取得するには、次のように記述します。

var year = context.getVariable('system.time.year');

context.setVariable()

カスタム変数または書き込み可能な事前定義された変数の値を設定します。

構文

context.setVariable("variable-name", value);

例

変数を設定する一般的なケースは、API プロキシによってターゲット URL が動的に書き込まれる必要がある場合です。以下の JavaScript では、USER.name という変数の値を取得し、その値をクエリ パラメータとして URL http://mocktarget.apigee.net?user= に追加して、事前定義された target.url をその値に設定します。

context.setVariable("target.url", "http://mocktarget.apigee.net/user?user="+context.getVariable("USER.name"));

context.removeVariable()

コンテキストから変数を削除します。

構文

context.removeVariable('variable-name');

context オブジェクトのプロパティ

context.flow

flow プロパティは、現在の API プロキシフローを識別する文字列です。このプロパティは、JavaScript が追加されたフローを表す場合に使用されます。サポートされている値は次のとおりです。

• PROXY_REQ_FLOW
• PROXY_RESP_FLOW
• TARGET_REQ_FLOW
• TARGET_RESP_FLOW

フロー名には、PreFlow と PostFlow の他に、ProxyEndpoint(s) または TargetEndpoint(s) で定義された条件付きフローが含まれます。

例

targetRequest フローでのみ HTTP ヘッダーを設定するには、次のように記述します。

if (context.flow=="TARGET_REQ_FLOW") {
     context.targetRequest.headers['TARGET-HEADER-X']='foo';
}

proxyResponse フローでのみコンテンツを設定するには、次のように記述します。

if (context.flow=="PROXY_RESP_FLOW") {
     context.proxyResponse.content='bar';
}

context.session

同じメッセージ コンテキストで実行する 2 つのポリシー間でオブジェクトを渡すために使用できる名前と値のペアのマップ。

例

セッションに値を設定するには、次のように記述します。

context.session['key']  = 123;

セッションから値を取得するには、次のように記述します。

var value = context.session['key']; // 123

context オブジェクトの子

以下に示すように、完全な API プロキシフローは 4 つの異なるフェーズから構成されています。各フェーズには、コンテキスト オブジェクトの子になるメッセージ オブジェクトが関連付けられています。

• context.proxyRequest: リクエスト側のクライアントから受信した受信リクエスト メッセージ。
• context.targetRequest: バックエンド サービスに送信された送信リクエスト メッセージ。
• context.proxyResponse: リクエスト側のクライアントに返される送信レスポンス メッセージ。
• context.targetResponse: バックエンド サービスから受信した受信リクエスト メッセージ。

以下のセクションでは、これらのオブジェクトのメソッドとプロパティについて説明します。

• context.*Request の子オブジェクト
• context.*Response の子オブジェクト

context.*Request の子オブジェクト

API プロキシで実行される HTTP トランザクションには、2 つのリクエスト メッセージ オブジェクトが作成されます。1 つは受信用（クライアントからのリクエスト）で、もう 1 つは送信用（API プロキシによって生成され、バックエンド ターゲットに送信されるリクエスト）です。

context オブジェクトには、これらのリクエスト メッセージを表す子オブジェクト（context.proxyRequest と context.targetRequest）があります。これらのオブジェクトを使用すると、JavaScript コードの実行時にスコープ内にあるリクエスト フロー内のプロパティにアクセスできます。

context.*Request の子オブジェクトのプロパティ

context.targetRequest.url = 'http://www.example.com/path?q1=1'
context.targetRequest.protocol ='https';

POST /v1/blogs HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z

context.proxyRequest.headers['Content-Type'];
context.proxyRequest.headers['Authorization'];

application/json
Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z

"?city=PaloAlto&city=NewYork"

context.proxyRequest.queryParams['city'];  // == 'PaloAlto'
context.proxyRequest.queryParams['city'][0]     // == 'PaloAlto'
context.proxyRequest.queryParams['city'][1];    // == 'NewYork'
context.proxyRequest.queryParams['city'].length(); // == 2

POST /v1/blogs HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z

context.proxyRequest.method;

POST

<customer number='1'>
<name>Fred<name/>
<customer/>

var name = context.targetRequest.body.asXML.name;

var number = context.targetRequest.body.asXML.@number;

{
"a":  1 ,
"b" : "2"
}

var a = context.proxyRequest.body.asJSON.a;    // == 1
var b = context.proxyRequest.body.asJSON.b;    // == 2

"vehicle=Car&vehicle=Truck"

v0 = context.proxyRequest.body.asForm['vehicle'][0];
v1 = context.proxyRequest.body.asForm['vehicle'][1];

context.*Response の子オブジェクト

API プロキシで実行される HTTP トランザクションには 2 つのリクエスト メッセージ オブジェクトが作成されます。1 つは受信用（バックエンド サービスからのリクエスト）で、もう 1 つは送信用（クライアントに返されるレスポンス）です。

context オブジェクトには、これらのレスポンス メッセージを表す子オブジェクト（context.proxyResponse と context.targetResponse）があります。これらのオブジェクトを使用すると、JavaScript コードの実行時にスコープ内にあるレスポンス フロー内のプロパティにアクセスできます。

context.*Response オブジェクトのプロパティ

var cookie = context.targetResponse.headers['Set-Cookie'];

var status = context.targetResponse.status.code;   // 200
var msg = context.targetResponse.status.message;   // "OK"

context.targetResponse.content.asXML;
context.targetResponse.content.asJSON;

.asXML 表記の使用

.asXML 表記を使用すると、XML ドキュメントを簡単に確認できます。このセクションでは、この表記の使用方法と、request.content や context.proxyRequest.content との違いについて説明します。

例:

request.content.asXML

または

context.proxyRequest.content.asXML

*.content と *.content.asXML のどちらの形式も、文字列のコンテキストで使用可能です。JavaScript では、これらの形式は強制的に文字列に変換されます。前者の場合（*.content）、文字列にはすべての宣言と XML コメントが含まれます。後者の場合（*.content.asXML）、結果の文字列値から宣言とコメントが削除されます。

例

msg.content:

<?xml version="1.0" encoding="UTF-8"?>
<yahoo:error xmlns:yahoo="http://yahooapis.com/v1/base.rng" xml:lang="en-US">
   <yahoo:description>Please provide valid credentials. OAuth oauth_problem="unable_to_determine_oauth_type", realm="yahooapis.com"
   </yahoo:description>
</yahoo:error>
<!-- mg023.mail.gq1.yahoo.com uncompressed/chunked Sat Dec 14 01:23:35 UTC 2013 -->

msg.content.asXML:

<?xml version="1.0" encoding="UTF-8"?>
<yahoo:error xmlns:yahoo="http://yahooapis.com/v1/base.rng" xml:lang="en-US">
   <yahoo:description>Please provide valid credentials. OAuth oauth_problem="unable_to_determine_oauth_type", realm="yahooapis.com"
   </yahoo:description>
</yahoo:error>

さらに、要素と属性の名前を指定することで、.asXML フォームを使用して XML 階層を走査できます。別の構文を使用して、階層を走査することはできません。

JavaScript の print() ステートメントを使用してデバッグする

JavaScript ポリシーを使用して、カスタム JavaScript コードを実行する場合は、print() 関数を使用して デバッグツールにデバッグ情報を出力できます。この関数は、JavaScript オブジェクト モデルで直接使用できます。例:

if (context.flow=="PROXY_REQ_FLOW") {
     print("In proxy request flow");
     var username = context.getVariable("request.queryparam.user");
     print("Got query param: " + username);
     context.setVariable("USER.name", username);
     print("Set query param: " + context.getVariable("USER.name"));
}


if (context.flow=="TARGET_REQ_FLOW") {
     print("In target request flow");
     var username = context.getVariable("USER.name");
     var url = "http://mocktarget.apigee.net/user?"
     context.setVariable("target.url", url + "user=" + username);
     print("Callout to URL: ", context.getVariable("target.url"));
}

出力を表示するには、デバッグ ウィンドウの下部にある [Output from all transactions] を選択します。stepExecution-stdout というデバッグ プロパティで出力を確認することもできます。

httpClient で JavaScript コールアウトを行う

httpClient を使用して、API プロキシフローで実行されるカスタム JavaScript コード内から、任意の URL に対して複数の非同期の HTTP リクエストを行います。httpClient オブジェクトは、Apigee JavaScript オブジェクト モデルで公開されます。

httpClient について

httpClient オブジェクトは、JavaScript オブジェクト モデルを介して Apigee で実行されるカスタム JavaScript コードに公開されます。カスタム JavaScript を API プロキシに接続するには、JavaScript ポリシーを使用します。ポリシーが実行されると、カスタム JavaScript コードが実行されます。

httpClient オブジェクトは、複合サービスやマッシュアップを開発するのに役立ちます。たとえば、複数のバックエンド呼び出しを 1 つの API メソッドに統合できます。

基本的な使用パターンは次のとおりです。Request オブジェクトをインスタンス化して（たとえば、呼び出し対象のバックエンド サービスの）URL に割り当て、そのリクエスト オブジェクトを使用して httpClient.send を呼び出します。

var myRequest = new Request();
myRequest.url = "http://www.example.com";
var exchangeObj = httpClient.send(myRequest);

httpClient リファレンス

HTTP クライアントは、get() と send() という 2 つのメソッドを公開します。

httpClient.get()

単純な HTTP GET リクエストに便利なメソッドで、HTTP ヘッダーのサポートはありません。

使用状況

var exchangeObj = httpClient.get(url);

戻り値

このメソッドは、exchange オブジェクトを返します。このオブジェクトにプロパティはありません。次のメソッドを公開します。

• isError(): （ブール値）httpClient がサーバーに接続できなかった場合に true が返されます。接続が完了して有効なレスポンス コードが返されたため、HTTP ステータス コード 4xx と 5xx が isError() falseになります。isError() が true を返す場合、getResponse() の呼び出しにより JavaScript の undefined が返されます。
• isSuccess(): （ブール値）送信が完了して成功した場合に、true が返されます。
• isComplete(): （ブール値）リクエストが完了すると true が返されます。
• waitForComplete(): リクエストが完了する（成功するか、エラーになる）まで、スレッドを一時停止します。
• getResponse():（オブジェクト）httpClient.send() が完了して成功すると、response オブジェクトが返されます。返されるオブジェクトには、context.proxyResponse オブジェクトと同じメソッドとプロパティが含まれます。コンテキスト オブジェクトの概要をご覧ください。
• getError():（文字列）httpClient.send() の呼び出しでエラーが発生した場合、エラー メッセージが文字列として返されます。

例

HTTP リクエストのプロパティを含む完全な構成の Request オブジェクトを送信します。非ブロック コールバックを使用してレスポンスを処理します。

// Add the required the headers for making a specific API request
var headers = {'X-SOME-HEADER' : 'some value' };
// Make a GET API request along with headers
var myRequest = new Request("http://www.example.com","GET",headers);

// Define the callback function and process the response from the GET API request
function onComplete(response,error) {
 // Check if the HTTP request was successful
    if (response) {
      context.setVariable('example.status', response.status);
     } else {
      context.setVariable('example.error', 'Woops: ' + error);
     }
}

// Specify the callback Function as an argument
httpClient.get(myRequest, onComplete);

JavaScript ポリシーの使用

JavaScript ポリシーを使用して、カスタム JavaScript コードをプロキシフローに追加します。 JavaScript ポリシーをご覧ください。

関連トピック

• JavaScript ポリシー
• JavaScript オブジェクト モデル
• アンチパターンの概要