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 型の値として扱います- マルチバイト文字は利用できません
- KVSのユニークなキーです
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も最新の時刻で更新されます
Updated about 1 year ago