Node.js でのキャッシュへのアクセス

非推奨の機能: Apigee Edge Cloud で、従来の Trireme ベースの Node.js サポートは廃止済みになりました。拡張機能の apigee-access も廃止済みになりました。この拡張機能は、Apigee Edge にデプロイされた Trireme ベースの Node.js アプリケーションでのみ使用されています。Trireme ベースの Node.js は 2019 年 10 月 10 日に廃止されました。詳しくは、Trireme ベースの Node.js のサポート終了をご覧ください。

Apigee Cloud を使用している場合、新しい Node.js の開発および Apigee Edge へのデプロイには、Hosted Targets を使用することをおすすめします。Apigee の従来の Node.js デプロイ手法を使用する既存の API プロキシの移行については、既存の Node.js プロキシの Hosted Targets プロキシへの移行をご覧ください。

apigee-access の不備は回避できますかもご覧ください。

apigee-access モジュールを使用すると、Node.js アプリケーション内から Edge 分散キャッシュにアクセスできます。このモジュールには、キャッシュの取得やデータの挿入、取得、削除に使用するメソッドが含まれています。

Apigee Edge 分散キャッシュには、文字列などのデータを保存できます。この分散キャッシュは一般的なキャッシュと同様、最も長く使用されていないデータから破棄されるキャッシュ（LRU キャッシュ）で、サイズに上限があります。Apigee Edge では、Node.js アプリケーションが実行されるすべてのノードにキャッシュが分散されます。キャッシュは Apigee Edge API を使用して管理できます。この API を使用すると、キャッシュリソースを手動で作成したり、デフォルトリソースを使用したりできます。Apigee Edge でのキャッシュ処理の概要については、Edge の永続性ツールをご覧ください。分散キャッシュの詳細については、例: 汎用キャッシュの使用をご覧ください。

apigee-access モジュールの概要と、このモジュールのその他の機能については、apigee-access モジュールの使用をご覧ください。

メソッド

（1）getCache
（2）getCache
put
get
remove

（1）getCache

var
  cache = apigee.getCache(cacheName);

名前付きキャッシュを参照し、必要があれば作成します。作成されるキャッシュには、一般的な状況に適した定義済みの構成パラメータセットが使用されます。

パラメータ:

cacheName - 文字列。キャッシュの名前（キャッシュリソースの名前ではありません）。

戻り値:

キャッシュオブジェクト。

例:

var apigee = require('apigee-access');
var cache = apigee.getCache('cache');

（2）getCache

var
  customCache = apigee.getCache(cacheName, options );

構成オブジェクトに指定されているカスタムキャッシュリソースにアクセスします。キャッシュリソースの作成方法の詳細については、環境用のキャッシュの管理をご覧ください。

パラメータ:

cacheName - 文字列。カスタムキャッシュの名前（キャッシュリソースの名前ではありません）。

options - 構成オブジェクト。空のオブジェクトでも構いません。または、以下の省略可能なパラメータを指定できます。

resource: キャッシュデータを格納する Apigee キャッシュリソースの名前。キャッシュリソースは、メモリ割り当てなどのキャッシュパラメータの微調整に使用されます。指定がない場合は、デフォルトのリソースが使用されます。キャッシュリソースが存在しない場合、メソッドからエラーがスローされます。
scope: 競合を防ぐためにキャッシュエントリに接頭辞を付けるかどうかを指定します。有効な値は global、application、exclusive です。
- global: 同じ Apigee「環境」内にあるすべての Node.js アプリケーションが全キャッシュエントリを見ることができます。
- application: 同じ Apigee Edge アプリケーションの一部であるすべての Node.js アプリケーションが全キャッシュエントリを見ることができます。
- exclusive: （デフォルト）同じ名前を持つ同じアプリケーション内の Node.js キャッシュだけがキャッシュエントリを見ることができます。これがデフォルトです。
prefix: Populate Cache ポリシーとキャッシュキーの使用で説明されているように、キャッシュキー名に接頭辞が含まれている場合は、このパラメータを使用して接頭辞を指定します。Edge は、接頭辞名の末尾に 2 つのアンダースコアを自動的に追加します。たとえば、キャッシュキーが UserToken という接頭辞付きで作成されている場合、ここで指定する接頭辞は UserToken__ になります。
defaultTtl: キャッシュエントリの有効期間を秒単位で指定します。指定しない場合、キャッシュリソースのデフォルトの TTL が使用されます。
timeout: 分散キャッシュから結果をフェッチするまでの待機時間を秒単位で指定します。デフォルトは 30 秒です。レイテンシの影響を受けやすいアプリケーションでは、キャッシュインフラストラクチャの負荷が高いときにレスポンスが遅くならないようにするため、この値を小さくするのが望ましい場合があります。

戻り値:

カスタムキャッシュオブジェクト。

例:

var apigee = require('apigee-access');
var customCache = apigee.getCache('doesNotMatter',
  { resource: 'MyCustomResource', scope: 'global', prefix: 'UserToken'} );
customCache.put("myCacheKey", "xyz");

次のような LookupCache ポリシーと一緒に使用します。

<LookupCache name="Lookup-Cache-1">
  <CacheKey>
    <Prefix>UserToken</prefix>
    <KeyFragment>myCacheKey</KeyFragment>
  </CacheKey>
  <CacheResource>MyCustomResource</CacheResource>
  <Scope>Global</Scope>
  <AssignTo>contextVariable</AssignTo>
</LookupCache>

put

cache.put('key',
  data, ttl, function(error));

データをキャッシュに挿入します。

パラメータ:

key: （必須）キャッシュ内のアイテムを一意に識別する文字列。キャッシュキーのサイズは 2 KB に制限されています。
data: （必須）キャッシュに保存するデータを表す文字列、バッファまたはオブジェクト。これ以外のデータ型はエラーになります。便宜上、オブジェクトは JSON.stringify で文字列に変換されます。
ttl: （省略可）キャッシュ内にデータを保存する最長時間（秒単位）。指定がない場合は、デフォルトの TTL が使用されます。
callback: （省略可）データがキャッシュに安全に保存された後に呼び出される関数を指定します。挿入エラーがあった場合、最初のパラメータとして Error オブジェクトが指定された状態で呼び出されます。それ以外の場合は、パラメータなしで呼び出されます。

例:

var apigee = require('apigee-access');
var cache = apigee.getCache();
// Insert a string into cache using the default TTL
cache.put('key1', 'Buenos dias, Mundo!');
// Insert a string into cache using a TTL of 120 seconds
cache.put('key2', 'Hello, World!', 120);
// Insert a string with the default TTL, and get notified when the insert is complete
cache.put('key3', 'Ciao, Mondo!', function(error) {
  // "error" will be falsy unless there was an error on insert
});
// Insert a string with a TTL of 600 seconds, and get notified when the insert is complete
cache.put('key4', 'Hallo Wereld!', 600, function(error) {
  // "error" will be falsy unless there was an error on insert
});

get

cache.get('key',
  function(error, data));

キャッシュからデータを取得します。

パラメータ:

key（必須）: キャッシュ内のアイテムを一意に識別する文字列。

Apigee Edge ポリシー（Populate Cache ポリシーなど）からキャッシュに挿入されるキャッシュエントリに対しては、ポリシーがエントリ用のキーを作成する具体的なやり方から類推してキャッシュキーを作成する必要があります。そのためには、ポリシーがどのように構成されているかを知る必要があります。キャッシュキーがポリシーによってどのように作成されるかについては、キャッシュキーの使用で説明しています。ここで、スコープに関連する文字列を指定しないように注意してください。Node.js からの呼び出しにおいて、スコープはすでにコンテキストの一部になっています。
callback（必須）: データが使用可能な場合に呼び出される関数。キャッシュされているデータが存在する場合、2 番目のパラメータで返されます。
- error - エラーオブジェクト。キャッシュからの取得中にエラーが発生した場合は、ここに Error オブジェクトがセットされます。それ以外の場合、このパラメータは「未定義値」にセットされます。
- data - 取得されたデータがある場合はそのデータ。以下に示す 4 つの値のどれかです。
  - 文字列が挿入されていた場合は文字列です。
  - Buffer が挿入されていた場合は Buffer です。
  - オブジェクトが挿入されていた場合は、JSON.stringify によって生成された JSON バージョンのオブジェクトを含む文字列です。
  - 何もない場合は undefined になります。

例:

var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.get('key', function(error, data) {
  // If there was an error, then "error" will be set.
  // If error is falsy, "data" is the item that was retrieved:
  //   - undefined, in the case of cache miss, or
  //   - a Buffer, or
  //   - a String
});

remove

cache.remove('key', function(error));

キャッシュアイテムを無効にします。キーを無効にすると、他の値が挿入されない限り、その後の get() リクエストでは undefined が返されます。

パラメータ:

key（必須）: キャッシュ内で無効にするアイテムを一意に識別する文字列。

Apigee Edge ポリシー（Populate Cache ポリシーなど）からキャッシュに挿入されるキャッシュエントリに対しては、ポリシーがエントリ用のキーを作成する具体的なやり方から類推してキャッシュキーを作成する必要があります。そのためには、ポリシーがどのように構成されているかを知る必要があります。キャッシュキーがポリシーによってどのように作成されるかについては、キャッシュキーの使用で説明しています。ここで、スコープに関連する文字列を指定しないように注意してください。Node.js からの呼び出しにおいて、スコープはすでにコンテキストの一部になっています。
callback（必須）: エラーが発生した場合に、Error オブジェクトで最初のパラメータとして呼び出されるコールバック関数。

例:

var apigee = require('apigee-access');
var cache = apigee.getCache();
cache.remove('key', function(error) {
});