Skip to content

エンドポイント ​

エンドポイント は distribution 上の /_api パスです。コンソールではこの面を Endpoints と呼びます。各パスの行き先は次のいずれかひとつです。

種類ルートのフィールド配信するもの
データオブジェクトdocumentedge_document_write で書いた、保存済みの JSON(またはその他のテキスト)ファイル
バックエンドプロキシproxy自分で運用する HTTPS オリジン
関数ランタイムwasmedge_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 は、関数ランタイムが 公開 ファイルストアに書いたファイルを配信します。非公開のファイルはルートでは配信されず、関数が発行する有効期限の短いリンクからだけ取り出せます。

json
{ "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 分間実行します。

json
{ "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 がまとめて置き換わります。

json
{
  "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_bytes1〜5,368,709,120(5 GiB)。既定は 104,857,600(100 MiB)
max_files1〜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_uploadupload id(upl_ と 26 文字)ではない
too_manymax_files より多くの id
duplicate同じ id が 2 回
invalid別のセッション、フォーム、フィールドに発行された、使用済み、またはファイルが拒否された
not_uploadedチケットは発行されたがファイルが届いていない

保存された送信内容と form.submitted イベントには、files: [{"field", "upload_id", "name", "type", "size", "status"}] が入ります。

スキャン ​

添付された各ファイルはマルウェアスキャンされ、先頭のバイトが申告された種類と照合されます。

status意味
scanning未確定
clean読み取りとダウンロードができる
rejectedreason は malware、type_mismatch、size_mismatch。ファイルは削除される
scan_failed1 回の再試行後も判定が出ない。読み取れない

200 MiB までの PDF、Word(.docx)、プレーンテキスト、CSV は、エージェント向けにテキスト(最大 1 MiB)が抽出されます。form.file.scanned は、添付ファイルごとにスキャンが確定した時点で 1 回送られます。送信に添付されなかったアップロードは 1 日後に削除されます。

フォームでファイルのアップロードを受け付ける と フォームの送信内容をエージェントに読ませる を参照してください。

あわせて読む ​