JavaScript オブジェクトモデル

このページは Apigee と Apigee ハイブリッドに適用されます。

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

このトピックでは、Apigee 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>

emit-results.js では、コードは次のようになる可能性があります。

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");

X.509 証明書で WS-Security を使用して SOAP ドキュメントを保護する

RSA/X.509 デジタル署名で WS-Security を使用して SOAP ドキュメントを保護します。

crypto.wsSecRsaSign()

SOAP ドキュメントに署名し、署名付きペイロードを返します。

構文

crypto.wsSecRsaSign(payload, options)

パラメータ

ペイロード -（文字列）署名する SOAP ドキュメント。

オプション -（オブジェクト）デジタル署名の構成オプション。次のテーブルに、使用可能な構成オプションを示します。すべてのオプション値は、リテラル文字列またはメッセージテンプレートにできます。メッセージテンプレートは、テンプレート文字 '{' と '}' を使用して示します。

名前	必須？	説明
`certificate`	必須	PEM 形式の秘密鍵と一致する証明書。
`private_key`	必須	PEM 形式の秘密鍵を含むフロー変数。
`c14_inclusive_elements`	オプション	`CanonicalizationMethod` 要素に `InclusiveElements` 要素を追加するために使用される名前空間 URI（接頭辞ではない）のカンマ区切りリスト。
`confirmation`	オプション	次のいずれかになります。署名される `SignatureConfirmation` 要素内の署名値のリスト。指定された値を持つ `SignatureConfirmation` 要素が存在しない場合は、挿入されます。ソースドキュメント内の既存の `SignatureConfirmation` 要素が署名されることを示す `\all\` 文字列。空の `SignatureConfirmation` 要素を挿入することを示す空の文字列。これらの確認シグネチャは、`elements-to-sign` で指定された要素に加えて使用されます。
`digest_method`	オプション	ダイジェストアルゴリズム。有効な値は `sha1` または `sha256` です。デフォルトは `sha256` です。
`ds_prefix`	オプション	Namespace の接頭辞として使用される単純な文字列。
`elements_to_sign`	オプション	署名する要素の XPath 式の配列（`["soapenv:Body"]` など）。
`expiry`	オプション	`Timestamp` の `Expires` 要素に挿入する値。120 秒、10 分、4 日を示すには、120s、10m、4d などの値を入力します。デフォルトでは有効期限はありません。
`ignore_security_header_placement`	オプション	署名なしペイロード内の既存の `Security` ヘッダーの配置を確認するかどうかを指定するブール値。一部の以前のシステムとの互換性のために提供されます。`true` に設定すると、API が署名ラッピング攻撃にさらされる可能性があるため、おすすめしません。デフォルトは `false` です。
`issuer_name_style`	オプション	発行者名の形式。有効な値は `CN` または `DN` です。
`key_identifier_type`	オプション	キーの識別子タイプ有効な値は `BinarySecurityToken`、`BST_DIRECT_REFERENCE`、`ISSUER_SERIAL`、`RSA_KEY_VALUE`、`THUMBPRINT`、`X509_CERT_DIRECT` です。デフォルトは `BinarySecurityToken` です。
`private_key_password`	オプション	秘密鍵が暗号化されている場合は、パスワード鍵。
`signing_method`	オプション	署名に使用されるメソッド。有効な値は `rsa-sha1` または `rsa-sha256` です。デフォルトは `rsa-sha1` ですが、`rsa-sha256` に設定することを強くおすすめします。
`soap_version`	オプション	SOAP バージョン。有効なバージョンは 1.1 と 1.2 です。デフォルトは 1.1 です。
`transform_inclusive_elements`	オプション	`Transform` 要素に `InclusiveElements` 要素を追加するために使用される名前空間 URI（接頭辞ではない）のカンマ区切りリスト。

例

次の例は、SOAP ドキュメントに署名する方法を示しています。秘密鍵と証明書がフロー変数に読み込まれていることを前提としています。

var signed = crypto.wsSecRsaSign(request.content, {
    'private_key': '{private.key.pem}', // Flow variable name
    'certificate': '{public.cert.pem}', // Flow variable name
    'elements_to_sign: 
        'wsu:Timestamp, soap:Body, wsa:To, wsa:MessageID',
    'signing_method': 'rsa-sha256',
    'digest_method': 'sha256',
    expires_in': '180s'
});

X.509 証明書で WS-Security を使用して SOAP ドキュメントを検証する

RSA/X.509 で WS-Security を使用して SOAP ドキュメントのデジタル署名を検証します。Gaambo は、渡された引数が有効であることを確認するために検証を行います。

crypto.wsSecRsaValidate()

SOAP ドキュメントのデジタル署名を検証します。

構文

crypto.wsSecRsaValidate(payload, options)

パラメータ

ペイロード -（文字列）検証するデジタル署名を含む SOAP ドキュメント。

オプション -（オブジェクト）検証の構成オプション。次のテーブルに、使用可能な構成オプションを示します。すべてのオプション値は、リテラル文字列またはメッセージテンプレートにできます。メッセージテンプレートは、テンプレート文字 '{' と ''}' を使用して示します。

名前	必須？	説明
`accept_subject_cns`	オプション	署名者として認められるサブジェクトの共通名（CN）のカンマ区切りのリスト。指定された CN のいずれとも一致しない CN からの署名がある場合、検証は失敗します。
`accept_thumbprints`	オプション	署名者として認められる証明書の SHA-1 サムプリントのカンマ区切りのリスト。署名が、指定されたサムプリントのいずれとも一致しないサムプリントを持つ証明書からのものである場合、検証は失敗します。`accept-thumbprints` または `accept-thumbprints-256` のいずれかのみを指定します。`certificate` オプションが指定されていない場合は、これらのオプションのいずれかが必要です。
`accept_thumbprints_256`	オプション	署名者として認められる証明書の SHA-256 サムプリントのカンマ区切りのリスト。署名が、指定されたサムプリントのいずれとも一致しないサムプリントを持つ証明書からのものである場合、検証は失敗します。`accept-thumbprints` または `accept-thumbprints-256` のいずれかのみを指定します。`certificate` オプションが指定されていない場合は、これらのオプションのいずれかが必要です。
`certificate`	オプション	署名を検証するための公開鍵を提供する証明書。署名付きドキュメントの `KeyInfo` で証明書が明示的に指定されていない場合にのみ必要となり、使用されます。
`digest_method`	オプション	サポートされているダイジェストメソッド。有効な値は `sha1` または `sha256` です。省略した場合、ダイジェストメソッドは確認されません。
`ignore_certificate_expiry`	オプション	指定された証明書の有効期間を無視するかどうかを指定するブール値。テストに便利です。デフォルトは `false` です。
`ignore_expiry`	オプション	SOAP ドキュメントの有効性を評価するときに `Timestamp/Expires` フィールドを無視するかどうかを指定するブール値。デフォルトは `false` です。
`ignore_security_header_placement`	オプション	署名付きペイロードでセキュリティヘッダーの配置をチェックするかどうかを指定するブール値。一部の以前のシステムとの互換性のために提供されます。この値を `true` に設定すると、API が署名ラッピング攻撃にさらされる可能性があるため、おすすめしません。デフォルトは `false` です。
`issuer_name_dn_comparison`	オプション	2 つの発行者名が同じエンティティを参照しているかどうかを判断するために使用するメソッド。署名付きドキュメントに `X509IssuerSerial` をラップする `KeyInfo` が含まれており、`issuer-name-style` が `DN`（デフォルト）の場合にのみ適用されます。値は {`string`、`normal`、`reverse`、`unordered`} のいずれかにできます。デフォルトは `string` です。
`issuer_name_dn_comparison_exclue_numeric_oids`	オプション	2 つの発行者名が同じエンティティを参照しているかどうかを判断するために使用されるメソッド。署名付きドキュメントに `X509IssuerSerial` をラップする `KeyInfo` が含まれており、`issuer-name-style` が `DN`（デフォルト）で、`issuer-name-dn-comparison` が `normal`、`reverse`、または `unordered` に設定されている場合にのみ適用されます。
`issuer_name_style`	オプション	発行者名の形式。署名付きドキュメントに `X509IssuerSerial` をラップする `KeyInfo` が含まれている場合にのみ使用されます。有効な値には、`CN`、`DN` が含まれます。
`max_lifetime`	オプション	署名付きドキュメントの最大有効期間。120 秒、10 分、4 日を示すには、120s、10m、4d などの値を入力します。このオプションでは、`Timestamp` に `Created` 要素と `Expires` 要素を含める必要があります。デフォルトでは、最大存続期間はありません。
`require_expiry`	オプション	タイムスタンプに有効期限が必要かどうかを指定するブール値。この値は `true` のままにしておくことをおすすめします。デフォルトは `true` です。
`required_sign_elements`	オプション	署名が必要な要素を示す `prefix:Tag` 形式のカンマ区切りまたはスペース区切りのリスト。デフォルトは `soap:Body, wsu:Timestamp` です。検証時にタイムスタンプのみの署名を必要とし、本文の署名を必要としない場合は、これを `wsu:Timestamp` に設定します。検証時に本文の署名のみを必要とし、タイムスタンプを必要としない場合は、これを `soap:Body` に設定します。プレフィックスとタグでは大文字と小文字が区別されます。変更する特別な理由がない限り、この値はデフォルトのままにしておくことをおすすめします。
`signing_method`	オプション	署名付きドキュメントの署名方法と一致している必要がある署名方法。有効な値は `rsa-sha1` または `rsa-sha256` です。省略すると、署名方法は確認されません。

例

次の例は、署名付き SOAP ベースの API を検証する方法を示しています。署名が無効な場合、フロー変数 wssec_error に特定のエラーが入力されます。

Var isValid = crypto.wsSecRsaValidate(request.content, {
        MaxLifetime: '300s',
        RequiredSignedElements: [
            '//*[local-name()=\'Body\']'
        ],
        IgnoreCertificateExpiry: false,
        TrustStore: '{truststore.pem}' // Flow variable with trusted certs
    });

 if (!isValid) {
   throw "invalid"
 }

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

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

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

context オブジェクトの概要

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

名前	説明	プロパティ
`context`	メッセージ処理パイプラインのコンテキストと、ProxyEndpoint と TargetEndpoint が実行するリクエスト / レスポンスフローのラッパー。	flow、session
`context.proxyRequest`	ProxyEndpoint への受信リクエストメッセージ（リクエスト側のアプリから API プロキシへのメッセージ）を表すオブジェクト。	headers、query parameters、method、body、url
`context.targetRequest`	TargetEndpoint からの送信リクエストメッセージ（API プロキシからバックエンドサービスへのメッセージ）を表すオブジェクト。	headers、query parameters、method、body、url
`context.targetResponse`	受信ターゲットレスポンスメッセージ（バックエンドサービスから API プロキシへのメッセージ）を表すオブジェクト。	headers、content、status
`context.proxyResponse`	送信プロキシレスポンスメッセージ（API プロキシからリクエスト側のアプリへのメッセージ）を表すオブジェクト。	headers、content、status
`context.flow`	現在のフローの名前。	context.flow をご覧ください。
`context.session`	同じコンテキストで実行している 2 つの異なるステップ間でオブジェクトを渡すために使用できる名前と値のペアのマップ。例: `context.session['key'] = 123`。	このオブジェクトを使用するタイミングと使用しないタイミングについて詳しくは、context.session['hello'] = {} と context.setVariable("hello", {}) の違いをご覧ください。

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) で定義された条件付きフローが含まれます。

共通の JavaScript が複数のフローで実行され、実行されるフローによって動作が変わる場合、このプロパティは便利です。複数の API プロキシで再利用する JavaScript モジュールに Flow プロパティを使用します。このコードは、ロジックの実行前に現在のフローを確認するために使用されます。

例

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 を使用して変数を取得 / 設定する場合と、context.getVariable() と context.setVariable() を使用する場合の違いを理解しておくことが重要です。詳しくは、Apigee コミュニティのディスカッションをご覧ください。

例

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

context.session['key']  = 123;

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

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

サンプル: context.session オブジェクトの使用例については、非同期コールアウトのサンプル API プロキシをご覧ください。

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 コードの実行時にスコープ内にあるリクエストフロー内のプロパティにアクセスできます。

注: 短縮オブジェクト request を使用してリクエストフローでこれらのプロパティにアクセスすることもできます。request オブジェクトでは、JavaScript コードが実行されるフロー内の場所に応じて context.proxyRequest または context.targetRequest を参照します。

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

プロパティ名	説明
`url`	`url` プロパティは、読み取り / 書き込みのコンビニエンスプロパティです。targetRequest のスキーム、ホスト、ポート、パス、クエリパラメータが組み合わされます。リクエストの完全な URL は、次のプロパティから構成されます。 protocol: URL のプロトコル（HTTP、HTTPS など） port: ポート（:80、:443 など） host: URL のホスト（www.example.com など） path: URI のパス（/v1/mocktarget など） `url` を取得すると、URL が次の形式で返されます。 `protocol://host:port/path?queryParams`
`url`	例: context.targetRequest.url = 'http://www.example.com/path?q1=1' context.targetRequest.protocol ='https';
`headers`	`String => List` のマッピングとしての HTTP リクエストヘッダー
`headers`	例: 次の HTTP リクエストに対して、 POST /v1/blogs HTTP/1.1 Host: api.example.com Content-Type: application/json Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z 次のように JavaScript を記述した場合、 context.proxyRequest.headers['Content-Type']; context.proxyRequest.headers['Authorization']; 次の値が返されます。 application/json Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z
`queryParams`	`String => List` のマッピングとしてのリクエストメッセージのクエリパラメータ。
`queryParams`	例: "?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
`method`	リクエストに関連する HTTP 動詞（GET、POST、PUT、DELETE. PATCH など）
`method`	例: 次のリクエストに対して、 POST /v1/blogs HTTP/1.1 Host: api.example.com Content-Type: application/json Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z 次のように JavaScript を記述した場合、 context.proxyRequest.method; 次の値が返されます。 POST
`body`	HTTP リクエストのメッセージの本文（ペイロード）リクエスト本文には次のメンバーがあります。 `context.targetRequest.body.asXML;` `context.targetRequest.body.asJSON;` `context.targetRequest.body.asForm;`
`body`	例: 次のような XML 本文において、 <customer number='1'> <name>Fred<name/> <customer/> XML オブジェクトの要素にアクセスするには、次のようにします。 var name = context.targetRequest.body.asXML.name; XML 属性にアクセスするには、`@` 表記を使用します。 var number = context.targetRequest.body.asXML.@number; JSON リクエスト本文の場合: { "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 コードの実行時にスコープ内にあるレスポンスフロー内のプロパティにアクセスできます。

注: 短縮オブジェクト response を使用して、レスポンスフローからこれらのプロパティにアクセスすることもできます。response オブジェクトでは、JavaScript コードが実行されるフロー内の場所に応じて context.proxyResponse または context.targetResponse を参照します。

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

プロパティ名	説明
`headers`	`String => List` のマッピングとしてのレスポンスメッセージの HTTP ヘッダー。
`headers`	例: var cookie = context.targetResponse.headers['Set-Cookie'];
`status`	ステータスコードとステータスメッセージ。ステータスコードとステータスメッセージは両方ともプロパティとして使用できます。
`status`	例: var status = context.targetResponse.status.code; // 200 var msg = context.targetResponse.status.message; // "OK"
`content`	レスポンスメッセージの HTTP 本文（ペイロードコンテンツ）レスポンスコンテンツには次のメンバーがあります。 context.targetResponse.content.asXML; context.targetResponse.content.asJSON;
`content`

.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(): リクエストが完了する（成功するか、エラーになる）まで、スレッドを一時停止します。
アンチパターン: waitForComplete の使用は推奨されません。アンチパターンとみなされます。代わりにコールバックを使用することをおすすめします。詳しくは、アンチパターン: JavaScript コードで waitForComplete() を使用するをご覧ください。
getResponse(): （オブジェクト）httpClient.send() が完了して成功すると、レスポンスオブジェクトが返されます。返されるオブジェクトには、context.proxyResponse オブジェクトと同じメソッドとプロパティが含まれます。コンテキストオブジェクトの概要をご覧ください。
getError(): （文字列）httpClient.send() の呼び出しでエラーが発生した場合、エラーメッセージが文字列として返されます。

例

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

注: レスポンスを非同期的に処理する場合は、コールバックの使用をおすすめします。waitForComplete() 関数の使用は推奨されません。また、アンチパターンとみなされます。アンチパターン: JavaScript コードで waitForComplete() を使用するもご覧ください。

// 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 オブジェクト モデルについて

context オブジェクト

crypto オブジェクト

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

print() 関数

properties オブジェクト

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

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

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

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

MD5 オブジェクトの操作

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

X.509 証明書で WS-Security を使用して SOAP ドキュメントを保護する

X.509 証明書で WS-Security を使用して SOAP ドキュメントを検証する

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

crypto を使用したサンプル

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

context オブジェクトの概要

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

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

context オブジェクトの子

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

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

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

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

.asXML 表記の使用

例

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

httpClient での JavaScript コールアウトの作成

httpClient について

httpClient リファレンス

httpClient.get()

例

JavaScript ポリシーの使用

関連トピック

JavaScript オブジェクトモデル

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

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