8-3 マニュアルから出し入れ（put・get・delete・list）

この節を一言で

マニュアルから倉庫にできることは、入れる・出す・消す・一覧の四つで、どれも荷札の名前で指します。

マニュアルから、入れる・出す・消す・一覧の四つを行います。

倉庫（R2）が建ち、受付の裏に取り出し口も付きました。次は、スタッフが実際に荷物を出し入れする手つきです。

いま読んでいるこのサイト（Cloudflare Lab）のマニュアル（Worker）も、この四つだけで図版の出し入れをまかなう予定です。ここでは、入れる、出す、消すと一覧、荷物に付いてくる控えの順に見ます。

Learning goals

この節でできるようになること

• 入れる・出す・消す・一覧の四つを日常語で言える
• 荷札が無いときに何が返るかを言える
• 一覧を荷札の先頭で絞れることを説明できる
• 荷物に添える自前のメモが何かを説明できる

1. 入れる

荷物を預けるときは、荷札の名前と中身を倉庫に渡します。受け取った側は、控えを 1 枚返してくれます。

Cloudflare では、この操作を put と呼びます。公式は、put は渡された値と付帯情報を指定した key のもとに保存し、成功すると保存した物の情報を持つ R2Object を返す、と説明しています。

次のコードは「届いた中身を、この荷札の名前で倉庫に入れる」ものです。読めなくても大丈夫です。

await env.MY_BUCKET.put(key, request.body);
return new Response(`Put ${key} successfully!`);

MY_BUCKET が第 8-2 節で登録した取り出し口、key が荷札の名前、request.body が中身です。

put は荷札と中身を預け、控え（R2Object）を返します。

荷札を貼った箱を倉庫に預けると、控えが 1 枚返ってきます。

つまり、put は荷札と中身を預け、控えを返します。

2. 出す

取り出すときは、荷札の名前だけを伝えます。その名前の荷物が無ければ、空手で戻ってきます。

Cloudflare では、この操作を get と呼びます。公式は、get は指定した key の R2ObjectBody（付帯情報と中身の両方）を返し、key が存在しない場合は null（何も無い）を返す、と説明しています。中身は body として少しずつ流れる形で受け取れます。

荷物には、種類（画像なのか文書なのか）などの情報が付いています。公式はこれを httpMetadata と呼び、writeHttpMetadata を使うと、その情報をお客さんへ返す答えに付ける控え（ヘッダ）へそのまま書き写せる、と説明しています。

次のコードは「その荷札の荷物を出し、無ければ見つからないと返す」ものです。読めなくても大丈夫です。

const object = await env.MY_BUCKET.get(key);
if (object === null) {
  return new Response("Object Not Found", { status: 404 });
}
const headers = new Headers();
object.writeHttpMetadata(headers);
return new Response(object.body, { headers });

get は荷札の名前で中身を受け取り、無ければ空を返します。

荷札の名前を伝えると箱が出てきます。添えられた情報は、そのまま返事の控えに書き写せます。

つまり、get は名前で中身を受け取り、無ければ空を返します。

3. 消すと、一覧する

いらなくなった荷物は下ろします。何が入っているかを知りたいときは、荷札を並べて見ます。

Cloudflare では、消すのが delete、並べるのが list です。公式は、delete は 1 回で最大 1,000 個の key を消せると説明しています。list は並び順が名前の辞書順で、1 回に返るのは最大 1,000 件です。

一覧は、荷札の先頭が同じものだけに絞れます。公式はこの絞り込みを prefix と呼び、指定した文字で始まる key だけが返ると説明しています。1 回で返り切らなかったときは truncated が true になり、続きを取るための cursor が付いてきます。

次のコードは「figures/ で始まる荷札だけを一覧する」ものです。読めなくても大丈夫です。

const listed = await env.MY_BUCKET.list({ prefix: "figures/", limit: 500 });

list は荷札の先頭が一致するものを、上限つきで並べます。

一覧表には、同じ書き出しで始まる荷札だけが並んでいます。

つまり、delete で下ろし、list に prefix を添えて必要なぶんだけ並べます。

4. 荷物に付いてくる控え

控えには、荷札の名前のほかに、大きさや預けた日時が書かれています。自分用のメモを添えることもできます。

公式は、R2Object の中身として key（荷札）、size（バイト単位の大きさ）、uploaded（預けた日時）などを挙げています。中身を持たず控えだけが欲しいときは head を使い、公式は、key があればその R2Object を、無ければ null を返すと説明しています。

自分で決めた項目を添えたいときは customMetadata を使います。公式はこれを「利用者が自分で決めた付帯情報の一覧」だと説明しており、預けるときに渡します。

head は控えだけを受け取り、余白には自前のメモを添えられます。

控えには名前・大きさ・預けた日時が並び、余白にメモを書き足せます。

つまり、控えだけが欲しいときは head、自前のメモは customMetadata です。

Cloudflare Lab での使われ方

ここで紹介した出し入れが、いま読んでいる Cloudflare Lab でどう使われるかを見ます。

Cloudflare Lab は Phase 2 で、図版の画像を figures/ で始まる荷札で put し、ページからは get で出す予定です。一覧を作るときは prefix を figures/ にして list します。実測（置いた object の数）は実装後に追記します。

つまずきやすいところ

つまずきポイント

無い荷札を指定すると、空（null）が返ります

get も head も、その名前の荷物が無ければ null を返します。受け取った後に「無かったとき」の返事を必ず用意します。

つまずきポイント

大きなファイルをそのまま抱え込みません

公式は、Worker には 1 つあたり 128 MB の記憶の上限があり、大きなファイルを何度も読み込むとこの上限に届くと注意しています。少しずつ流す形（Streams）を使います。

この節のまとめ

• 入れるのが put、出すのが get、消すのが delete、並べるのが list です。
• get と head は、荷札が無ければ null を返します。
• list は名前の辞書順で最大 1,000 件、prefix で先頭を絞れます。

この節で出てきた言葉を、つながりの順に並べると次のようになります。

flowchart TD
  A["取り出し口<br/>MY_BUCKET"] --> B["入れる<br/>put"]
  B --> C["控えが返る<br/>R2Object"]
  C --> D["出す<br/>get"]
  D --> E["中身と付帯情報<br/>body / httpMetadata"]
  E --> F["消す・並べる<br/>delete / list"]
  F --> G["先頭で絞る<br/>prefix"]

図のラベル: 取り出し口 MY_BUCKET / 入れる put / 控えが返る R2Object / 出す get / 中身と付帯情報 body / httpMetadata / 消す・並べる delete / list / 先頭で絞る prefix

次の節では、倉庫を店先に開ける方法と、無料で使える範囲を見ます。

この節のチェック

問 1put が成功したとき、公式では何が返ると説明されていますか？

何も返らない保存した物の情報を持つ R2Object消した件数荷札の一覧

問 2指定した key の荷物が無いとき、get は何を返しますか？

null（何も無い）空の文字列直前の荷物エラーで止まる

問 3list が 1 回で返す件数の上限はいくつですか？

10 件100 件1,000 件上限はない

問 4list に prefix を指定すると、何が起きますか？

並び順が逆になる件数の上限が増える中身も一緒に返る指定した文字で始まる key だけが返る

問 5中身は要らず、荷物の控えだけが欲しいときに使う操作はどれですか？

putheaddeletelist

採点する