7-3 マニュアルから貼る・読む（put・get・delete・list）
前の節でボードが用意できました。ここからは、受付のマニュアル（Worker）に「付箋をどう扱うか」を書きます。
壁の付箋にできることは多くありません。貼る、読む、はがす、一覧で見る。この四つで足ります。
いま読んでいるこのサイト（Cloudflare Lab）も、この四つで検証の要約を出し入れする予定です。ここでは、貼る、読む、はがす・一覧、書き替えの間隔の順に見ます。
Learning goals
この節でできるようになること
- 貼る・読む・はがす・一覧の四つの操作を言える
- 付箋が自動ではがれる時刻の指定を説明できる
- 読むときに受け取る形と手元に置く時間を選べることを言える
- 同じ見出しへの書き替えの上限を言える
新しい付箋を貼るときは、見出しと中身を書きます。同じ見出しの付箋が既にあれば、上から貼り替えたのと同じです。
Cloudflare では、この操作を put と呼びます。公式は、貼るときに三つの指定を添えられると説明しています。expiration は「いつはがすか」を決まった時刻で、expirationTtl は「今から何秒後にはがすか」で指定します。metadata は付箋の裏に書く小さなメモです。
公式によると、expirationTtl の最小の値は 60 で、60 秒より先でない期限は指定できません。metadata は JSON にできる値で、大きさは 1,024 バイトまでです。
次のコードは「first-key という見出しの付箋を貼る」ものです。読めなくても大丈夫です。
await env.NAMESPACE.put("first-key", "This is the value for the key");期限や裏書きを添えるときは、三つ目の引数で { expirationTtl: 600 } のように渡します。
付箋を貼るときに、はがれる時刻と裏書きのメモも一緒に決められます。
つまり、貼るのは put で、期限と裏書きを添えられます。
読むときは見出しを指定します。その付箋が無ければ、「無い」という結果が返ります。
Cloudflare では、この操作を get と呼びます。type で受け取る形を選べ、指定しなければ文字として受け取ります。JSON として組み立て直したいときや、大きな中身を少しずつ受け取りたいときは、ここを変えます。
もう一つの指定が cacheTtl です。公式は、読んだ場所に結果を置いておく秒数で、30 以上の整数、既定は 60 だと説明しています。めったに読まれない付箋でも、続けて読むときの待ち時間を減らせますが、よく書き替える付箋には向きません。裏書きも一緒に読むときは getWithMetadata を使います。
次のコードは「first-key の中身を読む」ものです。読めなくても大丈夫です。
const value = await env.NAMESPACE.get("first-key");見出しの配列を渡すと、まとめて読めます。公式によると、一度に渡せる見出しは 100 個までです。
見出しを言うと中身が返ります。受け取る形と、手元に置いておく時間を選べます。
つまり、読むのは get で、形と保持時間を選べます。
3. はがす・一覧
Section titled “3. はがす・一覧”いらなくなった付箋ははがします。どんな付箋が貼ってあるかは、一覧で見ます。
Cloudflare では、はがすのが delete、一覧が list です。公式は、存在しない見出しに対する delete も成功として返ると説明しています。
一覧で prefix を指定すると、見出しがその文字で始まる付箋だけが並びます。並び順は UTF-8 のバイト順です。一度に返しきれないときは list_complete が偽になり、cursor を次の呼び出しに渡して続きを受け取ります。
次のコードは「見出しが user:1: で始まる付箋を並べる」ものです。読めなくても大丈夫です。
const value = await env.NAMESPACE.list({ prefix: "user:1:" });
書き出しを指定すると、その仲間の付箋だけが抜き出されます。
つまり、はがすのは delete、一覧は list です。
4. 同じ付箋は 1 秒に 1 回
Section titled “4. 同じ付箋は 1 秒に 1 回”同じ付箋を続けざまに貼り替えると、受付の手が追いつきません。ここには決まった上限があります。
公式は、同じ見出しへの書き込みは 1 秒に 1 回が上限で、1 秒以内に同じ見出しへ書くと Too Many Requests の誤りが返ると説明しています。対処として、1 回の呼び出しでの書き込みを 1 回にまとめるか、1 秒以上あけることを勧めています。
もう一つの上限として、1 回の呼び出しから外部へ出せる操作は 1,000 回までです。まとめ読みは、何個の見出しを読んでも 1 回と数えられます。
同じ付箋を続けて貼り替えようとすると、途中から断られます。
つまり、同じ見出しの書き替えは 1 秒に 1 回までです。
Cloudflare Lab での使われ方
Section titled “Cloudflare Lab での使われ方”ここで紹介した四つの操作が、いま読んでいる Cloudflare Lab でどう使われるかを見ます。
Cloudflare Lab は Phase 2 で、検証が終わるたびに要約を 1 枚の付箋として put し、表示時に get で読む予定です。検証は 1 日に数回なので、1 秒に 1 回の上限には当たりません。実測は実装後に追記します。
つまずきやすいところ
Section titled “つまずきやすいところ”この節のまとめ
Section titled “この節のまとめ”- 貼るのが put、読むのが get、はがすのが delete、一覧が list です。
- 貼るときは、はがれる時刻（expiration・expirationTtl）と裏書き（metadata）を添えられます。
- 読むときは、受け取る形（type）と手元に置く時間（cacheTtl・30 以上、既定 60）を選べます。
この節で出てきた言葉を、つながりの順に並べると次のようになります。
図のラベル: 貼る put / はがれる時刻 expiration / expirationTtl / 裏書きのメモ metadata / 読む get / getWithMetadata / 形と保持時間 type / cacheTtl / はがす・一覧 delete / list（prefix） / 同じ見出しは 1 秒に 1 回
次の節では、無料で使える範囲と、帳簿との使い分けを見ます。
この節のチェック
© 2026 osdse