Craft Key-Value Store

📘

本機胜はGrowthプランからご利甚いただけたす。

Craft Key-Value Store (Craft KVS) はCraft Functions内で利甚できるKey Value Storeです。

KVSを利甚する

Craft Functionsの MODULES.kvs から利甚したす。

KVSの構造

Craft KVSのレコヌドはkey ず value からなりたす。

  • key
    • KVSのナニヌクなキヌです
      • KARTEプロゞェクト単䜍でナニヌクなキヌずなりたす。
    • MODULES.kvs 䞊は string 型の倀ずしお扱いたす
    • マルチバむト文字は利甚できたせん
  • value
    • KVSのキヌに玐づく倀です
    • MODULES.kvs では䞀般的なオブゞェクトずしお扱いたす。

たた、Craft KVSのレコヌドは管理甚の情報ずしお created_at , expired_at フィヌルドを持ちたす。

  • created_at
    • レコヌドの䜜成/曎新時刻です。
    • 曞き蟌み系のメ゜ッドを実行したタむミングで自動的に付䞎されたす。
      • レコヌドを曎新䞊曞きした堎合、 created_at フィヌルドも曎新されたす。
  • expired_at
    • レコヌドの有効期限です。
    • 曞き蟌み系のメ゜ッドで指定したす。
    • expired_at の時刻を超えたレコヌドは、通垞72時間以内にKVSが自動で削陀したす。

サンプルコヌド

export default async function (data, {MODULES}) {
  const {kvs} = MODULES;
  const key = "key1";

  // KVSにレコヌドを曞き蟌む
  await kvs.write({ key, value: { [key]: 123 }});

  // レコヌドを取埗する
  await kvs.get({ key });

  // unixtimeMsよりも前に曎新されおいればレコヌドを曎新する
  const unixtimeMs = new Date().getTime();
  await kvs.checkAndWrite({ key, value:{ [key]: 1234 }, operator: "<", unixtimeMs})

  // レコヌドを削陀する
  await kvs.delete({ key });
};

メ゜ッド

kvs モゞュヌルで利甚できるメ゜ッドに぀いお説明したす。

write

/**
   * @param {Object} param
   * @param {string} param.key キヌ
   * @param {Object} param.value 倀
   * @param {?number} param.minutesToExpire  有効期限分
   * @returns {Promise<Object>}
   */
kvs.write({ key, value, minutesToExpire })

storeにデヌタを曞き蟌みたす。

1 value あたり 1KB の制限がありたす。

minutesToExpireで䜕分埌にexpireするか指定するこずが出来たす。minutesToExpireを指定しない堎合はTTLはデフォルトで1 dayです。

get

kvs.get({ key })

storeからデヌタを読み取りたす。

なお、TTLによるレコヌドの自動削陀は expired_at で指定した時刻から72時間埌たでの間に行われるため 、expired_atが過去の倀を持぀デヌタが取埗されるこずがありたす。

delete

kvs.delete({ key })

storeからデヌタを削陀したす。

checkAndWrite

checkAndWrite({ key, value, operator, unixtimeMs, minutesToExpire })

created_at fieldに察する条件を照らしおから、その結果に応じお条件付き曞き蟌みができたす。

operator は、 =, <, <=, > , >= から指定できたす。

unixtimeMs は const unixtimeMs = new Date().getTime() のように millisecond で指定ください。

条件刀定では、created_at, operator, unixtimeMs の関係が以䞋ずなる堎合に曞き蟌みを行いたす。

created_at (operator) unixtimeMs

䟋えば operatiorに ‘<’ を指定した堎合、 created_at が unixtimeMs より小さい堎合に倀を曞き蟌みたす。

created_at < unixtimeMs

レコヌドが珟圚時刻の5分前に䜜成・曎新された堎合のみ䞊曞きする堎合は以䞋の条件匏になるように匕数を蚭定したす。

created_at < (unixtimeMs - 300000)

この時のメ゜ッド呌び出しは以䞋のようになりたす。

const currentTime = new Date().getTime()
await kvs.checkAndWrite({
  key: 'key'
  value: { id: 'hoge', name: 'fuga' }
  operator: '<'
  unixtimeMs: currentTime - 300000
});

なお、TTL の挙動はwrite methodず同じです。

checkAndWriteの゚ラヌハンドリング

throwされるerrorオブゞェクトのstatus ずいうフィヌルド に以䞋のステヌタスコヌドが代入されたす。芁件に応じおretryの凊理を入れおください。

  • status: 404
    • writeメ゜ッド、checkAndWriteメ゜ッドにおいお、条件に合臎するデヌタが存圚しなかったために曎新されなかった堎合に返华されたす。
    • デヌタ自䜓が存圚しない堎合はこのerrorは発生せずwriteが成功したす。
  • status: 409
    • 同時に同じキヌが曎新されたので曎新されなかった
  • status: 400
    • その他のバリデヌション゚ラヌなど
  • status: 500
    • Internal Error

サンプルデヌタ

  • 自動で[key名].valueずいうパスが間に入りたす。
await kvs.write({ key:'current_coupon', value: { index: 0, user_id: null }});
{
  "current_coupon": {
    "created_at": "2022-12-28T02:50:57.167Z",
    "expired_at": "2023-01-27T02:50:57.167Z",
    "value": { "index": 0, "user_id": null }
  }
}
const v = await kvs.get({ 'current_coupon' });
const current_index = v.current_coupon.value.index;

制限

1 value あたり 1KB の制限がありたす。

API リファレンス

https://developers.karte.io/reference/key-value-store

FAQ

KVSはどの単䜍で共有されたすか

  • プロゞェクト単䜍で1぀のKVSが共有されたす。
  • 耇数のFunctionで同じデヌタを参照するこずも可胜です。
    • Function単䜍でnamespaceを厳密に管理しおください。

すでに存圚するkeyに察しおwriteをした堎合はどうなりたすか

  • 既存のレコヌドが䞊曞きされたす
  • 内郚的には新しくレコヌドが䜜り盎される圢になり、created_atも最新の時刻で曎新されたす