関数からデータオブジェクトを読み書きする
関数ランタイムは、同一 distribution 上のデータオブジェクトを、ホスト経由の env.document 呼び出しで読み書きできます。付与(grant)が、どの script がどのキーに 触れられるか、オブジェクトが public(ルートまたは GET フォールバックで訪問者が GET できる)か private(訪問者には配信されない)か、読み取り専用か read-write かを決めます。
付与は関数ソースの外にあります。handler から付与を作成・変更・迂回することはできません。 付与の設定には function.write(edge_document_grant_set または edge_document_prefix_set)が必要です。document.write だけでは足りません。
関数への付与と private データオブジェクトは ウェブコンソールではまだ管理できません。 エージェントまたは MCP を使ってください。
このページは、少なくとも 1 つコンパイル済みの関数ランタイムがある distribution を前提とします。 まだの場合は エンドポイントを追加する から始めてください。 以降、その distribution は acme-marketing(d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38)、handler の script は 01JBQZ8XKT4A9WN2CDEFGH5RM7 とします。
1. public オブジェクトを書く(訪問者も読む場合)
public 付与を 1 キーに付けるとき、そのオブジェクトは public ストア(edge_document_write で管理するのと同じファイル)にすでに存在している必要があります。
acme-marketing にデータオブジェクト menu.json を
{"title":"Lunch"} で保存して、etag を見せて。edge api PUT /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/documents --input - <<'EOF'
{
"documents": [
{
"path": "menu.json",
"content": "{\"title\":\"Lunch\"}"
}
]
}
EOFcurl -s -X PUT \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/documents \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"documents": [
{
"path": "menu.json",
"content": "{\"title\":\"Lunch\"}"
}
]
}'エージェントは edge_document_write を実行します。これだけでは関数へのアクセスは付与されません。
2. 関数へアクセスを付与する
mode に read または read-write、visibility に public または private を選び、 必要なら script id と read / write を列挙する scripts を指定します。scripts を 省略すると、distribution 上のすべての関数が mode のアクセスを得ます。sidecar 付与を外すときは mode none です。
| visibility | 訪問者の GET /_api | 典型的な用途 |
|---|---|---|
public | マップまたは GET フォールバックで可 | ページと関数の両方が使う共有 JSON |
private | 不可 — ルートがあっても 404 | メモ、下書き、関数だけが触るカウンター |
既存付与の visibility は変更できません。public の read-write キーは cache-control: no-store で配信され、キャッシュが関数の書き込みを隠しません。
acme-marketing で、script 01JBQZ8XKT4A9WN2CDEFGH5RM7 に
public データオブジェクト menu.json の read アクセスを付与して。acme-marketing で、script 01JBQZ8XKT4A9WN2CDEFGH5RM7 に
private プレフィックス notes/ の read-write 付与を設定して。エージェントは edge_document_grant_set または edge_document_prefix_set を実行します。 プレフィックス付与は、その下のすべてのキー(関数が後から作るキーも)をカバーします。 プレフィックス付与は最大 32、sidecar あたりの script は最大 32 です。制限 を参照してください。
private キーは、private 付与のあと edge_private_document_write で内容を書き込みます。 これらのツールは private ストアのみを読み書きし、public の edge_document_* パスには触れません。
3. handler から env.document を呼ぶ
handler は 2 番目の引数 env でストアを受け取ります。JavaScript も Python も env.document を 持ちます(以前のグローバル edge.document は同じオブジェクトです)。Python は拒否時に .code 付きの DocumentError を投げます。
| メソッド | 用途 |
|---|---|
get(key) | {body, etag} を返す |
put(key, body, ifMatch?) | {etag} を返す。同時更新を避けるには前の etag を ifMatch に渡す |
list(prefix, cursor?) | {keys, cursor} — 最大 50 キーずつ |
delete(key) | {deleted: true} を返す |
1 回の invocation あたりのホスト呼び出しは、env.kv と env.sql と合わせて最大 8 回です。各 body の上限は public データオブジェクトと同じ 1 MiB です。
function handler(request, env) {
var doc = env.document.get('menu.json');
return {
statusCode: 200,
headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
body: JSON.stringify({ menu: JSON.parse(doc.body), etag: doc.etag }),
};
}error.code(JavaScript)または DocumentError.code(Python)の主な値:
| code | 意味 |
|---|---|
denied | 付与なし、script 未登録、アクセス不足 — 付与なしの get も含む |
not_found | 付与はあるがオブジェクトがない |
etag_mismatch | ifMatch が保存済みオブジェクトと一致しない |
etag_required | 更新に etag が必要だが渡されていない |
already_exists | 既存キーへの作成競合 |
エンドポイントを追加する で /_api に関数をマップします。 公開パスに頼る前に edge_function_invoke で試してください。
4. 付与を確認する
acme-marketing の menu.json の関数付与と、すべてのプレフィックス付与を見せて。エージェントは edge_document_grant_get と edge_document_prefix_get(function.read)を 実行します。
次に読む
- 関数ランタイム — サンドボックス上限と外向き HTTPS
- データオブジェクトを配信する — 関数なしの public オブジェクト
- 関数からキーバリューと SQL ストレージを使う — カウンター、セッション、問い合わせできるテーブル
- エンドポイント —
/_apiルートとデータオブジェクトの関係