Skip to content

フォームでファイルのアップロードを受け付ける ​

サイトのフォームは、テキストだけでなくファイルも受け取れます。訪問者のブラウザーは、フォームの送信とは別に、各ファイルをストレージへ直接送ります。そのあとフォームは、ファイルの代わりにファイルの upload id を送信します。Edge はすべてのファイルをマルウェアスキャンし、中身がブラウザーの申告した種類と一致するかを確認します。読み取りやダウンロードができるのは、スキャン結果が clean のファイルだけです。

ページからのリクエストは 3 つです。

  1. POST /_upload/{form_id} で、1 ファイル分のアップロードチケットを受け取ります。
  2. ブラウザーが、チケットの URL にファイルを送ります。
  3. POST /_submit/{form_id} でフォームを送信します。ファイルのフィールドの値は upload id です。

このページでは、distribution acme-careers(b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14)が公開済みで、応募ページがあり、/_api/openings でデータオブジェクトを 1 つ配信している状態を前提にします。フォームの名前は apply、ファイルのフィールドは resume です。

フォームは まだ Web コンソールでは管理できません。送信内容の受信箱もありません。コンソールの Endpoints はまだ準備中の画面です。ポリシーの設定と送信内容の読み取りは、エージェント、CLI、API で行ってください。

1. フォームでアップロードを許可する ​

ポリシーがない場合、/_upload/apply は 404 を返し、/_submit/apply は送られた値をそのままテキストとして保存します。ポリシーでは、フォーム、ファイルを受け取るフィールド、各フィールドが受け付ける種類、ファイルの最大サイズ、フィールドあたりのファイル数を指定します。

ポリシーは distribution の runtime の中に、/_api のマップと並べて置きます。runtime を送るとオブジェクト全体が置き換わるので、既存の api のルートも含めてください。

text
acme-careers の apply フォームで、resume フィールドに履歴書を 1 つ受け付けるようにして。
PDF か Word(.docx)で、100 MiB まで。GET /_api/openings は openings.json の配信を続けて。
bash
edge api PATCH /v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14 --input - <<'EOF'
{
  "runtime": {
    "api": {
      "routes": [
        { "match": "/_api/openings", "document": "openings.json" }
      ]
    },
    "uploads": {
      "apply": {
        "fields": {
          "resume": {
            "types": [
              "application/pdf",
              "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
            ],
            "max_bytes": 104857600,
            "max_files": 1
          }
        }
      }
    }
  }
}
EOF
bash
curl -s -X PATCH \
  https://api.edge.deca-dev.com/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14 \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"runtime":{"api":{"routes":[{"match":"/_api/openings","document":"openings.json"}]},"uploads":{"apply":{"fields":{"resume":{"types":["application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document"],"max_bytes":104857600,"max_files":1}}}}}}'

エージェントは edge_distribution_update を実行します。/_api のマップと同じく、ポリシーは更新がコンパイルされた時点で本番に反映されます。プレビューも promote もありません。フォームでファイルの受け付けをやめるには、そのフォームを除いた runtime をもう一度送ります。

更新時に確認される規則:

  • types は必須で、各値は許可リストにあるものです。PDF、Word・Excel・PowerPoint(.docx、.xlsx、.pptx)、ZIP、プレーンテキスト、CSV、JSON、PNG、JPEG、GIF、WebP、HEIC、AVIF、MP4、QuickTime、WebM、MP3、M4A、WAV、Ogg です。HTML、SVG、スクリプト、実行ファイルは受け付けません。
  • max_bytes は 1 バイトから 5 GiB です。既定は 100 MiB です。
  • max_files は 1 から 10 です。既定は 1 です。
  • アップロードを受け付けるフォームは distribution あたり 20 まで、ファイルのフィールドはフォームあたり 10 までです。フィールドを合わせて、1 回の送信に添付できるのは最大 10 ファイル、10 GiB です。
  • フィールド名に edge_s は使えません。この名前は訪問者のセッションを運びます。

種類の文字列の一覧は エンドポイント にあります。

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

/_upload への呼び出しには、訪問者のセッションを edge_s として付けます。ボディのフィールドでも、edge_s Cookie でもかまいません。このセッションは、そのあとページが /_submit に送るものと同じでなければなりません。upload id は、それを要求したセッションからの送信にしか添付できません。アナリティクス のためにページが edge_s Cookie をすでに設定しているなら、それを使ってください。そうでなければ、ページの読み込みごとにランダムな値を 1 つ作ります。

html
<form id="apply">
  <input name="name" required>
  <input name="email" type="email" required>
  <input name="resume" type="file" accept=".pdf,.docx" required>
  <button>応募する</button>
</form>
javascript
const cookie = document.cookie.match(/(?:^|; )edge_s=([^;]*)/);
const seed = cookie ? decodeURIComponent(cookie[1]) : crypto.randomUUID();

async function call(path, body) {
  const r = await fetch(path, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ edge_s: seed, ...body }),
  });
  if (!r.ok) throw await r.json();
  return r.json();
}

async function uploadFile(form, field, file) {
  const ticket = await call(`/_upload/${form}`, {
    field, name: file.name, type: file.type, size: file.size,
  });

  if (ticket.mode === 'single') {
    // 100 MiB まで: 1 回のフォーム送信。チケットの fields を先に、ファイルを最後に。
    const data = new FormData();
    for (const [key, value] of Object.entries(ticket.fields)) data.append(key, value);
    data.append('file', file);
    const r = await fetch(ticket.url, { method: 'POST', body: data });
    if (!r.ok) throw new Error('upload failed');
    return ticket.upload_id;
  }

  // それより大きい場合: 16 MiB のパートに分け、各パートはちょうど `length` バイトを PUT する。
  const parts = [];
  let urls = ticket.parts;
  for (let n = 1; n <= ticket.part_count; n += 1) {
    let part = urls.find((p) => p.n === n);
    if (!part) {
      urls = (await call(`/_upload/${form}/${ticket.upload_id}/parts`, { from: n })).parts;
      part = urls[0];
    }
    const start = (n - 1) * ticket.part_size;
    const r = await fetch(part.url, { method: 'PUT', body: file.slice(start, start + part.length) });
    if (!r.ok) throw new Error('part failed');
    parts.push({ n, etag: r.headers.get('ETag') });
  }
  await call(`/_upload/${form}/${ticket.upload_id}/complete`, { parts });
  return ticket.upload_id;
}

チケットの中身は、ページが申告したサイズによって変わります。

サイズチケットページが次にすること
100 MiB まで{"mode": "single", "upload_id", "url", "fields", "expires_at"}url に multipart/form-data で POST します。fields の項目をすべて入れ、ファイルを最後に置きます。チケットの有効期間は 10 分です。
それより大きい{"mode": "multipart", "upload_id", "part_size", "part_count", "parts": [{"n", "length", "url"}], "expires_at"}各パートの URL にちょうど length バイトを PUT し、すべてのパートの ETag を付けて /complete を呼びます。パートの URL は 1 時間有効です。最初の 100 個はチケットに含まれ、残りは from を付けて /parts に要求します。

サイズは固定されます。ストレージは、それと異なる長さのファイルやパートを拒否します。訪問者が選んだ File をそのまま送り、変換したコピーは送らないでください。

チケットが拒否されると、ページには理由が返ります。

ステータスボディ意味
400{"error": "invalid_upload", "field", "reason": "type"}種類がフィールドの types にありません。max_bytes を超えるファイルでは reason が size、名前が空、255 文字を超える、スラッシュや制御文字を含む場合は name です。
400{"error": "session_required"}ボディにも Cookie にも edge_s がありません
403{"error": "quota_exceeded"}組織の今月のアップロードが 100 GiB または 50,000 ファイルに達しました
404{"error": "not_found"}このフォームまたはフィールドにアップロードのポリシーがありません
429{"error": "rate_limited"}1 つの IP アドレスから 1 分に 20 枚、または 1 つのセッションから 1 日に 50 枚を超えるチケットを要求しました

3. フォームを送信する ​

ファイルのフィールドの値として upload id を送ります。複数のファイルを受け取るフィールドでは、id の配列を送ります。ファイルそのものを送信に含めないでください。/_submit はファイルのパートを 400 で拒否します。

javascript
document.getElementById('apply').addEventListener('submit', async (event) => {
  event.preventDefault();
  const form = event.currentTarget;
  const resume = await uploadFile('apply', 'resume', form.resume.files[0]);
  await call('/_submit/apply', {
    name: form.name.value,
    email: form.email.value,
    resume,
  });
});

送信内容が保存されると、id 付きで 200 が返ります。

json
{ "id": "19a3f0c4e2b5c8d1e3f7", "lane": "submit", "path": "/_submit/apply" }

ファイルのフィールドの値が使えないアップロードの場合、/_submit は 400 を返し、何も保存しません。訪問者は修正してもう一度送信できます。

json
{ "error": "invalid_upload", "field": "resume", "reason": "not_uploaded" }
reason意味
not_an_upload値が upload id ではありません
too_manyフィールドの max_files より多くの id があります
duplicate同じ upload id が 2 回あります
invalid別のセッション、フォーム、フィールドの id である、すでに使われている、またはファイルが拒否されています
not_uploadedチケットは発行されたが、ファイルが届いていません

送信に添付されなかったアップロードは 1 日後に削除されます。添付されたファイルは、その送信内容とともに残ります。

4. スキャンを確認する ​

送信内容が保存されるとすぐに、訪問者には 200 が返ります。スキャンはそのあとに実行され、結果が確定するまでファイルは scanning のままです。各ファイルは次の 4 つのいずれかの状態です。

status意味
scanningまだ確定していません
cleanマルウェアは見つからず、中身は申告された種類と一致しています。読み取りとダウンロードができます。
rejectedreason は malware、type_mismatch(先頭のバイトが申告された種類と一致しない)、size_mismatch のいずれかです。ファイルは削除されます。
scan_failed1 回の再試行後も判定が出ませんでした。このファイルは読み取れません。
text
acme-careers の送信内容 19a3f0c4e2b5c8d1e3f7 と、添付ファイルのスキャン状態を見せて。
bash
edge api GET /v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/19a3f0c4e2b5c8d1e3f7
bash
curl -s \
  https://api.edge.deca-dev.com/v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/19a3f0c4e2b5c8d1e3f7 \
  -H "Authorization: Bearer $EDGE_TOKEN"

エージェントは edge_submission_get を実行します。応答には、送信されたフィールドと、各ファイルの現在の状態を含む files の一覧があります。

json
{
  "submission_id": "19a3f0c4e2b5c8d1e3f7",
  "form_id": "apply",
  "received_at": "2026-10-18T02:41:07.512Z",
  "fields": {
    "name": "Mika Tanaka",
    "email": "mika@example.com",
    "resume": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B"
  },
  "files": [
    {
      "field": "resume",
      "upload_id": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B",
      "name": "mika-tanaka-cv.pdf",
      "type": "application/pdf",
      "size": 482113,
      "status": "clean",
      "reason": null,
      "has_text": true
    }
  ]
}

has_text が true のときは、エージェントが読めるように Edge がファイルのテキストを抽出しています。対象は 200 MiB までの PDF、Word(.docx)、プレーンテキスト、CSV です。

送信内容の読み取りはすべて記録されます。履歴書そのものをエージェントに読ませるには、フォームの送信内容をエージェントに読ませる を参照してください。

5. 自分のシステムにファイルを送る ​

応募内容を採用管理システムや CRM に渡すには、Webhook で form.submitted と form.file.scanned を購読します。フォームのイベントには訪問者が入力した内容が含まれるため、ワークスペースの管理者だけが持つフォーム転送の権限が必要です。また Edge は、購読を作成する前に確認を求めます。フォームの送信を転送する を参照してください。

text
acme-careers の apply フォームの送信内容と、添付ファイルごとのスキャン結果を
https://ats.acme.example/edge-applications に送って。
bash
edge webhooks create \
  --url https://ats.acme.example/edge-applications \
  --event form.submitted \
  --event form.file.scanned \
  --distribution b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14 \
  --filters - --yes <<'EOF'
{"form_id": "apply"}
EOF
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/webhooks \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://ats.acme.example/edge-applications",
        "event_types": ["form.submitted", "form.file.scanned"],
        "distribution_ids": ["b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14"],
        "filters": { "form_id": "apply" },
        "confirm": true
      }'

エージェントは edge_webhook_create を実行し、概要を見せ、同意を得てから呼び出しを繰り返します。

form.submitted は送信内容が保存された時点で届きます。この時点では、ファイルはたいてい scanning のままです。ファイルは data.envelope.files に並びます。そのあと、添付ファイルごとにスキャン結果が確定した時点で form.file.scanned が 1 回届きます。

json
{
  "type": "form.file.scanned",
  "distribution_id": "b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14",
  "data": {
    "form_id": "apply",
    "submission_id": "19a3f0c4e2b5c8d1e3f7",
    "file": {
      "field": "resume",
      "upload_id": "upl_01M4ZK6Q2T9V8X3N5P7R1W4Y6B",
      "name": "mika-tanaka-cv.pdf",
      "type": "application/pdf",
      "size": 482113,
      "status": "clean",
      "reason": null,
      "download_url": "https://api.edge.deca-dev.com/v1/file-links/eyJ2IjoxLCJ1Ijoi…"
    }
  }
}

どちらのイベントでも、各ファイルに download_url があります。受信側は、トークンなしでここからファイルを取得します。

bash
curl -sL -o mika-tanaka-cv.pdf "$DOWNLOAD_URL"
  • リンクが使えるのは、ファイルが clean になってからです。それまでは 409 を返します。rejected や scan_failed になったファイルでは、ずっと使えません。取得する前に、status が clean の form.file.scanned を待ってください。
  • リンクはイベントから 7 日間有効です。60 秒間有効なダウンロードにリダイレクトするので、すぐにリダイレクト先をたどってください。
  • 使用はすべて記録されます。リンクを持っている人は、期限まで誰でもファイルをダウンロードできます。パスワードと同じように扱い、ログに残したり他人に渡したりしないでください。

次に読む ​