在 Node.js 中存取快取

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

您可以使用 apigee-access 模組，從 Node.js 應用程式內存取 Edge 分散式快取。此模組包含取得快取、計算、取得和移除資料的方法。

Apigee Edge 分散式快取可讓您儲存字串或其他資料。就像大多數快取一樣，是最近使用且有大小上限的快取。在 Apigee Edge 中，快取會分配至執行 Node.js 應用程式的所有節點。您可以透過 Apigee Edge API 管理快取。您可以使用 API 手動建立快取資源，也可以使用預設資源。如需 Apigee Edge 快取的簡介，請參閱 Edge 中的永久工具。如要進一步瞭解分散式快取，請參閱範例：一般用途快取。

如需 apigee-access 模組及其其他功能的簡介，請參閱使用 apigee-access 模組。

方法

(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：如果快取金鑰名稱包含前置字串 (如「填入快取政策」和「使用快取金鑰」一節所述)，請使用此參數指定前置字串。邊緣會自動在前置字串名稱中加入雙底線後置字串。因此，如果快取金鑰的前置字串是「UserToken」，這裡指定的前置字串是「UserToken__」。

  • defaultTtl：指定快取項目的預設存留時間 (以秒為單位)。如未指定，系統會使用快取資源中的預設存留時間。

  • 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>

放置

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

將資料放入快取。

參數：

  • key：(必要) 用來識別快取中特定項目的字串。快取金鑰的大小上限為 2 KB。

  • data：(必要) 代表要快取的資料的字串、緩衝區或物件。任何其他資料類型都會導致錯誤。為方便起見，系統會使用「JSON.stringify」將物件轉換為字串。

  • 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
});

取得

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

從快取擷取資料。

參數：

  • key (必要)：用來識別快取中特定項目的字串。

    如為由 Apigee Edge 政策將快取項目放入快取 (例如「填入快取政策」)，您必須透過政策建立項目金鑰的特定方式推斷，藉此建構快取金鑰。如要做到這點，您需要瞭解這項政策的設定方式。雖然使用快取金鑰也說明瞭快取金鑰透過政策建立的方式，但請注意，請勿指定與範圍相關的字串值；在透過 Node.js 的呼叫中，範圍已是結構定義的一部分。

  • callback (必要)：有資料可用時，系統會呼叫的函式。如果有快取資料，則會在第二個參數中傳回。

    • error - 錯誤物件。如果從快取擷取時發生錯誤，系統就會在這裡設定 Error 物件。否則，此參數會設為「未定義」。

    • data - 擷取的資料 (如果有的話)。這會是以下四種值的其中一種：

      • 如果插入字串，該字串會是字串。
      • 如果插入緩衝區，緩衝區會呈現緩衝區。
      • 如果插入物件，該物件就會是包含「JSON.stringify」所產生物件 JSON 版本的字串。
      • 如果找不到，則會是「未定義」。

範例：

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

移除

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

撤銷快取項目。一旦金鑰失效，除非已插入其他值，否則後續的 get() 要求會傳回「未定義」。

參數：

  • key (必要)：這個字串專門用於識別快取中要撤銷的項目。

    如為由 Apigee Edge 政策將快取項目放入快取 (例如「填入快取政策」)，您必須透過政策建立項目金鑰的特定方式推斷，藉此建構快取金鑰。如要做到這點，您需要瞭解這項政策的設定方式。雖然使用快取金鑰也說明瞭快取金鑰透過政策建立的方式，但請注意，請勿指定與範圍相關的字串值；在透過 Node.js 的呼叫中，範圍已是結構定義的一部分。

  • callback (必要)：發生錯誤時，系統會使用 Error 物件呼叫的回呼函式，做為第一個參數。

範例：

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