エンドポイント
エンドポイント は distribution 上の /_api パスです。コンソールではこの面を Endpoints と呼びます。各パスの行き先は次のいずれかひとつです。
| 種類 | ルートのフィールド | 配信するもの |
|---|---|---|
| データオブジェクト | document | edge_document_write で書いた、保存済みの JSON(またはその他のテキスト)ファイル |
| バックエンドプロキシ | proxy | 自分で運用する HTTPS オリジン |
| 関数ランタイム | wasm | edge_function_create で作成したコンパイル済みコード |
| ファイル | file | 関数が env.file で書いた公開ファイル |
/api/* を作らないでください。マッチするパスは /_api で始まる必要があります。最初に一致したものが使われます。
マップの JSON フィールドは runtime です。runtime を送るとマップ全体が置き換わるので、残したいパスはすべて含めてください。runtime だけを送る更新は、本番の /_api レーンに直接コンパイルされます。プレビュー URL も promote もありません。
エンドポイントは ウェブコンソールではまだ管理できません。データオブジェクトの書き込みとパスのマッピングは、エージェント、CLI、または API で行ってください。
共通の規則
- ルートは
document、file、proxy、wasmのいずれか ちょうどひとつ を設定します(プラットフォームのlambda許可リストを除く。GET /_api/__healthはルートなしで提供されます)。objectはdocumentの別名としてまだ受け付けます。 methodsはGET、HEAD、POST、PUT、PATCH、DELETEの許可リストです。拒否されたメソッドはAllow付きで 405 を返します。データオブジェクトのルートは GET のみ、ファイルのルートはGETとHEADのみに応答します。どちらもmethodsは省略してください。/_api/_jobs/と/_api/_uploads/はプラットフォームが予約しています。ルートでマッチさせることはできません。/_upload/{form_id}は フォームのアップロード 用の別のプラットフォームレーンで、/_apiのパスではありません。- 既定のキャッシュ TTL は、データオブジェクトが 60 秒、プロキシと関数ランタイムが 0 です。
- ボディ付きの
POSTとPUTは、そのボディの SHA-256 を小文字の hex にしたx-amz-content-sha256を送る必要があります。送らないとエッジは 400 を返します。 - distribution あたりプロキシエンドポイントは最大 100、データオブジェクトは 1,000 です。制限 を参照してください。
データオブジェクト
ファイルを書いてからマップします。マップしなくても、未マップの GET フォールバックに頼れます。
- ツール:
edge_document_list、edge_document_get、edge_document_write、edge_document_delete。HTTP:/v1/distributions/{id}/documents。書き込みボディのフィールドはdocumentsです(objectsも受け付けます)。 - バージョン履歴と切り戻しは MCP のみです。
edge_document_historyとedge_document_rollback。 - 書き込みはオブジェクトの
etagに対するif_match/if_none_matchを受け付けます。 - 未マップの
GET /_api/widgetsは、ルートが一致しなかったときデータオブジェクトwidgets.jsonを配信します。別のキーや TTL が必要なときは明示的にマップしてください。 - 未マップの
POST /_apiは 405 を返します。 - データオブジェクトにシークレットを置かないでください。訪問者に配信されます。
データオブジェクトを配信する を参照してください。
関数への付与と private オブジェクト
メンテナは、JSON ファイルを書くこととは別に、関数ランタイムへデータオブジェクトへのアクセスを付与します。付与は MCP のみです。edge_document_grant_get、edge_document_grant_set、edge_document_prefix_get、edge_document_prefix_set(function.read / function.write)。sidecar 付与は 1 キー、プレフィックス付与はその下のすべてのキーをカバーします。
- public 付与は public ストア(
edge_document_*)のオブジェクトを指します。ルートまたはフォールバックでキーを配信するとき、訪問者は引き続きGETできます。 - private 付与は private ストアを使います。訪問者はそれらのキーで常に 404 です。private JSON の投入と管理は
edge_private_document_list、edge_private_document_get、edge_private_document_write、edge_private_document_delete(function.read/function.write)です。 - public の read-write キーは
cache-control: no-storeで配信されます。
付与された関数の内側では env.document を使います。関数からデータオブジェクトを読み書きする を参照してください。
バックエンドプロキシ
パスをひとつの HTTPS URL に転送します。
- スキームは
httpsのみです。ホストは DNS 名である必要があります。IP リテラル、localhost、プライベート / リンクローカル / メタデータアドレスは使えません。 {splat}は一致しなかったパスの残りを上流 URL にコピーします。ホスト名には使えません。- 訪問者の Cookie は転送されません。リダイレクトは追いかけません。タイムアウトは 10 秒です。
- モードは
buffered(既定)またはstreamです。ストリームはヘッダー送信後に再試行しません。上流が途中で落ちると、訪問者は 200 のあとに途切れたボディを見ることがあります。 - 任意の
proxy_authは、保存した資格情報を付けます。典型的にはAuthorizationヘッダーです。訪問者には渡りません。クエリパラメータよりヘッダーを優先してください。 - 上流への接続失敗は 502 を返します。
バックエンドをプロキシする を参照してください。
関数ランタイム
自分のハンドラを WebAssembly にコンパイルしたものです。作成しても本番サイトは変わりません。wasm を script id にマップすると変わります。言語は javascript、python、rust、tinygo、c、assemblyscript です。関数ランタイム と エンドポイントを追加する を参照してください。
ファイル
file は、関数ランタイムが 公開 ファイルストアに書いたファイルを配信します。非公開のファイルはルートでは配信されず、関数が発行する有効期限の短いリンクからだけ取り出せます。
{ "match": "/_api/exports/*", "file": "exports/", "cache_ttl_seconds": 300 }/*で終わるマッチでは、fileは/で終わるキーのプレフィックスで、パスの残りが後ろに付きます。/*がなければ、fileは"brand/logo.png"のような 1 つのキーです。- 画像、PDF、プレーンテキスト、CSV、JSON、一般的な音声と動画はブラウザーで表示されます。それ以外の種類(HTML、SVG、スクリプトを含む)は、サンドボックスのコンテンツセキュリティポリシー付きの添付ファイルとしてダウンロードされます。保存したファイルがサイトのオリジンで実行されることはありません。
- 4 MiB までのファイルは直接配信します。それより大きいファイルは、5 分間有効なダウンロードリンクにリダイレクトします。
- 関数が書き込めるプレフィックスは
cache-control: no-storeで配信します。
関数からファイルを保存して配信する を参照してください。
バックグラウンドルート
wasm ルートに "background": true を付けると、すぐに 202 を返し、関数を最大 5 分間実行します。
{ "match": "/_api/reports/build", "wasm": "01M3RD5T2C8V7X1N4K6P9Q2W5Z", "methods": ["POST"], "background": true }レスポンスは {"job_id", "status": "queued", "status_url"} です。GET /_api/_jobs/{job_id} は status(queued、running、succeeded、failed)を返し、成功したら関数のレスポンスを result に、失敗したら error_code を含めます。リクエストボディの上限は 192 KiB で、distribution あたり同時に実行できるバックグラウンド実行は 5 つまでです(6 つ目は 429)。大きなファイルをバックグラウンドで生成する を参照してください。
フォームのアップロード
runtime.uploads を使うと、フォームでファイルを受け取れます。/_api のマップと同じ distribution の更新で設定し、一緒にコンパイルされ、更新がコンパイルされた時点で本番に反映されます。プレビューも promote もありません。runtime を送ると api と uploads がまとめて置き換わります。
{
"runtime": {
"uploads": {
"apply": {
"fields": {
"resume": { "types": ["application/pdf"], "max_bytes": 104857600, "max_files": 1 }
}
}
}
}
}| キー | 規則 |
|---|---|
フォーム id(apply) | 1〜64 文字。英字、数字、.、_、-。distribution あたり最大 20 フォーム |
フィールド名(resume) | 1〜64 文字。英字、数字、_、-。edge_s は不可。フォームあたり最大 10 フィールド |
types | 必須。重複不可。各値は下の一覧から |
max_bytes | 1〜5,368,709,120(5 GiB)。既定は 104,857,600(100 MiB) |
max_files | 1〜10。既定は 1 |
| 1 回の送信あたり | フィールドの max_files の合計は最大 10、max_files × max_bytes の合計は最大 10 GiB |
types に使える値:
| 種類 | 文字列 |
|---|---|
| 文書 | application/pdf、application/vnd.openxmlformats-officedocument.wordprocessingml.document、application/vnd.openxmlformats-officedocument.spreadsheetml.sheet、application/vnd.openxmlformats-officedocument.presentationml.presentation |
| アーカイブとデータ | application/zip、text/plain、text/csv、application/json |
| 画像 | image/png、image/jpeg、image/gif、image/webp、image/heic、image/avif |
| 動画 | video/mp4、video/quicktime、video/webm |
| 音声 | audio/mpeg、audio/mp4、audio/wav、audio/ogg |
HTML、SVG、スクリプト、実行ファイルは受け付けられません。
アップロードのレーン
どの呼び出しにも、訪問者のセッションを edge_s(JSON ボディのフィールドまたは edge_s Cookie)として付けます。このセッションは、あとで /_submit を呼ぶセッションと同じでなければなりません。
| リクエスト | ボディ | 応答 |
|---|---|---|
POST /_upload/{form_id} | {"field", "name", "type", "size"} | チケット。100 MiB までは {"mode": "single", "upload_id", "url", "fields", "expires_at"} で 10 分有効。それより大きい場合は {"mode": "multipart", "upload_id", "part_size", "part_count", "parts": [{"n", "length", "url"}], "expires_at"} で 1 時間有効 |
POST /_upload/{form_id}/{upload_id}/parts | {"from": 101} | 次の 100 個のパート URL |
POST /_upload/{form_id}/{upload_id}/complete | {"parts": [{"n", "etag"}]} | {"upload_id", "status": "uploaded"} |
single のチケットでは、url に multipart/form-data で POST します。fields の項目をすべて入れ、ファイルを最後に置きます。multipart のチケットのパートは 16 MiB(最後は残り)で、各 URL にはちょうど length バイトを PUT します。チケットで申告したサイズは固定されます。
| ステータス | ボディ | 原因 |
|---|---|---|
| 400 | {"error": "invalid_upload", "field", "reason"} | reason は type、size、name(空、255 文字超、スラッシュや制御文字を含む) |
| 400 | {"error": "session_required"} | edge_s がない |
| 403 | {"error": "quota_exceeded"} | 組織の今月のアップロードが 100 GiB または 50,000 ファイルに達した |
| 404 | {"error": "not_found"} | このフォームまたはフィールドにポリシーがない |
| 429 | {"error": "rate_limited"} | IP アドレスあたり 1 分に 20 枚、またはセッションあたり 1 日に 50 枚のチケット |
upload id を送信する
/_submit/{form_id} は、アップロードのフィールドの値として upload id を受け取ります。複数なら配列です。/_submit に直接ファイルのパートを送ると 400 で拒否されます。使えない値は 400 {"error": "invalid_upload", "field", "reason"} となり、何も保存されません。
reason | 原因 |
|---|---|
not_an_upload | upload id(upl_ と 26 文字)ではない |
too_many | max_files より多くの id |
duplicate | 同じ id が 2 回 |
invalid | 別のセッション、フォーム、フィールドに発行された、使用済み、またはファイルが拒否された |
not_uploaded | チケットは発行されたがファイルが届いていない |
保存された送信内容と form.submitted イベントには、files: [{"field", "upload_id", "name", "type", "size", "status"}] が入ります。
スキャン
添付された各ファイルはマルウェアスキャンされ、先頭のバイトが申告された種類と照合されます。
status | 意味 |
|---|---|
scanning | 未確定 |
clean | 読み取りとダウンロードができる |
rejected | reason は malware、type_mismatch、size_mismatch。ファイルは削除される |
scan_failed | 1 回の再試行後も判定が出ない。読み取れない |
200 MiB までの PDF、Word(.docx)、プレーンテキスト、CSV は、エージェント向けにテキスト(最大 1 MiB)が抽出されます。form.file.scanned は、添付ファイルごとにスキャンが確定した時点で 1 回送られます。送信に添付されなかったアップロードは 1 日後に削除されます。
フォームでファイルのアップロードを受け付ける と フォームの送信内容をエージェントに読ませる を参照してください。