エンドポイントを追加する
エンドポイントは、distribution 上の /_api パスです。関数ランタイムを実行することも、データオブジェクト を配信することも、自分で運用する バックエンドへプロキシ することもできます。コンソールではこの面を Endpoints と呼びます。種類は エンドポイント にあります。
このページでは 関数ランタイム を追加します。自分のハンドラを WebAssembly にコンパイルし、1 リクエストずつサンドボックスで実行します。作成しただけでは本番サイトは変わりません。エンドポイントに割り当てたときに変わります。
関数ランタイムは ウェブコンソールではまだ管理できません。作成用の HTTP API もありません。エージェントに指示してください。公開パスの割り当てだけが例外で、それは distribution の更新なので curl でも行えます。
このページは、すでに公開中の distribution があることを前提とします。まだの場合は 最初のサイトを公開する から始めてください。以降、その distribution は acme-marketing(d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38)とします。
1. ファイルを 1 つ書く
ソースは自己完結した単一ファイルである必要があります。ビルド時に Edge は npm も pip も実行しないため、自分でバンドルしていない限り import と require は失敗します。
このチュートリアルでは JavaScript を使います。ハンドラは {method, path, body} を受け取り、{statusCode, headers, body} を返します。body は文字列または null です。path にクエリ文字列は含まれません。console.log と console.error は訪問者ではなくログに出ます。
function handler(request, env) {
return {
statusCode: 200,
headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
body: JSON.stringify({
ok: true,
method: request.method,
path: request.path
})
};
}ライブラリを含める場合は、先にローカルでバンドルしてください。
esbuild echo.js --bundle --format=iife --outfile=bundle.jsesm ではなく iife を使います。提出したソースに export があるとビルドエラーになります。
ほかの言語は python、rust、tinygo、c、assemblyscript です。Python も同じ handler(request, env) の形です。コンパイル言語は stdin から JSON オブジェクトを 1 つ読み、stdout に JSON エンベロープを 1 つ書き出します。言語の ABI、ツールチェーン、fetch の規則は 関数ランタイム にあります。その言語のプラットフォームテンプレートから始めるよう、エージェントに頼んでください。
2. 作成する
acme-marketing の distribution で、echo.js から JavaScript の
関数ランタイムを作って。公開の /_api パスはまだ割り当てないで。
script id と、ビルドが成功したタイミングを教えて。エージェントは edge_function_create を実行します。応答はすぐ返ります。script_id(ULID)、status: pending、job_id です。本番サイトは変わりません。
このチュートリアルでは script id を 01M2QG8K4N7R9T1V3W5X7Y9ZAB とします。実際の値は異なります。
3. ビルドを待つ
ビルドが終わるまでポーリングするよう、エージェントに頼んでください。エージェントは edge_function_get を実行します。
succeeded— 呼び出せます。failed—build_logを読んでください。ソースの行が示されます。ファイルを直して更新してください。同じハンドラのために関数ランタイムを 2 つ作らないでください。
割り当て済みのパスは、ビルドが成功するまで 503 を返します。だからこのページでは、URL を公開する前に呼び出します。
4. URL なしで試す
acme-marketing の script 01M2QG8K4N7R9T1V3W5X7Y9ZAB を
GET /_api/echo で invoke して、body、stderr、fuel、memory を見せて。エージェントは edge_function_invoke を実行します。invoke はランナーに直接話します。エンドポイントのマップは見ないため、/_api/echo の割り当てがなくても失敗にはなりません。パスの methods リストも適用されません。
入力を省略した場合の既定は、ボディなしの GET /_api/_invoke です。渡せるのは {method, path, body} と、バイナリのボディで試すときの body_encoding: "base64" だけです(関数からファイルを返す)。ヘッダー、Cookie、クエリ文字列、認証は拒否されます。サンドボックスが受け取ることはありません。
5. /_api に載せる
訪問者が見る内容が変わりうる手順です。最初のサイトを公開する のように、すでに公開中の distribution から始めてください。
エンドポイントマップの JSON フィールドは runtime です。runtime を送るとマップ全体が置き換わります。ほかの /_api パスがある場合は、同じ更新に含めないと消えます。
acme-marketing の GET /_api/echo を script
01M2QG8K4N7R9T1V3W5X7Y9ZAB に割り当てて。既存のエンドポイントは
すべて残して。新しい deployment を promote しないで。これは
エンドポイントの更新です。edge api PATCH /v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 --input - <<'EOF'
{
"runtime": {
"api": {
"routes": [
{
"match": "/_api/echo",
"wasm": "01M2QG8K4N7R9T1V3W5X7Y9ZAB",
"methods": ["GET"],
"cache_ttl_seconds": 0
}
]
}
}
}
EOFcurl -s -X PATCH \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"runtime": {
"api": {
"routes": [
{
"match": "/_api/echo",
"wasm": "01M2QG8K4N7R9T1V3W5X7Y9ZAB",
"methods": ["GET"],
"cache_ttl_seconds": 0
}
]
}
}
}'エージェントは edge_distribution_update を実行します。runtime だけを送る更新は、公開中の /_api レーンに直接載ります。プレビュー URL も promote もありません。関数ランタイムの既定は cache_ttl_seconds: 0 なので、ある訪問者の応答が次の訪問者に出ることはありません。
マッチするパスは /_api で始まる必要があります。/api/* を作らないでください。
そのあと https://acme-marketing.edge.deca-dev.com/_api/echo を開きます。同じオリジンのページからは fetch("/_api/echo") で足ります。ボディ付きの POST と PUT は、そのボディの小文字 hex SHA-256 を x-amz-content-sha256 として送る必要があります。そうしないとエッジは 400 を返します。
6. 出力を読む
acme-marketing の script 01M2QG8K4N7R9T1V3W5X7Y9ZAB の
ログを最新 20 行見せて。エージェントは edge_function_logs を実行します。行は訪問者のリクエスト、自分の invoke、関数ランタイムを実行したフックを、新しい順で、7 日間保持します。有効な応答エンベロープである stdout は捨てられます。それは訪問者のボディだったからです。リクエストボディ、クエリ文字列、ヘッダー、Cookie は保存されません。
個人データを出力しないでください。ハンドラが訪問者のフィールドをログに出すと、そのフィールドがキャプチャに残ります。
変更するか、止めるか
ソースを更新しても script_id は同じで、新しいビルドがキューに入ります。新しいビルドが成功するまで、公開パスは以前成功した成果物で動き続けます。エージェントは edge_function_update を実行します。
コンパイル済みのエンドポイントがまだその script_id を指しているあいだは、削除は失敗します。先に wasm パスを外してから削除してください。エージェントは edge_function_delete を実行します。
つまずきやすい点
- サンドボックスにはソケット、ファイルシステム、環境、タイマーがありません。 外向きの HTTPS はホスト経由です(JavaScript または Python ハンドラ内の
fetch)。1 回の実行につき最大 4 回、ポート 443、DNS 名、リダイレクトなし、プライベートアドレスなしです。プライベートな上流に届けるには、依然としてプロキシエンドポイントを使います。 Math.random()は 同じ JavaScript 成果物では繰り返されます。トークンや id に使わないでください。- fuel、メモリ、時間には上限があります。 ループしすぎたり待ちすぎたりしたハンドラは、そのリクエストに失敗します。制限 を参照してください。
次に読む
- 関数ランタイム — 言語、ABI、fetch
- データオブジェクトを配信する
- バックエンドをプロキシする
- エンドポイント
- 制限