Skip to content

関数からキーバリューと 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 は付与を外し、データは残します。

text
acme-marketing で、すべての関数にキーバリューストアの read-write アクセスを与えて。
bash
edge api PUT /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/store-grants --input - <<'EOF'
{"store":"kv","mode":"read-write"}
EOF
bash
curl -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 つの トランザクションとして全部実行されるか、何も実行されないかのどちらかです。

text
acme-marketing で SQL テーブル signups を作って。id は integer primary key、
email は text unique not null、created_at は text default current_timestamp。
bash
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)"}]}
EOF
bash
curl -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)。

javascript
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. ルートを割り当てる前に試す ​

text
acme-marketing の関数 01JBQZ8XKT4A9WN2CDEFGH5RM7 を、POST body
{"email":"ana@example.com"} で呼び出してレスポンスを見せて。

関数の実行には HTTP ルートがありません。エージェントは edge_function_invoke を実行します。訪問者のリクエストと同じ付与とストアを 使います。そのあと エンドポイントを追加する のとおりにルートを 割り当てます。

5. データを確認する ​

text
acme-marketing で、signups の新しい 10 行と KV キー signups:total の値を見せて。
bash
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:total
bash
curl -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 データベースも削除されます。

次に読む ​