フォームでファイルのアップロードを受け付ける
サイトのフォームは、テキストだけでなくファイルも受け取れます。訪問者のブラウザーは、フォームの送信とは別に、各ファイルをストレージへ直接送ります。そのあとフォームは、ファイルの代わりにファイルの upload id を送信します。Edge はすべてのファイルをマルウェアスキャンし、中身がブラウザーの申告した種類と一致するかを確認します。読み取りやダウンロードができるのは、スキャン結果が clean のファイルだけです。
ページからのリクエストは 3 つです。
POST /_upload/{form_id}で、1 ファイル分のアップロードチケットを受け取ります。- ブラウザーが、チケットの URL にファイルを送ります。
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 のルートも含めてください。
acme-careers の apply フォームで、resume フィールドに履歴書を 1 つ受け付けるようにして。
PDF か Word(.docx)で、100 MiB まで。GET /_api/openings は openings.json の配信を続けて。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
}
}
}
}
}
}
EOFcurl -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 つ作ります。
<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>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 で拒否します。
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 が返ります。
{ "id": "19a3f0c4e2b5c8d1e3f7", "lane": "submit", "path": "/_submit/apply" }ファイルのフィールドの値が使えないアップロードの場合、/_submit は 400 を返し、何も保存しません。訪問者は修正してもう一度送信できます。
{ "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 | マルウェアは見つからず、中身は申告された種類と一致しています。読み取りとダウンロードができます。 |
rejected | reason は malware、type_mismatch(先頭のバイトが申告された種類と一致しない)、size_mismatch のいずれかです。ファイルは削除されます。 |
scan_failed | 1 回の再試行後も判定が出ませんでした。このファイルは読み取れません。 |
acme-careers の送信内容 19a3f0c4e2b5c8d1e3f7 と、添付ファイルのスキャン状態を見せて。edge api GET /v1/distributions/b6e2c9d1-4f3a-4b7e-9c21-5d8a7f0e3b14/submissions/19a3f0c4e2b5c8d1e3f7curl -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 の一覧があります。
{
"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 は、購読を作成する前に確認を求めます。フォームの送信を転送する を参照してください。
acme-careers の apply フォームの送信内容と、添付ファイルごとのスキャン結果を
https://ats.acme.example/edge-applications に送って。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"}
EOFcurl -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 回届きます。
{
"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 があります。受信側は、トークンなしでここからファイルを取得します。
curl -sL -o mika-tanaka-cv.pdf "$DOWNLOAD_URL"- リンクが使えるのは、ファイルが
cleanになってからです。それまでは 409 を返します。rejectedやscan_failedになったファイルでは、ずっと使えません。取得する前に、statusがcleanのform.file.scannedを待ってください。 - リンクはイベントから 7 日間有効です。60 秒間有効なダウンロードにリダイレクトするので、すぐにリダイレクト先をたどってください。
- 使用はすべて記録されます。リンクを持っている人は、期限まで誰でもファイルをダウンロードできます。パスワードと同じように扱い、ログに残したり他人に渡したりしないでください。
次に読む
- フォームの送信内容をエージェントに読ませる
- Edge のイベントを Webhook に送る
- エンドポイント: ポリシーの規則と種類の文字列
- 制限