Skip to content

関数ランタイム ​

関数ランタイムは自己完結したソースファイル 1 本で、WebAssembly にコンパイルされ、1 リクエストごとに Wasmtime で実行されます。プラットフォームに npm、pip、Cargo、Go モジュールはありません。edge_function_create の language に、下表のいずれかの値を渡してください。その言語のプラットフォームテンプレートから始めるよう、エージェントに頼んでください。

作成の手順は エンドポイントを追加する にあります。上限は 制限 です。

言語 ​

language実行形態ABIツールチェーン
javascriptwasm 内で解釈handler-v1Javy 9.1.0(QuickJS、ソースをスナップショットに含める)
pythonwasm 内で解釈handler-v1RustPython 0.5.0(Python 3 方言)、Wizer スナップショット
rustwasm にコンパイルwasi-command-v1rustc --target wasm32-wasip1、std のみ
tinygowasm にコンパイルwasi-command-v1TinyGo -target=wasip1、GOPROXY オフ
cwasm にコンパイルwasi-command-v1wasi-sdk clang、-std=c17
assemblyscriptwasm にコンパイルwasi-command-v1WASI 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 には使わないでください。

javascript
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 は何もサスペンドしない場合にだけ動きます。イベントループはありません。

python
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 ヘッダーを付けてバイト列を返します。

言語返すもの
JavaScriptbody に Uint8Array か ArrayBuffer
Pythonbody に bytes か bytearray
Rust、TinyGo、C、AssemblyScript"bodyEncoding":"base64" と、body に base64

どの言語でも、bodyEncoding: "base64" と base64 の文字列を返すこともできます。バイナリのボディには content-type ヘッダーが必須で、ないと訪問者には汎用の 500 になります。デコード後のボディは 4 MiB まで返せます(テキストのボディは 1 MiB のままです)。

javascript
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 で拒否されます。

JavaScriptPython戻り値
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 で失敗します。

JavaScriptPython戻り値
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マルウェアがなく、先頭のバイトが申告された種類と一致する
rejectedreason は 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 です。毎回同じ引数を同じ順で呼んでください。プラットフォームがハンドラをリプレイします。

言語方法
JavaScripthandler 内のみ: fetch(url, {method, headers, body}) → {ok, status, contentType, body, error}
Pythonhandler 内: fetch(url, method="GET", headers=None, body=None) — 同じ戻りオブジェクト。urllib / http は拒否されたまま
Rust、TinyGo、C、AssemblyScriptstdout にオブジェクト 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 文字列のボディを受け取ります。

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_reacheddistribution の実行中の実行がすでに 1000 件ある
rate_limitedこの呼び出しの上限を使い切った
too_largeinput または payload が 256 KiB を超える
invalid_request名前、id、キーの形式が正しくない
unavailableEdge が呼び出しを受け付けられなかった。後で再試行する

リクエストランナー上の関数は 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、メモリ、エラーがすぐに返ります。

あわせて読む ​