コンテキスト変数

コンテキスト変数は、 が処理するリクエストと関連があります。 これらの変数によって、 で何が起きているかに関する豊富な情報を明らかにすることができるため、問題を解決するために非常に重要な助けになります。
gateway83
コンテキスト変数は、
Layer7 API Gateway
が処理するリクエストと関連があります。 これらの変数によって、
Layer7 API Gateway
で何が起きているかに関する豊富な情報を明らかにすることができるため、問題を解決するのに非常に重要な助けになります。
アサーションはコンテキスト変数を読み取ることができます。 その場合、アサーションが実行されると、変数の値は実行時に解決されます。 アサーションは、その変数をその他のアサーションで使用できるように、リクエスト コンテキストに変数を書き込むこともできます。
文字列内にコンテキスト変数を埋め込む場合は、以下の形式を使用します。
${context.variable.name}
例:
Send Email Alert または Return Template Response to Requestor アサーションで、「This transaction is being denied because the account ${request.authenticateduser} has exceeded quota. Please contact customer support at
${gateway.supportnumber}
for assistance.」というメッセージを作成します。 この場合は、区切り文字で囲む必要があります。
アサーションでコンテキスト変数の名前だけが必要な場合は、以下のように、区切り文字で囲まずにその名前を入力します。
context.variable.name
例:
Restrict Access to IP Address Range アサーションで、コンテキスト変数 request.http.header.remoteip から IP アドレスを解決するとします、 この場合、区切り文字は必要ありません。
(1) コンテキスト変数が失敗した場合のデフォルトの動作は、警告をログに記録し、空の文字列を使用することです。 コンテキスト変数を呼び出したアサーションは失敗しません。 コンテキスト変数が失敗した場合にアサーションが失敗するようにするには、template.strictMode クラスタ プロパティを「true」に設定します。 コンテキスト変数が失敗する例を次に示します: a)「
${request.http.header.abc}
」を呼び出しているが、そのリクエストに「abc」ヘッダがない。b)存在しないコンテキスト変数「
${someNonExistentVariable}
」をリクエストしている。
(2)組み込みのコンテキスト変数
${gateway.<propertyName>
} を使用して、クラスタ プロパティ値にアクセスできます。 組み込みの「gateway」プレフィックスの使用の詳細については、以下の表を参照してください。
(3)アサーションで設定および使用されるコンテキスト変数は、[Assertion Information]ダイアログ ボックスを表示することによって確認できます。
一部のコンテキスト変数では、特定のメッセージをターゲットにできます。 これらは、変数名の「<
target
>」プレフィックスで示されます。「<
target
>」は、request、response、またはポリシー内でそのアサーションより前に設定されたメッセージ コンテキスト変数です。 メッセージ コンテキスト変数の詳細については、「コンテキスト変数のデータ型」を参照してください。
複数値のコンテキスト変数
以下で説明するすべてのコンテキスト変数は、一度に 1 つの値のみを保持できます。 ただし、任意の個数の値を持つことができる、「複数値のコンテキスト変数」と呼ばれる特殊なクラスの変数があります。 これらのコンテキスト変数は、Join Variable、Extract Attributes for Authenticated User、Listen Ports、または Query LDAP アサーションを使用して作成され、単一値のコンテキスト変数が使用されるところならどこでも使用できます。
コンテキスト変数が定義される場所
Layer7 API Gateway
には、一連の組み込みのコンテキスト変数があります。 また、多くのアサーションでは、ポリシーで使用されるときに独自のコンテキスト変数が定義されます。 これらの変数は、ポリシー ツリー内の後続のアサーションで使用できます。 これらの変数の詳細については、それぞれのアサーションのトピックを参照してください。
以下のトピックでも、特定のシナリオで使用されるコンテキスト変数について説明します。
  • XPath 用のコンテキスト変数
  • CA Single Sign-On 用のコンテキスト変数
  • デバッグ追跡ポリシーの使用
コンテキスト変数の命名規則
アサーションでユーザが新しいコンテキスト変数の名前を入力できる場合(システムで定義されている命名パターンを使用して作成するのではなく)、以下の命名規則に注意してください。
  • 最初の文字は、英字またはアンダースコア文字(_)のいずれかである必要があります。
  • 変数名の 2 番目の文字以降は、英字、数字、アンダースコア(_)、またはピリオド(.)の任意の組み合わせを使用できます。
  • ドル記号($)は予約文字であるため、名前には使用できません。
  • コンテキスト変数名は「request.」または「response.」で始めないでください。 これらの文字は、システムで使用するために予約されています。
  • マルチバイト文字は、コンテキスト変数名として現時点ではサポートされていません。
例:
  • 有効なコンテキスト変数名: _counter、request.url、layer7
  • 無効なコンテキスト変数名: ..request、7layer
コンテキスト変数のデータ型
コンテキスト変数では、技術的には任意のデータ型を扱うことができます。 コンテキスト変数は、数字や文字列から、添付ファイルおよびヘッダ付きのメッセージ全体まで、さまざまなデータを保持できます。 Policy Manager 内のアサーションでは、以下のデータ型で変数を作成できます。
  • String:
    この変数には、文字列が含まれます。 これは
    Layer7 API Gateway
    で最もよく使用されるデータ型です。 事前定義済みの変数のほとんどはこの型です。
  • Message:
    この変数には、添付ファイル付き(存在する場合)の完全なメッセージが含まれます。 メッセージのメイン/ルート MIME パートの本文に文字列としてアクセスするには、コンテキスト変数に「.mainpart」サフィックスを追加します。 「.mainpart」サフィックスの詳細については、「メッセージ レイヤのコンテキスト変数」を参照してください。
Message 型のコンテキスト変数は、Set Context Variable アサーションおよび Route via HTTP(S) アサーション(「Response Destination」フィールド)によって作成されます。 また、任意の組み込みの変数に「${request.*}」または「${response.*}」プレフィックスを付けて使用して、それらにアクセスすることもできます。
  • Number:
    この変数には、数字が含まれます。 これらの変数は、XPath アサーション(Evaluate Request XPath または Evaluate Response XPath)で「0.14 * //item/@price」などの XPath 式を評価する際に作成されます。 Number 型のコンテキスト変数は、ほとんどの場合に String 型として解釈できます。
  • X.509 Certificate:
    この変数には、1 つ以上の X.509 証明書が含まれます。 これらの変数は、(Non-SOAP) Verify XML Element および Look Up Certificates アサーションによって作成されます。 また、証明書認証情報変数でそれらにアクセスすることもできます。
  • Element:
    この変数には、メッセージの特定の XML 要素への参照が含まれます。 これらの変数は以下のアサーションで作成できます。
    • (Non-SOAP) Verify XML Element
    • (Non-SOAP) Decrypt XML Element
    • Evaluate Request XPath
    • Evaluate Response XPath
    • Require WS-Security Signature Credentials
  • AuditDetail
    および
    AuditRecord
    : これらの変数は、監査シンク ポリシー内で組み込みの変数 ${audit.*} を使用してアクセスされます。 詳細については、「監査シンク ポリシーの使用」を参照してください。
  • Date/Time:
    この変数には、日付/時刻情報が含まれます。 これらの変数は、「日付/時刻変数」で説明している組み込みの変数と同様に動作します。
カスタム アサーションまたはモジュール型アサーション(
Layer7 API Gateway
またはサードパーティが提供)によって作成されるコンテキスト変数は、上記以外のデータ型である可能性があります。
コンテキスト変数の検証
コンテキスト変数またはコンテキスト変数のプレフィックスを入力すると、Policy Manager は入力内容を検証し、即時フィードバック メッセージをダイアログ ボックスに表示します。 以下の表では、表示される可能性があるさまざまなメッセージについて説明します。
Validation
説明
OK
入力した名前は有効で、新しいコンテキスト変数が作成されます。
OK (Overwrite)
入力した名前は、このポリシー内の前のアサーションですでに定義されているコンテキスト変数に一致しています。 その変数が上書きされます。
OK (Built-in, settable)
入力した名前は、値を割り当てられる組み込みのコンテキスト変数に一致しています。
Built-in, not settable
入力した名前は、値を割り当てられない組み込みコンテキスト変数に一致しています。 別の名前を入力してください。
OK (New Prefix)
名前は有効で、新しいプレフィックスが作成されます。
Invalid syntax
フィールドが空のままか、または入力した名前に不正な文字が含まれています。 別の名前を入力してください。 詳細については、「コンテキスト変数の命名規則」を参照してください。
No such variable
指定した変数が存在しません。
このメッセージは、新しい変数を作成するのではなく、既存の変数を参照してその値を取得すると想定されている場合に使用されます。
コンテキスト変数の存在の確認
ポリシーでは、正しく分岐するために、コンテキスト変数が存在するかどうかの確認が必要な場合があります(たとえば、特定のヘッダまたはパラメータが存在するかどうかを確認する場合など)。 これを行うには、ポリシー ロジックの要件に応じて、以下の 2 つの方法があります。
方法 1: Look Up Context Variable アサーションを単独で使用する
以下は「
test
」という変数が存在するかどうかを確認する例です。
  1. 「All Assertions Must Evaluate to True」フォルダ内の最初のアイテムとして、Look Up Context Variable アサーションを追加します。
  2. Look Up Context Variable を以下のように設定します。
    • [Fail if not found]チェック ボックスをオンにします。
    • [Expression]フィールドに「test」と入力します。
このロジックを使用して、この変数が存在しない場合は分岐を行わないようにできます。
方法 2: Look Up Context Variable を Compare Expression と組み合わせて使用する
以下は「
test
」という変数が存在するかどうかを確認する例です。
  1. ポリシーの Compare Expression アサーションの前に Look Up Context Variable アサーションを追加します。
  2. Look Up Context Variable を以下のように設定します。
    [Fail if not found]チェック ボックスをオフにします。
    [Expression]フィールドに「test」と入力します。
  3. ${lookup.found}
    変数の値が true または false のどちらであるかを確認するように、Compare Expression アサーションを設定します。
詳細については、「Look Up Context Variable アサーション」を参照してください。