関数からキーバリューと SQL ストレージを使う
distribution ごとに、その 関数ランタイム だけが使えるストアが 2 つあります。
- キーバリュー(
env.kv) — キーごとの文字列値。同時書き込みを安全にするバージョン、 有効期限、カウンターを備えます。セッション、レート制限、投票数、フラグに向いています。 - SQL(
env.sql) — distribution ごとに 1 つの SQLite データベース。問い合わせたい データ(申し込み、コメント、注文、小さな CRM)に向いています。
訪問者はどちらのストアにも直接は届きません。訪問者が /_api エンドポイントを呼び、関数が 動き、関数がストアを読み書きします。このページの操作は、公開中のサイトのファイルや deployment を変えません。
アクセスは distribution の ストア付与 で決まり、関数ソースの外で設定します。handler から 付与を作成・変更・迂回することはできません。ストア付与、キー、SQL は Web コンソールではまだ 管理できません。エージェント、CLI、または API を使ってください。関数の作成と実行はエージェントのままです。
このページは、ビルド済みの関数ランタイムが 1 つ以上ある distribution を前提にしています。 まだない場合は エンドポイントを追加する から始めてください。 例の distribution は acme-marketing(d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38)、handler の スクリプトは 01JBQZ8XKT4A9WN2CDEFGH5RM7 です。
1. 関数にストアを許可する
ストア(kv または sql)と mode(read または read-write)を選びます。スクリプトを 指定して個別に read / write を与えることもできます。指定しなければ distribution のすべての 関数が mode のアクセスを得ます。mode none は付与を外し、データは残します。
acme-marketing で、すべての関数にキーバリューストアの read-write アクセスを与えて。edge api PUT /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/store-grants --input - <<'EOF'
{"store":"kv","mode":"read-write"}
EOFcurl -X PUT "https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/store-grants" \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"store":"kv","mode":"read-write"}'1 つのスクリプトに限るときは名前を指定します。ボディのフィールドは scripts です。例: [{"script_id":"01JBQZ8XKT4A9WN2CDEFGH5RM7","access":"write"}] に "store":"sql"。
これは edge_store_grant_set を呼びます。最初の sql 付与で distribution の データベースも作られます(database_created: true)。訪問者のリクエストには、付与が始める ランタイム更新のあと(通常は数秒以内)に反映されます。edge_function_invoke にはすぐに 反映されます。
2. テーブルを作る(SQL のみ)
ルートが依存する前にスキーマを作ります。1 回のリクエストに複数の文を入れると、1 つの トランザクションとして全部実行されるか、何も実行されないかのどちらかです。
acme-marketing で SQL テーブル signups を作って。id は integer primary key、
email は text unique not null、created_at は text default current_timestamp。edge api POST /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/sql --input - <<'EOF'
{"statements":[{"sql":"CREATE TABLE signups (id INTEGER PRIMARY KEY, email TEXT UNIQUE NOT NULL, created_at TEXT DEFAULT current_timestamp)"}]}
EOFcurl -X POST "https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/sql" \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"statements":[{"sql":"CREATE TABLE signups (id INTEGER PRIMARY KEY, email TEXT UNIQUE NOT NULL, created_at TEXT DEFAULT current_timestamp)"}]}'これは edge_sql_execute を呼びます。書き込む文には function.write が必要です。あとでスキーマを見るときは SELECT name, sql FROM sqlite_schema を頼んでください。
3. handler から env.kv と env.sql を呼ぶ
handler の 2 番目の引数 env に distribution のストアが入っています。env.document と 並んで env.kv と env.sql が使えます。拒否された呼び出しは .code 付きのエラーを投げます (Python は KvError または SqlError)。
function handler(request, env) {
if (request.method === 'POST') {
const { email } = JSON.parse(request.body || '{}');
try {
env.sql.query('INSERT INTO signups (email) VALUES (?)', [email]);
} catch (error) {
if (error.code === 'sql_error') return { statusCode: 409, body: 'already signed up' };
throw error;
}
const { value } = env.kv.incr('signups:total');
return { statusCode: 201, body: JSON.stringify({ total: value }) };
}
const { rows } = env.sql.query('SELECT email, created_at FROM signups ORDER BY id DESC LIMIT 20');
return { statusCode: 200, headers: { 'content-type': 'application/json' }, body: JSON.stringify(rows) };
}キーバリューの呼び出し:
| メソッド | 戻り値 |
|---|---|
get(key) | {value, version}。ない場合は not_found を投げる |
getMany(keys) | 最大 25 キーの {items}。ないキーは含まれない |
put(key, value, {ttl, ifVersion, ifAbsent}) | {version}。ifVersion は誰も変えていない場合だけ、ifAbsent はキーがない場合だけ書き込む |
incr(key, by, {ttl}) | {value, version}。キーがなければ by で作る |
delete(key, {ifVersion}) | {deleted} |
list(prefix, {cursor, limit}) | {keys, cursor}。1 ページ最大 100 キー |
値は文字列です。JSON は JSON.stringify で保存してください。ttl は秒(60 秒から 1 年)で、 期限切れのキーはすぐに「ない」ものとして読まれます。
SQL の呼び出し:
| メソッド | 戻り値 |
|---|---|
query(sql, params) | {columns, rows, rows_affected, last_insert_rowid} |
batch([{sql, params}, …]) | {results}。最大 20 文を 1 つのトランザクションで実行 |
値は文字列連結ではなく ? プレースホルダーで渡してください。mode read の付与で許される のは SELECT、VALUES、EXPLAIN、WITH … SELECT だけです。
ホスト呼び出しは、データオブジェクト・KV・SQL を合わせて 1 回の invocation あたり 8 回 です。getMany と batch はそれぞれ 1 回と数えるので、複数のキーや文が必要なときはこちらを 使ってください。
fetch する関数はもう一度実行される
外部 URL を呼ぶ関数は、fetch のたびに最初から実行し直されます。fetch より前のストア呼び出しも もう一度実行されます。書き込みは fetch のあとに行うか、繰り返しても安全な形にしてください (KV なら ifVersion / ifAbsent、SQL なら一意制約や INSERT OR IGNORE)。
4. ルートを割り当てる前に試す
acme-marketing の関数 01JBQZ8XKT4A9WN2CDEFGH5RM7 を、POST body
{"email":"ana@example.com"} で呼び出してレスポンスを見せて。関数の実行には HTTP ルートがありません。エージェントは edge_function_invoke を実行します。訪問者のリクエストと同じ付与とストアを 使います。そのあと エンドポイントを追加する のとおりにルートを 割り当てます。
5. データを確認する
acme-marketing で、signups の新しい 10 行と KV キー signups:total の値を見せて。edge api POST /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/sql --input - <<'EOF'
{"statements":[{"sql":"SELECT email, created_at FROM signups ORDER BY id DESC LIMIT 10"}]}
EOF
edge api GET /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/kv/signups:totalcurl -X POST "https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/sql" \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"statements":[{"sql":"SELECT email, created_at FROM signups ORDER BY id DESC LIMIT 10"}]}'
curl "https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/kv/signups:total" \
-H "Authorization: Bearer $EDGE_TOKEN"これは edge_sql_execute と edge_kv_get を呼びます。edge_kv_list は接頭辞で キーを一覧し、edge_kv_put と edge_kv_delete はキーを変更し、edge_store_grant_get は 現在の付与を表示します。
distribution を削除すると、その関数、キーバリューのデータ、SQL データベースも削除されます。
次に読む
- 上限 — 値のサイズ、キー数、1 回あたりの行数、データベースサイズ
- 関数からデータオブジェクトを読み書きする — 訪問者も読める JSON ドキュメント
- 関数ランタイム — サンドボックスの上限と外部 HTTPS