Skip to content

関数からデータオブジェクトを読み書きする ​

関数ランタイムは、同一 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 で管理するのと同じファイル)にすでに存在している必要があります。

text
acme-marketing にデータオブジェクト menu.json を
{"title":"Lunch"} で保存して、etag を見せて。
bash
edge api PUT /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/documents --input - <<'EOF'
{
        "documents": [
          {
            "path": "menu.json",
            "content": "{\"title\":\"Lunch\"}"
          }
        ]
      }
EOF
bash
curl -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 で配信され、キャッシュが関数の書き込みを隠しません。

text
acme-marketing で、script 01JBQZ8XKT4A9WN2CDEFGH5RM7 に
public データオブジェクト menu.json の read アクセスを付与して。
text
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 です。

javascript
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_mismatchifMatch が保存済みオブジェクトと一致しない
etag_required更新に etag が必要だが渡されていない
already_exists既存キーへの作成競合

エンドポイントを追加する で /_api に関数をマップします。 公開パスに頼る前に edge_function_invoke で試してください。

4. 付与を確認する ​

text
acme-marketing の menu.json の関数付与と、すべてのプレフィックス付与を見せて。

エージェントは edge_document_grant_get と edge_document_prefix_get(function.read)を 実行します。

次に読む ​