Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

フロー変数について

このトピックで説明する内容

この概要トピックでは、Apigee Edge API プロキシでフロー変数にアクセスする方法、およびその使い方について説明します。このトピックを読むと、次の内容の理解が深まります。

  • フロー変数とは何か
  • フロー変数が作成されるタイミングと場所
  • フロー変数の参照方法
  • フロー変数の範囲とデータ型
  • ポリシーでフロー変数にアクセスする方法
  • フロー変数 JavaScript および Node.js コードへのアクセス方法
  • カスタムフロー変数の作成方法

コードサンプルを直接参考にしたい場合、GitHub にある多くの API プロキシサンプルでは、フロー変数が使用されています。詳細については、以下の「関連コードサンプル」を参照してください。

Watch this video for an introduction to flow variables.

フロー変数とは

フロー変数とは、名前が付けられた一種の参照であり、Apigee Edge で処理される API トランザクションと関連付けられた状態を保持します。これらの変数は、API プロキシフローの内容に含まれ、名前が付けられた変数がソフトウェアプログラム内で状態を追跡する場合と同じ方法で、API トランザクション内の状態を追跡します。フロー変数に格納される情報:

  • IP アドレス、ヘッダー、URL パス、および要求元アプリから送信されるペイロード
  • Edge がリクエストを受信した日時などのシステム情報
  • ポリシー実行時に派生したデータ。例えば、OAuth トークンを検証するポリシーを実行した後、Edge は要求元アプリケーションの名前などの情報を保持するフロー変数を作成します。
  • ターゲットシステムからのレスポンスに関する情報

一部の変数は Edge の「組み込み」変数になっており、API リクエストの受信時に常に値が自動的に入力されます。これらの変数は、API トランザクション全体を通じて利用できます。また AssignMessage などのポリシー、あるいは JavaScript、Node.js、Java コードなどを使用して、独自のカスタム変数を作成できます。言うまでもなく変数には範囲があり、アクセスできる場所は、ある程度、API プロキシフローで作成されたタイミングに応じて異なります。一般的に、変数が作成されると、API トランザクションフローで後で実行するポリシーとコードが、この変数にアクセスできるようになります。

フロー変数の使い方

フロー変数はポリシーおよび条件付きフローで使用します。ポリシーは、フロー変数から状態を取得して、これらの情報に基づいて処理を実行できます。例えば、VerifyAccessToken ポリシーは、フロー変数から検証すべきトークンを取得して、このトークンで検証を実行できます。別の例としては、JavaScript コールはフロー変数を取得して、これらの変数に含まれているデータをエンコードできます。条件付きフローでは、プログラミングで switch ステートメントを使用する場合と似た方法で、フロー変数を参照して API のフローを Edge 経由に誘導することができます。例えば、障害を返すポリシーは、特定のフロー変数が設定された場合のみ実行することができます。最後に、Node.js ターゲットアプリケーションでは、フロー変数の取得と設定を実行できます。 

以下のそれぞれの状況で、変数がどのように使用されるか、例を見てみましょう。

ポリシーでのフロー変数

一部のポリシーは、入力としてフロー変数を取得します。例えば、以下の AssignMessage ポリシーは、フロー変数値 client.ip を取得して、My-Client-IP というリクエストヘッダーに埋め込みます。リクエストフローに追加される場合、このポリシーはバックエンドターゲットに渡されるヘッダーを設定します。レスポンスフローで設定される場合、ヘッダーはクライアントアプリに返送されます。

<AssignMessage name="set-ip-in-header">
<AssignTo createNew="false" transport="http" type="request">request</AssignTo>
 <Set>
 <Headers>
 Header name="My-Client-IP">{client.ip}</Header>
 </Headers> 
</Set>
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

もう 1 つの例では、Quota ポリシーの実行時に、一部のフロー変数にポリシー関連値が入力されます。これらの変数の 1 つは、ratelimit.my-quota-policy.used.count という変数です。my-quota-policy は、使用するクォータポリシーの名前です。「現在のクォータカウントが最大値の 50 %を下回っており、午前 9 時から午後 5 時までの間であれば、異なるクォータを適用する」という条件付きフローを後で実行できます。この条件は、現在のクォータカウントの値と system.time というフロー変数 (これは組み込み Edge 変数の 1 つ) に基づいています。

条件付きフローでのフロー変数

条件付きフローは、フロー変数を評価して、プロキシが動的に機能性できるようにします。条件は、一般的にフロー、ステップ、ルートルールの動作を変更するために使用されます。ここでは、プロキシフローステップで変数 request.verb の値を評価する条件付きフローについて説明します。この例でリクエスト動詞が POST である場合、VerifyApiKey ポリシーが実行されます。これは API プロキシ設定で使用される一般的なパターンです。

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

ここで疑問に思われるかもしれませんが、request.verbclient.ipsystem.timeなどの変数はどこから来たのでしょうか? これらの変数はいつインスタンス化され、値が入力されるのでしょうか? 変数が作成されるタイミング、利用可能になるタイミングに関して理解を深められるように、以降で変数の範囲について説明します。

JavaScript ポリシーで呼び出される JavaScript コードでのフロー変数

JavaScript ポリシーを使用すると、API プロキシフローの処理中に JavaScript コードを実行できます。このポリシーで実行される JavaScript は、Apigee JavaScript オブジェクトモデルを使用します。このモデルは、リクエスト、レスポンス、コード実行中の API プロキシフローと関連付けられたコンテキストオブジェクトに対して、カスタムコードアクセスを提供します。例えば、このコードは、フロー変数 target.name から取得した値でレスポンスヘッダーを設定します。

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

変数の読み取りと設定に JavaScript を使用するこの方法は、AssignMessage ポリシーで実行できる前述の方法と似ています。これは、同じ種類の処理を Edge で実行する 1 つの方法です。注目すべき点は、JavaScript ポリシーで実行される JavaScript は、存在していて、API プロキシフローの範囲内にあるすべてのフロー変数にアクセスできることです。

Node.js コードでのフロー変数

apigee-access モジュールを要求することで、Edge に展開された Node.js コード内から、 フロー変数の設定とアクセスを実行できます。

ここでは、custom.foo という変数を値 Bar に設定する簡単な例について説明します。一度設定すると、この新しい変数は、Node.js コードの実行後に、プロキシフローに出現する任意のポリシー、その他のコードで利用できます。

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

変数を操作するために apigee-access を使用する方法については、「Node.js アプリケーションでフロー変数にアクセスする」で確認することができます。

フロー変数の範囲について

変数の範囲は、フローまたは API プロキシコールの「ライフサイクル」全体に関連しています。

API プロキシのフローを可視化する

To understand flow variable scope, it's important to understand or visualize the way messages flow through an API proxy. An API proxy consists of a series of message processing steps organized as a flow. At every step in a proxy flow, the proxy evaluates information available to it and decides what to do next. Along the way, the proxy may execute policy code or perform conditional branching.

次の図では、この一連のフローを示します。フローは、ProxyEndpoint リクエスト、TargetEndpoint リクエスト、TargetEndpoint レスポンス、ProxyEndpoint レスポンスという 4 つの主要なセグメントで構成されていることに注目してください。 

このトピックの後半では、このフロー構造を念頭に置いてフロー変数について見ていきましょう。

プロキシフロー構造の詳細を確認するには、「フローの構成」を参照してください。

変数の範囲とプロキシフローが関連している仕組み

前述のように、プロキシ経由でメッセージが転送される仕組みを可視化すると、変数の範囲も理解しやすくなります。範囲という概念は、プロキシフローのライフサイクル中で、まず変数がインスタンス化されている時間を表しています。例えば、ポリシーが ProxyEndpoint リクエストセグメントに接続されている場合、このポリシーは、範囲が TargetEndpoint リクエストセグメントに設定されている変数にはアクセスできなくなります。この理由は、フローの TargetEndpoint リクエストセグメントがまだ実行されていないため、API プロキシがこの範囲に変数を格納する機会に至っていないからです。

次の表にそれぞれの変数の範囲を示して、プロキシフロー内でこれらが利用可能になるタイミングについて説明します。

特定の範囲でフロー変数が入力されると、その変数はプロキシフローのライフサイクルでそれ以降利用可能になります。範囲にまだ存在していない変数にアクセスしようとすると、エラーまたは NULL 値を受信することになります。

変数の範囲 これらの変数が入力される場所
プロキシリクエスト ProxyEndpoint リクエストセグメント
ターゲットリクエスト TargetEndpoint リクエストセグメント
ターゲットレスポンス TargetEndpoint レスポンスセグメント
プロキシレスポンス ProxyEndpoint レスポンスセグメント
常に利用可能 プロキシがリクエストを受信した時点。これらの変数は、プロキシフローのライフサイクル全体で利用可能です。

例えば、client.ip という組み込みの Edge 変数があります。この変数には「プロキシリクエスト」の範囲が適用されます。この変数には、プロキシを呼び出したクライアントの IP アドレスが自動的に入力されます。リクエストが最初に ProxyEndpoint をヒットした時点で値が入力され、プロキシフローのライフサイクル全体で値が利用可能になります。

すべての組み込み Edge 変数の範囲が、「変数リファレンス」に記載されています。

他に、target.url という組み込み変数があります。この変数の範囲は「ターゲットリクエスト」です。この変数には、TargetEndpoint リクエストセグメントで、バックエンドターゲットに送信されたリクエスト URL が値として入力されます。ProxyEndpoint リクエストセグメントで target.url にアクセスしようとすると、NULL 値を受信することになります。範囲に至る前にこの変数を設定しようとしても、プロキシは何も実行しません。つまり、エラーは生成されず、変数は設定されません。 

未定義の変数にアクセスされた場合に、エラーを送信する、あるいは NULL 値を返すように、ポリシーを設定することは可能です。詳細については、個々のポリシーの参照ページを参照してください。

ここでは、変数の範囲をどのように考えるべきか、簡単な例で説明していきます。リクエストオブジェクト (ヘッダー、パラメータ、本文) の内容全体をコピーして、呼び出し元アプリに返信すべきレスポンスペイロードに割り当てると仮定します。このタスクには AssignMessage ポリシーを使用できます。ポリシーコードは次のようになります。

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

このポリシーは、リクエストオブジェクトを単純にコピーして、レスポンスオブジェクトに割り当てています。ただし、プロキシフロー内でこのポリシーはどこに配置すべきでしょうか? レスポンス変数の範囲が「ターゲットレスポンス」であるため、答えとしては TargetEndpoint レスポンスに配置する必要があります。

フロー変数の参照

Apigee Edge のすべての組み込み変数は、ドット表記の命名規則に従っています。この規則では、変数の目的をより簡単に明示することができます。例えば、system.time.hourrequest.content などです。

このドット表記の規則は、命名の目的に厳格に従っています。例えば、request.content が、「request」という名前の親変数やオブジェクトを参照することはありません。カスタム変数には、任意の名前を付けることができます。必ずしもドットを含める必要はありません。独自のカスタムフロー変数を作成する場合は、この命名規則に従うことがベストプラクティスであると Apigee は認識しています。ドットを利用して、カスタム変数を整理すると便利です。例えば、approval.code および approval.status は、両方ともフロー内の承認 (approval) 機能を指しているからです。Apigee は、request、target、system、response などをプレフィックスとして使用して、関連する変数を適切に整理しています。

ポリシーで変数を参照する場合、中かっこで変数を囲む必要があります。例えば、この簡単な AssignMessage ポリシーは、変数値 client.ip を取得して、Client-IP というリクエストヘッダーに埋め込みます。

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

条件付きフローでは、中かっこは必要ありません。例えば、この条件は変数 request.header.accept を評価します。

<Step>   
    <Condition>request.header.accept = "application/json"</Condition>   
    <Name>XMLToJSON</Name> 
</Step>

また JavaScript および Java コードでもフロー変数を参照できます。詳細については、このトピックの後半で「JavaScript での変数の操作」を参照してください。また「Node.js アプリケーションでフロー変数にアクセスする」も参照してください。

フロー変数のデータ型

フロー変数には、string、long、integer、boolean、collection など、詳細に定義されたデータ型があります。「変数リファレンス」では、組み込み Edge フロー変数ごとに、リストされたデータ型を確認できます。ポリシーで作成される変数については、データ型の情報が記載された特定のポリシー参照トピックを参照してください。最後に、手動で作成する変数は、作成時に指定されたデータ型を継承します。またデータ型は、使用可能な値のタイプに基づいて決定されます。例えば、Node.js コードで作成される変数は、number、String、boolean、null、または undefined に制限されます。

ポリシーでのフロー変数の使用

多くのポリシーは、通常の実行の一環としてフロー変数を作成します。「ポリシーリファレンス」には、これらのポリシー固有の変数がすべて記載されています。プロキシとポリシーを操作する場合は、「ポリシーリファレンス」を参照して、作成される変数と使用される目的を必ず確認してください。例えば、Quota ポリシーでは複数の変数が作成され、クォータカウント、制限事項、有効時間などの情報が格納されます。詳細なリストについては、「ポリシー固有の変数」セクション (Quota ポリシーの) を参照してください。一部のポリシー変数はデバッグに役立ちます。例えば、トレースツールを使用して、プロキシフロー内の特定のインスタンスで何の変数が設定されたかを確認できます。

ExtractVariables ポリシーでは、メッセージから取得したデータをカスタム変数に入力できます。クエリーパラメータ、ヘッダー、およびその他のデータを取得できます。例えば、特定のデータをメッセージから取得するために、パターンを使用してリクエストおよびレスポンスメッセージを解析できます。

次の例では、レスポンスメッセージの解析、およびレスポンスから取得した特定データの格納に ExtractVariables が使用されています。2 つのカスタム変数が作成され、値が割り当てられます。変数は geocoderesponse.latitudegeocoderesponse.longitude です。

<ExtractVariables name="ParseGeocodingResponse"> 
  <Source>response</Source> 
  <VariablePrefix>geocoderesponse</VariablePrefix> 
  <JSONPayload> 
    <Variable name="latitude"> 
      <JSONPath>$.results[0].geometry.location.lat</JSONPath> 
    </Variable> 
    <Variable name="longitude"> 
      <JSONPath>$.results[0].geometry.location.lng</JSONPath> 
    </Variable> 
  </JSONPayload> 
</ExtractVariables>

ここでもう一度、多くのポリシーが自動的に変数を作成することに注目してください。これらの変数は、プロキシフローのコンテキストでアクセスできます。また、これらの変数については、「ポリシーリファレンス」において、それぞれ個別のポリシートピックで報が提供されています。

JavaScript コードでのフロー変数の操作

API プロキシのコンテキストで実行している JavaScript コードでは、直接的に変数へのアクセスと設定を実行できます。Apigee JavaScript オブジェクトモデルでは、Edge 上で実行中の JavaScript は、プロキシフローの変数に直接アクセスできます。

JavaScript ポリシーを使用してプロキシから JavaScript を呼び出すことができます。詳細については、「JavaScript ポリシー」を参照してください。

JavaScript コードで変数にアクセスするには、以下のオブジェクトのいずれかで getter/setter メソッドを呼び出します。

  • proxyRequest
  • targetRequest
  • targetResponse
  • proxyResponse
  • context

すでにお気づきでしょうが、これらのオブジェクト参照は、「API プロキシのフローを可視化する」で前述したプロキシフローモデルのセグメントに対応しています。

context オブジェクトは、システム変数など、「グローバルに」利用できる変数に対応しています。例えば、context オブジェクトで getVariable() を呼び出して現在の年を取得できます。

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

同様に setVariable() を呼び出して、カスタム変数の値を設定したり、書き込み可能な標準変数の値を設定したりできます。ここでは、organization.name.myorg というカスタム変数を作成して、値をこの変数に割り当てます。

var org = context.setVariable('organization.name.myorg', value);

この変数は context オブジェクトで作成されるため、すべてのフローセグメントで使用することができます。基本的にこれはグローバル変数の作成に似ています。

「変数リファレンス」は、書き込み可能な変数、読み取り専用の変数について説明しています。「変数リファレンス」を参照してください。JavaScript オブジェクトモデルの詳細については、「JavaScript オブジェクトモデル」を参照してください。

また JavaCallout ポリシーで実行する Java コードでは、プロキシフロー変数の取得/設定を実行できます。詳細については、「Java Callout ポリシー」を参照してください。

Node.js アプリケーションでフロー変数にアクセスする

Edge に導入された Node.js コードから、フロー変数の取得、設定、および削除を実行できます。必要な操作は、コードで apigee-access モジュールを「require」することだけです。詳細については、「Node.js アプリケーションでフロー変数にアクセスする」を参照してください。

留意事項

フロー変数に関して、ここでは重要な留意事項をいくつか説明します。

  • 一部の「標準」変数は、プロキシ自体により自動的にインスタンス化され、値が入力されます。これらは「変数リファレンス」で説明しています。
  • プロキシフローで利用可能なカスタム変数を作成できます。AssignMessage や JavaScript などのポリシー、Node.js コードで変数を作成できます。 
  • 変数には範囲があります。例えば、最初のプロキシがアプリからリクエストを受信すると、一部の変数には自動的に値が入力されます。その他の変数には、プロキシのレスポンスフローセグメントで値が入力されます。これらのレスポンス変数は、レスポンスセグメントの実行まで未定義の状態に保たれます。
  • ポリシーを実行すると、ポリシー固有の変数が作成され、値が入力されます。各ポリシーのドキュメントには、関連するポリシー固有の変数がすべてリストされます。   
  • 条件付きフローは、一般的に 1 つ以上の変数を評価します。条件付きフローを作成する場合は、変数への理解を深める必要があります。  
  • 多くのポリシーは、入力または出力として変数を使用します。一般的に、あるポリシーで作成される変数は、後で別のポリシーによって利用されます。 
  • Edge で実行している Node.js、純正の JavaScript、または Java コードでは、多くのフロー変数を取得および設定することができます。

関連コードサンプル

API プロキシサンプルは GitHub にあり、簡単にダウンロードして利用できます。サンプルのダウンロードと使い方については、「サンプル API プロキシの使用」を参照してください。API プロキシサンプルの説明と機能については、「サンプルリファレンス」を参照してください。

変数の使用と変数の処理を特長とするサンプルプロキシ:

  • variables - 転送、JSON、XML メッセージのコンテンツに基づいて変数を取得、設定する方法について説明します。
  • policy-mashup-cookbook - ポリシーの作成機能を使用する完成度の高いアプリケーションです。2 つのパブリック API を呼び出し、処理結果を結合して、クライアントアプリ向けに詳細なレスポンスを生成します。このサンプルの詳細については、「ポリシー作成機能の使用」を参照してください。
  • conditional-policy - 変数値に基づいて、簡単な条件付きポリシーを適用できます。

何らかの方法で変数を使用するサンプルは、その他にもいくつか用意されています。ExtractVariables ポリシーを使用するサンプルを見つけてください。このサンプルは、プロキシフローで変数を処理するためによく利用されています。

関連トピック

  • API プロキシに値が自動的に入力される変数はすべて「変数リファレンス」にリストされています。またこのリファレンスには、各変数のタイプと範囲もリストされます。
  • 特定のポリシーで値が入力される変数を確認する場合は、ポリシーのリファレンストピックを参照してください。例えば、「Quota ポリシー」と「ポリシー固有の変数」セクションを参照してください。

 

Help or comments?