関数ランタイム
関数ランタイムは自己完結したソースファイル 1 本で、WebAssembly にコンパイルされ、1 リクエストごとに Wasmtime で実行されます。プラットフォームに npm、pip、Cargo、Go モジュールはありません。edge_function_create の language に、下表のいずれかの値を渡してください。その言語のプラットフォームテンプレートから始めるよう、エージェントに頼んでください。
作成の手順は エンドポイントを追加する にあります。上限は 制限 です。
言語
language | 実行形態 | ABI | ツールチェーン |
|---|---|---|---|
javascript | wasm 内で解釈 | handler-v1 | Javy 9.1.0(QuickJS、ソースをスナップショットに含める) |
python | wasm 内で解釈 | handler-v1 | RustPython 0.5.0(Python 3 方言)、Wizer スナップショット |
rust | wasm にコンパイル | wasi-command-v1 | rustc --target wasm32-wasip1、std のみ |
tinygo | wasm にコンパイル | wasi-command-v1 | TinyGo -target=wasip1、GOPROXY オフ |
c | wasm にコンパイル | wasi-command-v1 | wasi-sdk clang、-std=c17 |
assemblyscript | wasm にコンパイル | wasi-command-v1 | WASI shim 付き AssemblyScript |
6 言語すべてが使えます。リクエストにヘッダー、Cookie、クエリ文字列、認証は含まれません。
handler-v1 — JavaScript と Python
トップレベルの handler(request, env) は {statusCode, headers, body}、または素の文字列(200)を返します。statusCode は 100–599、既定は 200 です。body は文字列、またはファイルを返すときはバイト列です(バイナリのボディ)。request は {method, path, body, bodyEncoding} で、body は文字列または null です。env には distribution のストア(env.document、env.kv、env.sql、env.file、env.upload)が入り、それぞれ付与で制御されます。キューの送信者で制御される env.queue と、関数の workflow_starts で制御される env.workflow もあります。バイト列には env.base64 を使います。request だけを受け取る handler も引き続き動きます。以前のグローバル edge.document は env.document と同じオブジェクトです。そのほかのストアは env にだけあります。
JavaScript は スクリプト であり、モジュールではありません。import、require、export は使えません。ライブラリは手元で esbuild yourscript.js --bundle --format=iife --outfile=bundle.js としてまとめ、bundle.js を提出してください。console.* はログに出ます。async ハンドラはマイクロタスクだけで完了します。タイマーはないため、すでに解決していないものを await すると永遠に終わりません。Math.random() は成果物ごとに同じ列を繰り返します。トークンや id には使わないでください。
function handler(request, env) {
return {
statusCode: 200,
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ method: request.method, path: request.path })
};
}Python も同じ形です(dict を返す def handler(request, env))。print() はログに出ます。import できるのは RustPython に同梱された純粋 Python の標準ライブラリだけです。それ以外の純粋 Python は 1 ファイルにベンダーしてください。C 拡張パッケージ(numpy、pandas、cryptography、lxml、pydantic_core)と socket、ssl、subprocess、threading、asyncio、http、urllib.request、ctypes はビルド時に拒否されます。RustPython は CPython ではありません。怪しい箇所は edge_function_invoke で確認してください。async def handler は何もサスペンドしない場合にだけ動きます。イベントループはありません。
import json
def handler(request, env):
return {
"statusCode": 200,
"headers": {"content-type": "application/json"},
"body": json.dumps({"method": request["method"], "path": request["path"]}),
}wasi-command-v1 — Rust、TinyGo、C、AssemblyScript
プログラムは main です(AssemblyScript はトップレベル)。stdin は JSON オブジェクト 1 個 {"method","path","body","bodyEncoding"} です。method と path は argv[1] / argv[2] および $METHOD / $PATH にもあります。stdout に {"statusCode","headers","body"} をちょうど 1 つ書き、exit 0 してください。stdout にそれ以外がある場合、または非ゼロ終了の場合、訪問者には汎用の 500 になります。stderr はログです。headers は文字列のオブジェクト、body は文字列です。ファイルを返すときは "bodyEncoding":"base64" を付け、body に base64 を入れます(バイナリのボディ)。
標準ライブラリのみです。
- Rust — Cargo なし、クレートなし、serde なし。
include!、include_str!、include_bytes!、ファイル外のmod name;は拒否されます。モジュールはインラインである必要があります。 - TinyGo — Go モジュールなし、cgo なし。
encoding/jsonは使えます。プレーンな struct を優先してください。 - C — wasi-sdk の sysroot からの
#include <header.h>のみ。引用符付き include、#embed、.incbinは拒否されます。 - AssemblyScript — 標準ライブラリと WASI-shim のグローバルのみ。標準ライブラリに JSON はありません。
バイナリのボディ
関数はファイルを受け取り、ファイルを返せます。PDF の領収書、CSV のエクスポート、生成した画像などです。
リクエスト。 bodyEncoding で body の読み方がわかります。
bodyEncoding | 条件 | body |
|---|---|---|
"utf8" | リクエストの content-type がテキスト(text/*、JSON、XML、フォーム)か未指定で、バイト列が正しい UTF-8 | そのテキスト |
"base64" | それ以外(image/png、application/pdf など) | バイト列そのままの base64 |
null | ボディなし | null |
リクエストボディの上限は 1 MiB のままです。大きなファイルは関数に POST せず、フォームのアップロードを使ってください。
レスポンス。 content-type ヘッダーを付けてバイト列を返します。
| 言語 | 返すもの |
|---|---|
| JavaScript | body に Uint8Array か ArrayBuffer |
| Python | body に bytes か bytearray |
| Rust、TinyGo、C、AssemblyScript | "bodyEncoding":"base64" と、body に base64 |
どの言語でも、bodyEncoding: "base64" と base64 の文字列を返すこともできます。バイナリのボディには content-type ヘッダーが必須で、ないと訪問者には汎用の 500 になります。デコード後のボディは 4 MiB まで返せます(テキストのボディは 1 MiB のままです)。
function handler(request) {
const csv = new TextEncoder().encode('id,total\n1,42\n');
return {
headers: {
'content-type': 'text/csv',
'content-disposition': 'attachment; filename="report.csv"',
},
body: csv,
};
}サンドボックスの JavaScript には Buffer、btoa、atob がありません。env.base64.encode(bytes) と env.base64.decode(text)(Uint8Array を返します)を使ってください。Python は標準ライブラリの base64 が使えます。
バイト列を返す処理はサイズにかかわらず軽量です。JavaScript と Python のハンドラーはバイト列をそのままメモリーとしてプラットフォームに渡し、エンコードはプラットフォームが行うため、4 MiB のボディでも 4 バイトとほぼ同じ燃料(fuel)で済みます。一方、バイト列を作る処理はハンドラー自身の仕事なので燃料を使います。JavaScript や Python で 1 バイトずつループするのは高コストですが、new Uint8Array(n)、TextEncoder、bytes(n)、bytearray(n) は軽量です。ルートを割り当てる前に、大きな出力は edge_function_invoke で確認してください。
関数からのファイル
env.file は、CSV、PDF、画像、アーカイブなどのファイルを distribution のファイルストアに読み書きします。アクセスはソースの外で edge_file_prefix_set によりキーのプレフィックス単位で付与するので、関数が自分のアクセス範囲を広げることはできません。付与のないキーは not_granted で拒否されます。
| JavaScript | Python | 戻り値 |
|---|---|---|
put(key, bytes | string, {contentType, ifMatch}) | put(key, data, content_type=..., if_match=None) | {etag, size} |
get(key) | get(key) | {bytes, contentType, etag, size}、または null / None |
head(key) | head(key) | {contentType, etag, size}、または null / None |
read(key, {offset, length}) | read(key, offset=0, length=...) | 範囲。形は get と同じ |
list(prefix, {cursor}) | list(prefix, cursor=None) | {items, cursor} |
delete(key) | delete(key) | {deleted: true} |
create(key, {contentType}) | create(key, content_type=...) | ライター(append、commit、abort) |
link(key, {ttlSeconds, disposition}) | link(key, ttl_seconds=900, disposition=...) | {url, expiresIn} |
putはキーを新しく作ります。既存のキーを置き換えるには、現在の etag をifMatchに渡します。渡さないとprecondition_failedです。- 1 回の呼び出しで動かせるのは 4 MiB までです。
getはそれより大きいファイルを拒否します。readで少しずつ読むか、create、append、commitで 5 GiB まで書いてください。 put、get、head、list、delete、create、commit、linkは、env.documentと共通の「呼び出しあたり 8 回」のホスト呼び出しを使います。appendとreadは回数ではなくバイト数で制限されます。呼び出しあたり 512 MiB、バックグラウンドルートでは 5 GiB です。- ハンドラーの終了時に開いたままのライターは破棄されます。プラットフォームは
fetchのたびにハンドラーを再実行するので、fetch は書き込みを始める前に済ませてください。 linkは 60〜3,600 秒(既定 900 秒)有効なダウンロード URL を返します。その場で開くのは画像、PDF、テキスト、CSV、JSON、音声、動画だけで、それ以外はダウンロードされます。- エラーは、JavaScript では
.code付きのError、Python では.code付きのFileErrorとして送出されます。not_granted、not_found、precondition_failed、too_large、quota_exceeded、budget_exhausted、invalid_key、writer_closedです。
バイト列は再エンコードなしでハンドラーとプラットフォームの間を移動するので、ファイルを動かす燃料はサイズにほぼ関係しません。関数からファイルを保存して配信する を参照してください。
関数で受け付ける訪問者のアップロード
env.upload(handler(request, env) の env 引数。Python では def handler(request, env))を使うと、関数は 1 人の訪問者に、ファイルをストレージへ直接アップロードするためのチケットを渡せます。ファイルはマルウェアスキャンされ、先頭のバイトが申告された種類と照合されます。関数がファイルを読んだりファイルストアに保存したりできるのは、clean になってからです。署名する前に訪問者を確認してください。関数は Cookie や身元を受け取らないので、サインインした訪問者だけにアップロードを許すときは、distribution を訪問者のサインインの後ろに置きます。
アップロードは、メンテナーが script ごとに edge_function_upload_grant_set(distribution_id、script_id、enabled)で有効にします。この付与はソースの外に保存され、MCP だけで設定できます。対応する HTTP ルートや CLI コマンドはありません。edge_file_prefix_get は、付与された script を upload_scripts として返します。付与がないと、すべての呼び出しが not_granted で失敗します。
| JavaScript | Python | 戻り値 |
|---|---|---|
sign({contentType, size}) | sign(content_type, size) | チケット(下記) |
parts(uploadId, from) | parts(upload_id, start) | {upload_id, parts}。パート from から最大 100 件の追加のパート URL |
complete(uploadId, [{n, etag}]) | complete(upload_id, parts) | {upload_id, status: "uploaded"} |
status(uploadId) | status(upload_id) | {status, reason, contentType, size}(Python では content_type) |
read(uploadId, {offset, length}) | read(upload_id, offset=0, length=None) | {bytes, contentType, size}(Python では content_type) |
keep(uploadId, key) | keep(upload_id, key) | {key, size, etag, contentType}(Python では content_type) |
チケットは /_upload レーンと同じ形です。訪問者のページが読むので、フィールド名はスネークケースです。
mode | チケット | ページが次に行うこと |
|---|---|---|
single(100 MiB まで) | {upload_id, mode, url, fields, expires_in} | url に multipart/form-data で POST します。fields のすべての項目を先に、ファイルを最後に入れます。有効期間は 10 分です。 |
multipart(それより大きい場合) | {upload_id, mode, part_size, part_count, parts: [{n, length, url}], expires_in} | 各パート URL にちょうど length バイトを PUT し、すべてのパートの ETag を関数に送り返します。関数が complete を呼びます。パートは 16 MiB で、最初の 100 件の URL はチケットに含まれます。各 URL の有効期間は 1 時間です。 |
status は次のいずれかです。
status | 意味 |
|---|---|
pending | 署名済みだが、ファイルがまだ届いていない |
scanning | 届いたが、スキャンがまだ終わっていない |
clean | マルウェアがなく、先頭のバイトが申告された種類と一致する |
rejected | reason は malware または type_mismatch |
scan_failed | 判定が出なかった。このファイルは読み取りも保存もできない |
contentTypeは、フォームのアップロードと同じ許可リストにある必要があります。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、スクリプト、実行ファイルはtype_not_allowedで失敗します。sizeは 1 バイト〜5 GiB です(超えるとtoo_large)。ストレージはちょうどその長さのバイト列だけを受け付けるので、ブラウザーは申告したサイズのとおりに送る必要があります。- アップロードを確認できるのは、署名した script だけです。ほかの script では
not_foundになります。 readとkeepはcleanのアップロードでだけ動きます。それより前はnot_cleanで失敗します。中身が申告された種類でないファイルはtype_mismatchで失敗します。readは 1 回の呼び出しで最大 4 MiB を返します。keepは、env.fileのプレフィックス付与の下へアップロードをファイルストアにコピーします。キーを新しく作るだけで、既存のキーは置き換えません(precondition_failed)。コピーはファイルストアの上限に数えられます。公開プレフィックスならfileルートで配信できます。画像、PDF、テキスト、CSV、JSON、音声、動画はブラウザーで開き、それ以外の種類はダウンロードされます。- 保存(keep)されなかったアップロードは 1 日後に削除されます。
sign、parts、complete、status、keepは、env.documentとenv.fileと共通の「呼び出しあたり 8 回」のホスト呼び出しを使います。readは回数ではなく、ファイルの読み込みのバイト数に数えられます。- アップロードは、フォームのアップロードと共通の、組織の月間アップロード上限(1 か月に 100 GiB、50,000 ファイル)に数えられます。使用量はアップロードが届いた時点で計測されるので、上限を超えた直後に数件が通ることがあります。その後は
signがquota_exceededで失敗します。 - エラーは、JavaScript では
.code付きのError、Python では.code付きのUploadErrorとして送出されます。not_granted、type_not_allowed、too_large、quota_exceeded、not_found、not_clean、type_mismatch、invalid_parts、precondition_failed、budget_exhausted、invalid_request、unavailableです。invalid_partsは、completeに渡したパートの一覧が欠けている、順番が違う、またはストレージが受け取った内容と一致しないことを意味します。
エージェントは、同じ規則を edge://runtime/functions の uploads セクションと、edge://limits の function_uploads で読みます。サインインした訪問者に画像をアップロードさせる を参照してください。
外向き HTTPS
サンドボックスにソケットはありません。HTTPS はホスト経由です。ポート 443、DNS 名(IP リテラル不可)、リダイレクトなし、プライベート / リンクローカル / メタデータアドレス不可、訪問者やプラットフォームの資格情報は使いません。呼び出しあたり最大 4 回、各 2 秒、リクエスト 64 KiB、レスポンス 256 KiB です。毎回同じ引数を同じ順で呼んでください。プラットフォームがハンドラをリプレイします。
| 言語 | 方法 |
|---|---|
| JavaScript | handler 内のみ: fetch(url, {method, headers, body}) → {ok, status, contentType, body, error} |
| Python | handler 内: fetch(url, method="GET", headers=None, body=None) — 同じ戻りオブジェクト。urllib / http は拒否されたまま |
| Rust、TinyGo、C、AssemblyScript | stdout にオブジェクト 1 つ {"fetch":{"method","url","headers","body"}} を書いて exit 0。リプレイの stdin に fetchResults が含まれます。メソッド: GET、HEAD、POST |
ok は、プラットフォームが URL を拒否した場合や呼び出しが失敗した場合に false です。error は短い公開メッセージであり、上流のボディではありません。自分で設定するオリジンには、代わりに プロキシエンドポイント を使ってください。
バックグラウンドジョブ
関数は訪問者のリクエストなしに バックグラウンドジョブ としても実行できます。成果物もハンドラも同じです。/_jobs/{kind}/{name}(kind は cron、queue、workflow)への POST として、JSON 文字列のボディを受け取ります。
{"type":"cron","job_id":"job_01M4X7T2K9Q0V3B8N6C5D1E2F3","attempt":1,"distribution_id":"d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38"}いつもと同じエンベロープで応答します。2xx は成功、5xx は再試行され、4xx は再試行せず失敗になります。ジョブは複数回実行されることがあるので、副作用は job_id をキーにしてください。
ジョブはより長い予算を持つ別のバックグラウンドランナーで動きます。既定 300 秒、background_timeout_seconds で最大 840 秒、256 MiB、外向き呼び出し 100 回です。訪問者のリクエストがここに届くことはありません。上限 と 関数をバックグラウンドジョブとして試す を参照してください。
関数からのデータオブジェクト
handler コードは、同一 distribution 上のデータオブジェクトを env.document 経由で読み書きできます。付与はソースの外で edge_document_grant_set と edge_document_prefix_set(function.write)で設定します。関数は自分の付与を編集できません。document.write では付与を設定できません。
| メソッド | 戻り値 |
|---|---|
get(key) | {body, etag} |
put(key, body, ifMatch?) | {etag} |
list(prefix, cursor?) | {keys, cursor} — 1 ページ最大 50 キー |
delete(key) | {deleted: true} |
JavaScript は .code 付きの Error、Python は .code 付きの DocumentError を投げます。付与がないとき、get はキーがなくても denied になります。public オブジェクトは edge_document_write で書くキーと同じです。private オブジェクトは GET /_api では配信されません。edge_private_document_* で管理し、関数が env.document を呼べるよう private 付与を付けます。
1 invocation あたり document 呼び出しは最大 8 回、各 body は 1 MiB 上限です。read-write 付与の public キーは訪問者向けに cache-control: no-store で配信されます。
Rust、TinyGo、C、AssemblyScript は同じ JSON 操作で deca:document call を import できます。JavaScript と Python は上記の env.document を使います。
関数からデータオブジェクトを読み書きする を参照してください。
関数からのキュー
env.queue は同じ distribution の キュー にメッセージを送ります。関数が送れるのは、senders にその script id か "*" が入っているキューだけです。senders は edge_queue_create か edge_queue_update(queue.write)で設定します。関数のコードからは変えられません。
| メソッド | 戻り値 |
|---|---|
send(queue, body, {delaySeconds?, idempotencyKey?}) | {id} |
sendBatch(queue, [{body, delaySeconds?, idempotencyKey?}, …]) | {ids} |
Python では send(queue, body, delay_seconds=None, idempotency_key=None) と send_batch(queue, [{"body": …, "delay_seconds": …, "idempotency_key": …}]) で、.code 付きの QueueError を送出します。JavaScript は .code 付きの Error を投げます。コードは denied(送信者でない)、not_found(その名前のキューがない)、queue_full、rate_limited、too_large、invalid_request、unavailable です。
送信はメッセージが保存された時点で返り、キューのコンシューマーがあとでバックグラウンドランナーで処理します。リクエストランナーの関数は 1 回の呼び出しで 10 件、バックグラウンドジョブは 100 件まで送れます。キューへの送信は 8 回のストア呼び出しには数えません。idempotencyKey のない送信には呼び出しごとのキーが付くので、fetch を使う関数が最初から実行し直されても送信は重複しません。
Rust、TinyGo、C、AssemblyScript は edge:queue の call を import し、{"op": "send", "queue", "body", "delay_seconds"?, "idempotency_key"?} または {"op": "send_batch", "queue", "messages": [...]} を渡して、{"ok": true, "id"}、{"ok": true, "ids"}、{"ok": false, "error"} を受け取ります。
関数からのワークフロー
env.workflow は同じ distribution の ワークフロー実行 を開始し、シグナルを送り、状態を読みます。
| メソッド | 戻り値 |
|---|---|
start(name, input, {scriptId?, idempotencyKey?}) | {runId, created} |
signal(runId, name, payload, {idempotencyKey?}) | {delivered} |
get(runId) | {run_id, name, status, step, waiting_for, output?, error?} |
start は、scriptId で別の関数を指定しない限り、呼び出した関数自身のスクリプトを実行します。別の関数を開始できるのは、そのスクリプトが自分の workflow_starts 付与に入っているときだけです。付与は edge_function_update(distribution_id, script_id, workflow_starts=[…])(function.write)で設定します。["*"] は distribution のすべての関数を許し、[] は付与を消します。関数のコードからは変えられません。
signal と get が届くのは、その関数が開始した実行と、その関数が開始できるスクリプトの実行です。ワークフローのステップは子の実行を開始できますが、自分の実行にシグナルは送れません。実行を進めるのはステップの答え(next、sleep、wait)です。実行がまだそのシグナルを待っていないとき delivered は false になり、Edge は実行が待つまでシグナルを保持します。
Python では start(name, input=None, script_id=None, idempotency_key=None)({"run_id", "created"} を返します)、signal(run_id, name, payload=None, idempotency_key=None)、get(run_id) です。失敗すると .code 付きの WorkflowError を送出します。JavaScript は .code 付きの Error を投げます。
| コード | 意味 |
|---|---|
denied | 付与がそのスクリプトや実行を含まない、またはステップが自分の実行にシグナルを送った |
not_found | この distribution にその関数や実行がない |
run_finished | 実行はすでに完了、失敗、またはキャンセルされている |
limit_reached | distribution の実行中の実行がすでに 1000 件ある |
rate_limited | この呼び出しの上限を使い切った |
too_large | input または payload が 256 KiB を超える |
invalid_request | 名前、id、キーの形式が正しくない |
unavailable | Edge が呼び出しを受け付けられなかった。後で再試行する |
リクエストランナー上の関数は 1 回の呼び出しで env.workflow を 10 回、バックグラウンドジョブは 50 回まで呼べます。8 回のストア呼び出しには数えません。idempotencyKey のない start と signal には呼び出しから決まるキーが付くので、fetch する関数が最初から再実行されても、二重に開始やシグナル送信はしません。再試行されたジョブは新しい呼び出しなので新しいキーになります。再試行をまたいで実行をちょうど 1 回だけ開始するには、自分の idempotencyKey を渡します。
Rust、TinyGo、C、AssemblyScript は edge:workflow の call を import し、{"op": "start", "name"?, "input"?, "script_id"?, "idempotency_key"?}、{"op": "signal", "run_id", "name", "payload"?, "idempotency_key"?}、{"op": "get", "run_id"} を渡して、{"ok": true, "run_id", "created"}、{"ok": true, "delivered"}、{"ok": true, "run"}、{"ok": false, "error"} を受け取ります。
ランタイムログを見る
edge_function_logs は直近の呼び出しを新しい順で返します。訪問者のリクエスト、直接の edge_function_invoke テスト、関数を実行したフック、バックグラウンドジョブを対象にし、次を含みます。
- キャプチャした stdout と stderr
- fuel、メモリ、所要時間
- 発生した場合のランタイムエラー
ISO 8601 の since タイムスタンプ、source(visitor、invoke、hook、cron、queue、workflow)、job_id で絞り込めます。1 ページは最大 50 行、キャプチャの保持期間は 7 日です。
stdout に書いたレスポンスのエンベロープはログ行としては保存されません。Edge は関数ログにリクエストボディ、クエリ文字列、ヘッダー、Cookie も記録しません。自分の console.*、print()、stderr 出力には訪問者のデータが入りうるので、個人データやシークレットはログに出さないでください。
ビルド失敗は別です。edge_function_get は build_log を返し、上限は 32 KiB です。公開パスにマップする前に edge_function_invoke を使ってください。stdout、stderr、fuel、メモリ、エラーがすぐに返ります。