Skip to content

サインインした訪問者に画像をアップロードさせる ​

function runtime は、訪問者にファイルをストレージへ直接アップロードさせることができます。アップロードを許可するかどうかは関数が判断し、許可するときは env.upload でアップロードに署名します。訪問者のブラウザーは、返されたチケットを使ってファイルをストレージに送るので、ファイルが関数を通ることはありません。その後 Edge はファイルをマルウェアスキャンし、先頭のバイトが申告された種類と一致するかを確認します。スキャン結果が clean になって初めて、関数はファイルを読んだり、distribution のファイルストアに**保存(keep)**したりできます。ファイルストアに保存したファイルは file ルートで配信できます。

このページでは、プロフィール写真のアップロードを作ります。ページは 1 つの関数の 3 つのパスとやり取りします。

  1. POST /_api/avatar/sign はリクエストを確認し、アップロードチケットを返します。
  2. GET /_api/avatar/status/{upload_id} はスキャンの状態を返します。
  3. POST /_api/avatar/keep は clean な画像をファイルストアの avatars/ にコピーします。

保存した画像は、file ルートで /_api/avatars/* から配信します。

このページでは、acme-community(7c1e4b9a-2d5f-4e83-a6b0-9f3d8c2e1a57)が公開中で、GET /_api/members でデータオブジェクト members.json を配信しており、コンパイル済みの JavaScript の function runtime(script 01M5BX8R3K7N2Q9V4T6W1Y3Z5C)がある状態を前提にします。関数がまだない場合は、エンドポイントを追加するから始めてください。

function runtime とその付与は、まだ Web コンソールでは管理できません。アップロードとファイルのプレフィックスの付与はエージェントだけが行えます。どちらにも対応する HTTP ルートや CLI コマンドはありません。

始める前に: サインインを必須にする ​

関数は、訪問者の Cookie、ヘッダー、身元を受け取りません。そのため、訪問者を互いに区別できません。アップロードをサインインした訪問者だけに限るには、distribution 全体を訪問者のサインインの後ろに置きます。そうすると Edge は、有効なサインインのない /_api リクエストをすべて拒否するので、関数に届くのはサインインした訪問者だけになります。distribution をパスワードで保護する と アクセス制御 のルールを参照してください。

関数の中では、署名する前に、リクエストから分かることを確認します。申告された種類とサイズ、そのほか独自のロジックに必要な条件です。Edge はさらに独自の確認を加えます。種類は許可リストにあること、ファイルは申告どおりのサイズで届くこと、そしてアップロードを確認できるのは署名した script だけであることです。

1. 関数にアップロードへの署名を許可する ​

アップロードは、有効にするまですべての script でオフです。この設定はソースの外に保存されるので、コードが自分にアップロードを許可することはできません。

text
acme-community で、script 01M5BX8R3K7N2Q9V4T6W1Y3Z5C が訪問者のアップロードに署名できるようにして。

エージェントは enabled を true にして edge_function_upload_grant_set を実行します。応答には、その distribution でアップロードに署名できるすべての script が含まれます。

json
{ "script_id": "01M5BX8R3K7N2Q9V4T6W1Y3Z5C", "uploads": true, "upload_scripts": ["01M5BX8R3K7N2Q9V4T6W1Y3Z5C"] }

edge_file_prefix_get も同じ一覧を upload_scripts として返します。script の署名を止めるときは、その script のアップロードをオフにするようエージェントに頼みます。エージェントは enabled を false にして同じツールを実行します。付与がないと、env.upload の呼び出しはすべて not_granted で失敗します。

この操作で本番サイトは変わりません。ルートがこの script を実行するまで、訪問者はアップロードできません。

2. 保存する画像のための公開プレフィックスを付与する ​

keep はファイルストアに書き込むので、script には画像を保存するプレフィックスへの読み書きの付与も必要です。file ルートで配信できるように、公開にします。

text
acme-community で、script 01M5BX8R3K7N2Q9V4T6W1Y3Z5C に、ファイルのプレフィックス
avatars/* を公開として読み書きできるように付与して。

エージェントは edge_file_prefix_set を実行します。プレフィックスの公開・非公開は、一度設定すると変更できません。ファイルの付与の仕組みは 関数からファイルを保存して配信する を参照してください。

3. ハンドラーを書く ​

1 つのハンドラーで 3 つのパスすべてを処理します。受け付けるのは 5 MiB までの JPEG と PNG です。これは関数独自の規則で、Edge 自体はもっと大きなファイルや多くの種類を許可しています。

javascript
const MAX_BYTES = 5 * 1024 * 1024;
const EXTENSIONS = { 'image/jpeg': 'jpg', 'image/png': 'png' };
const STATUS_FOR = { not_found: 404, not_clean: 409, precondition_failed: 409, type_mismatch: 422, quota_exceeded: 403 };

function reply(statusCode, value) {
  return { statusCode, headers: { 'content-type': 'application/json' }, body: JSON.stringify(value) };
}

function handler(request, env) {
  try {
    if (request.method === 'POST' && request.path === '/_api/avatar/sign') {
      const { contentType, size } = JSON.parse(request.body || '{}');
      if (!EXTENSIONS[contentType]) return reply(400, { error: 'jpeg_or_png_only' });
      if (!(size >= 1 && size <= MAX_BYTES)) return reply(400, { error: 'too_large' });
      return reply(200, env.upload.sign({ contentType, size }));
    }

    if (request.method === 'GET' && request.path.startsWith('/_api/avatar/status/')) {
      const uploadId = request.path.slice('/_api/avatar/status/'.length);
      const { status, reason } = env.upload.status(uploadId);
      return reply(200, { status, reason });
    }

    if (request.method === 'POST' && request.path === '/_api/avatar/keep') {
      const { uploadId } = JSON.parse(request.body || '{}');
      const { contentType } = env.upload.status(uploadId);
      const kept = env.upload.keep(uploadId, `avatars/${uploadId}.${EXTENSIONS[contentType]}`);
      return reply(200, { url: `/_api/${kept.key}`, size: kept.size });
    }

    return reply(404, { error: 'not_found' });
  } catch (error) {
    if (!error.code) throw error;
    return reply(STATUS_FOR[error.code] || 400, { error: error.code });
  }
}
  • sign はブラウザーが必要とするチケットを返します。そのままページに渡してください。ページが読むので、フィールド名はスネークケースです。
  • keep はファイルを新しく作り、既存のファイルを置き換えることはありません。画像はアップロード ID で名前を付けるので、アップロードごとに別のキーになります。関数は訪問者が誰かを知らないので、どの画像が誰のものかは自分のシステムで記録してください。
  • 保存(keep)されなかったアップロードは 1 日後に削除されます。
  • このハンドラーがリクエストごとに行うアップロードの呼び出しは最大 2 回で、呼び出しあたり 8 回のホスト呼び出しに十分収まります。

Python では、ハンドラーは def handler(request, env) で、呼び出しは env.upload.sign(content_type, size)、env.upload.status(upload_id)、env.upload.keep(upload_id, key) です。戻り値は辞書です。エラーは .code 付きの UploadError として送出されます。

4. パスを割り当てる前に試す ​

text
acme-community の script 01M5BX8R3K7N2Q9V4T6W1Y3Z5C を、POST /_api/avatar/sign と
ボディ {"contentType": "image/jpeg", "size": 248311} で invoke して。

エージェントは edge_function_invoke を実行します。レスポンスのボディはチケットです。

json
{
  "upload_id": "upl_01M5C2H7QK3R8T1V6W9X4Y2Z5B",
  "mode": "single",
  "url": "https://…",
  "fields": { "key": "…", "Content-Type": "image/jpeg", "Policy": "…", "X-Amz-Signature": "…", … },
  "expires_in": 600
}

テストで発行したチケットも、ほかのチケットと同じく組織の月間アップロード上限に数えられ、使われなければ期限切れになります。

5. パスを割り当てる ​

この手順で訪問者がアクセスできるものが変わります。runtime を送るとエンドポイントの割り当て全体が置き換わるので、既存のパスもすべて含めてください。

text
acme-community で、POST /_api/avatar/sign、GET /_api/avatar/status/*、
POST /_api/avatar/keep を script 01M5BX8R3K7N2Q9V4T6W1Y3Z5C に割り当てて、
avatars/ の下の公開ファイルを /_api/avatars/* で配信して。
GET /_api/members は members.json のまま残して。
bash
edge api PATCH /v1/distributions/7c1e4b9a-2d5f-4e83-a6b0-9f3d8c2e1a57 --input - <<'EOF'
{
  "runtime": {
    "api": {
      "routes": [
        { "match": "/_api/members", "document": "members.json" },
        { "match": "/_api/avatar/sign", "wasm": "01M5BX8R3K7N2Q9V4T6W1Y3Z5C", "methods": ["POST"] },
        { "match": "/_api/avatar/status/*", "wasm": "01M5BX8R3K7N2Q9V4T6W1Y3Z5C", "methods": ["GET"] },
        { "match": "/_api/avatar/keep", "wasm": "01M5BX8R3K7N2Q9V4T6W1Y3Z5C", "methods": ["POST"] },
        { "match": "/_api/avatars/*", "file": "avatars/" }
      ]
    }
  }
}
EOF
bash
curl -s -X PATCH \
  https://api.edge.deca-dev.com/v1/distributions/7c1e4b9a-2d5f-4e83-a6b0-9f3d8c2e1a57 \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"runtime":{"api":{"routes":[{"match":"/_api/members","document":"members.json"},{"match":"/_api/avatar/sign","wasm":"01M5BX8R3K7N2Q9V4T6W1Y3Z5C","methods":["POST"]},{"match":"/_api/avatar/status/*","wasm":"01M5BX8R3K7N2Q9V4T6W1Y3Z5C","methods":["GET"]},{"match":"/_api/avatar/keep","wasm":"01M5BX8R3K7N2Q9V4T6W1Y3Z5C","methods":["POST"]},{"match":"/_api/avatars/*","file":"avatars/"}]}}}'

エージェントは edge_distribution_update を実行します。パスは更新がコンパイルされた時点で有効になります。エンドポイントにはプレビューも promote もありません。パスを取り下げるときは、そのパスを除いた割り当てをもう一度送ってください。

6. ページからアップロードする ​

関数に届くのはリクエストのパスだけで、クエリ文字列は届きません。そのため、状態を問い合わせるときはアップロード ID をパスに入れます。また、ボディ付きの /_api への POST には、ボディの SHA-256 を 16 進数にした x-amz-content-sha256 が必要です。

html
<input id="avatar" type="file" accept="image/jpeg,image/png">
<img id="preview" alt="">
javascript
async function api(method, path, body) {
  const init = { method, headers: {} };
  if (body !== undefined) {
    const text = JSON.stringify(body);
    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
    init.headers['content-type'] = 'application/json';
    init.headers['x-amz-content-sha256'] = [...new Uint8Array(digest)]
      .map((byte) => byte.toString(16).padStart(2, '0')).join('');
    init.body = text;
  }
  const r = await fetch(path, init);
  const data = await r.json();
  if (!r.ok) throw data;
  return data;
}

async function uploadAvatar(file) {
  // 1. 関数にチケットを求める。
  const ticket = await api('POST', '/_api/avatar/sign', { contentType: file.type, size: file.size });

  // 2. ファイルをストレージに送る。チケットのフィールドを先に、ファイルを最後に。
  const data = new FormData();
  for (const [key, value] of Object.entries(ticket.fields)) data.append(key, value);
  data.append('file', file);
  const sent = await fetch(ticket.url, { method: 'POST', body: data });
  if (!sent.ok) throw new Error('upload failed');

  // 3. スキャンを待つ。
  for (;;) {
    const { status, reason } = await api('GET', `/_api/avatar/status/${ticket.upload_id}`);
    if (status === 'clean') break;
    if (status === 'rejected' || status === 'scan_failed') throw new Error(reason || status);
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }

  // 4. 保存して表示する。
  const kept = await api('POST', '/_api/avatar/keep', { uploadId: ticket.upload_id });
  document.getElementById('preview').src = kept.url;
  return kept.url;
}

document.getElementById('avatar').addEventListener('change', (event) => {
  uploadAvatar(event.target.files[0]).catch((error) => console.error(error));
});

チケットの有効期間は 10 分です。ストレージは、ページが申告したサイズと異なる長さのファイルを拒否します。再エンコードしたコピーではなく、訪問者が選んだ File をそのまま送ってください。

status は次の値をとります。

status意味
pendingチケットは発行済みだが、ファイルがまだ届いていない
scanningファイルが届き、スキャン中
cleanマルウェアがなく、先頭のバイトが申告された種類と一致する。関数は読み取りと保存ができる
rejectedreason は malware、または先頭のバイトが申告された種類でない場合の type_mismatch
scan_failed判定が出なかった。このファイルは読み取りも保存もできない

アップロードが clean になる前に keep を呼ぶと not_clean で失敗します。中身が申告された種類でないファイルでは type_mismatch です。このハンドラーは、それぞれ 409 と 422 で応答します。

bash
curl -sI https://acme-community.edge.deca-dev.com/_api/avatars/upl_01M5C2H7QK3R8T1V6W9X4Y2Z5B.jpg

保存した画像はブラウザーで開きます。関数が書き込めるプレフィックスの file ルートと同じく、cache-control: no-store で配信されます。

100 MiB を超えるファイルには single のチケットではなく、16 MiB のパートに分かれた multipart のチケットが返ります。ページは各パートを PUT し、最後に関数へ渡して env.upload.complete で完了させます。関数ランタイム を参照してください。

次に読む ​