Request

Request ↗ インターフェースは HTTP リクエストを表し、Fetch API の一部です。

Request オブジェクトに最もよく出会うのは、受信リクエストのプロパティとしてです。

export default {
	async fetch(request, env, ctx) {
		return new Response('Hello World!');
	},
};

リクエストオブジェクトを変更したい場合は、自分で Request を構築することもあります。fetch() ハンドラー から受け取る受信 request パラメーターは不変だからです。

export default {
	async fetch(request, env, ctx) {
        const url = "https://example.com";
        const modifiedRequest = new Request(url, request);
		// ...
	},
};

fetch() ハンドラー は Request コンストラクターを呼び出します。以下で定義する RequestInit と RequestInitCfProperties は、fetch() ハンドラー に渡せる有効なパラメーターも表します。

let request = new Request(input, options)

• input string | Request

  • URL を含む文字列、または既存の Request オブジェクトです。

• options options 任意

  • Request に適用する設定を含む、任意の options オブジェクトです。

リクエストに適用したいプロパティを含むオブジェクトです。

• cache undefined | 'no-store' | 'no-cache' 任意

  • 標準の HTTP cache ヘッダーです。サポートされるのは cache: 'no-store' と cache: 'no-cache' だけです。 それ以外の cache ヘッダーは、メッセージ Unsupported cache mode: <attempted-cache-mode> の TypeError になります。

• cf RequestInitCfProperties 任意

  • Request に設定できる Cloudflare 固有のプロパティです。Cloudflare グローバルネットワークがリクエストをどう扱うかを制御します。

• method string 任意

  • HTTP リクエストメソッドです。デフォルトは GET です。Workers では CONNECT ↗ を除くすべての HTTP リクエストメソッド ↗ をサポートします。

• headers Headers 任意

  • Headers オブジェクト ↗ です。

• body string | ReadableStream | FormData | URLSearchParams 任意

  • リクエストボディがある場合のボディです。
  • GET または HEAD メソッドのリクエストにはボディを付けられません。

• redirect string 任意

  • 使うリダイレクトモードです。follow、error、manual のいずれかです。新しい Request オブジェクトのデフォルトは follow です。ただし、FetchEvent の受信 Request プロパティのリダイレクトモードは manual です。

• signal AbortSignal 任意

  • 指定すると、対応する AbortController で abort をトリガーしてリクエストをキャンセルできます。

Request オブジェクトに設定できる Cloudflare 固有のプロパティを含むオブジェクトです。例:

// Disable ScrapeShield for this request.
fetch(event.request, { cf: { scrapeShield: false } })

cf オブジェクトの無効なキーや誤った名前のキーは、黙って無視されます。cf オブジェクトを正しく使うには、TypeScript を使い、wrangler types で型を生成することを検討してください。

• apps boolean 任意

  • このリクエストで Cloudflare Apps ↗ を有効にするかどうかです。デフォルトは true です。

• cacheEverything boolean 任意

  • すべてのコンテンツを静的として扱い、Cloudflare のデフォルトキャッシュ対象を超える ファイル種別 もキャッシュします。オリジン Web サーバーのキャッシュヘッダーは尊重します。Page Rule の Cache Level（Cache Everything） を設定するのと同等です。デフォルトは false です。 このオプションは GET と HEAD リクエストメソッドにだけ適用されます。

• cacheKey string 任意

  • リクエストのキャッシュキーは、キャッシュの目的で 2 つのリクエストが同じかどうかを決めます。あるリクエストが以前のリクエストと同じキャッシュキーを持つ場合、Cloudflare は両方に同じキャッシュ済みレスポンスを返せます。

• cacheTags Array<string> 任意

  • このオプションは、オリジンサーバーからのレスポンスに追加の Cache-Tag ヘッダーを付けます。オリジンサーバーを変更せず、Worker が付けたタグに基づいてキャッシュ済みコンテンツをパージできます。Purge by Tag 機能で行います。

• cacheTtl number 任意

  • レスポンスで見えたヘッダーに関係なく、このリクエストのレスポンスを Cloudflare にキャッシュさせます。2 つの Page Rule、Edge Cache TTL と Cache Level（Cache Everything） を設定するのと同等です。値は 0 または正の数である必要があります。0 はキャッシュアセットが直ちに期限切れになることを示します。このオプションは GET と HEAD リクエストメソッドにだけ適用されます。

• cacheTtlByStatus { [key: string]: number } 任意

  • レスポンスのステータスコードに基づいて TTL を選ぶ、cacheTtl の別バージョンです。このリクエストへのレスポンスのステータスコードが一致する場合、Cloudflare は指示された時間キャッシュし、オリジンが送ったキャッシュ指示を上書きします。例: { "200-299": 86400, "404": 1, "500-599": 0 }。値は 0 と負の整数を含む任意の整数です。0 はキャッシュアセットが直ちに期限切れになることを示します。負の値は、Cloudflare に一切キャッシュしないよう指示します。このオプションは GET と HEAD リクエストメソッドにだけ適用されます。

• vary RequestInitCfPropertiesVary 任意

  • 単一の fetch() リクエストについて、Vary ヘッダー付きのオリジンレスポンスを Cloudflare がどうキャッシュするかを制御します。cf.vary と Cache Rules Vary の両方がある場合、このサブリクエストでは cf.vary が優先されます。

• image Object | null 任意

  • このリクエストで Image Resizing を有効にします。取りうる値は Workers 経由で画像を変換する のドキュメントを参照してください。

• polish string 任意

  • Polish ↗ モードを設定します。取りうる値は lossy、lossless、off です。

• resolveOverride string 任意

  • DNS ルックアップを上書きして、リクエストを別のオリジンサーバーへ向けます。resolveOverride の値は、URL に指定したホスト名ではなく、オリジン IP アドレスの決定に使う代替ホスト名です。リクエストの Host ヘッダーは、引き続き URL の内容と一致します。つまり resolveOverride により、URL / Host ヘッダーが指定するサーバーとは別のサーバーへリクエストを送れます。ただし resolveOverride が効くのは、URL のホストと resolveOverride で指定したホストの両方が自分のゾーン内にある場合だけです。どちらかが別ゾーン / ドメインのホストを指定すると、セキュリティ上の理由でこのオプションは無視されます。Host ヘッダーはゾーン内を指したまま、ゾーン外のホストへリクエストを向けたい場合は、まずゾーン内にゾーン外ホストを指す CNAME レコードを作り、resolveOverride をその CNAME レコードに向けます。セキュリティ上の理由で、実際にそのホストへ送っていない限り、ゾーン外のホストを指定する Host ヘッダーは設定できません。

• scrapeShield boolean 任意

  • このゾーンでほかに設定されている場合、このリクエストで ScrapeShield ↗ を有効にするかどうかです。デフォルトは true です。

• webp boolean 任意

  • Polish での WebP ↗ 画像形式を有効または無効にします。

cf.vary オブジェクトは、単一の fetch() リクエストについて、オリジンの Vary レスポンスヘッダーが指名するリクエストヘッダーを Cloudflare がどう扱うかを制御します。Cache Rules Vary と同じ default と headers の形を使い、Vary と同じアクションと正規化の挙動です。

cf.vary を省略すると、Cloudflare はゾーンのほかの Vary 挙動を使います。設定されていれば Cache Rules Vary も含みます。

この設定がキャッシュキーに影響するには、オリジンレスポンスに Vary ヘッダーが必要です。Vary: * を含むレスポンスは、常にキャッシュをバイパスします。

cf.vary オブジェクトは次のキーをサポートします。

vary オブジェクトがある場合、default は必須です。空の vary オブジェクトは無効です。無効な cf.vary 設定は、そのリクエストでは無視されます。

各ヘッダー設定オブジェクトと default オブジェクトには、normalize、passthrough、bypass のいずれかに設定した action キーが必要です。指針は Actions を参照してください。

特定のヘッダー名には、追加パラメーターを指定できます。

default オブジェクトと、accept / accept-language 以外の headers エントリがサポートするのは action だけです。

ほとんどのデプロイでは、default.action を bypass にし、想定するオリジン Vary ヘッダーの headers エントリを追加し、オリジンが生のヘッダー値を必要としない限り accept と accept-language には normalize を使います。

次の制限と検証ルールが適用されます。

• headers のヘッダー名は小文字である必要があります。
• ヘッダー名に使えるのは小文字、数字、アンダースコア、ハイフンです。
• ヘッダー名は 128 文字を超えられません。
• cf- または cf_ で始まるヘッダー名は使えません。
• 一部の hop-by-hop、cache-control、proxy-control ヘッダーは使えません。例: connection、content-length、cache-control、host、range、origin、x-forwarded-for。
• headers は最大 50 エントリです。
• accept.media_types は最大 10 エントリです。
• accept-language.languages は最大 20 エントリです。
• media_types と languages の値は、空でない印字可能な ASCII 文字列である必要があります。

次の request init 断片は Accept と Accept-Language を正規化し、オリジン Vary レスポンス内のほかのヘッダーではキャッシュをバイパスします。

{
	"cf": {
		"vary": {
			"default": {
				"action": "bypass"
			},
			"headers": {
				"accept": {
					"action": "normalize",
					"media_types": ["text/html", "application/json"]
				},
				"accept-language": {
					"action": "normalize",
					"languages": ["en", "fr", "de"]
				}
			}
		}
	}
}

受信 Request オブジェクト（fetch() ハンドラー から受け取るリクエスト）のプロパティはすべて読み取り専用です。受信リクエストのプロパティを変更するには、新しい Request オブジェクトを作り、変更するオプションを コンストラクター に渡します。

• body ReadableStream 読み取り専用

  • ボディ内容のストリームです。

• bodyUsed Boolean 読み取り専用

  • ボディがすでにレスポンスで使われたかどうかを示します。

• cf IncomingRequestCfProperties 読み取り専用

  • Cloudflare グローバルネットワークが提供する、受信リクエストに関するプロパティを含むオブジェクトです。
  • このプロパティは読み取り専用です（既存の Request から作成した場合を除く）。値を変更するには、新しい Request オブジェクトを作るときに init オプション引数の cf キー へ新しい値を渡します。

• headers Headers 読み取り専用

  • Headers オブジェクト ↗ です。

  • ブラウザーと比べて、Cloudflare Workers が送信を許可するヘッダーの制限はごく少ないです。たとえばブラウザーは Cookie ヘッダーの設定を許可しません。クッキーはブラウザー自身が扱うためです。一方 Workers はクッキーを特別扱いせず、Cookie ヘッダーをほかのヘッダーと同じように扱います。

• method string 読み取り専用

  • リクエストのメソッドです。例: GET、POST など。

• redirect string 読み取り専用

  • 使うリダイレクトモードです。follow、error、manual のいずれかです。リダイレクトモードが follow の場合、fetch メソッドは自動でリダイレクトに従います。manual の場合、3xx リダイレクトレスポンスはそのまま呼び出し元に返ります。新しい Request オブジェクトのデフォルトは follow です。ただし、FetchEvent の受信 Request プロパティのリダイレクトモードは manual です。

• signal AbortSignal 読み取り専用

  • このリクエストに対応する AbortSignal です。enable_request_signal 互換性フラグを使うと、シグナルにイベントリスナーを付けられます。Worker の呼び出しが終わる前に、クリーンアップやログ書き込みができます。 たとえば次の Worker を実行し、クライアントからリクエストを中止すると、ログが書き込まれます。
    export default {
    	async fetch(request, env, ctx) {
    		// This sets up an event listener that will be called if the client disconnects from your
    		// worker.
    		request.signal.addEventListener("abort", () => {
    			console.log("The request was aborted!");
    		});
    
    		const { readable, writable } = new IdentityTransformStream();
    		sendPing(writable);
    		return new Response(readable, {
    			headers: { "Content-Type": "text/plain" },
    		});
    	},
    };
    
    async function sendPing(writable) {
    	const writer = writable.getWriter();
    	const enc = new TextEncoder();
    
    	for (;;) {
    		// Send 'ping' every second to keep the connection alive
    		await writer.write(enc.encode("ping\r\n"));
    		await scheduler.wait(1000);
    	}
    }

    export default {
      async fetch(request, env, ctx): Promise<Response> {
        // This sets up an event listener that will be called if the client disconnects from your
        // worker.
        request.signal.addEventListener('abort', () => {
          console.log('The request was aborted!');
        });
    
        const { readable, writable } = new IdentityTransformStream();
        sendPing(writable);
        return new Response(readable, { headers: { 'Content-Type': 'text/plain' } });
      },
    } satisfies ExportedHandler<Env>;
    
    async function sendPing(writable: WritableStream): Promise<void> {
    	const writer = writable.getWriter();
    	const enc = new TextEncoder();
    
    	for (;;) {
    		// Send 'ping' every second to keep the connection alive
    		await writer.write(enc.encode('ping\r\n'));
    		await scheduler.wait(1000);
    	}
    }

• url string 読み取り専用

  • リクエストの URL です。

標準の Request ↗ オブジェクトのプロパティに加え、受信 Request の request.cf オブジェクトには、Cloudflare グローバルネットワークが提供するリクエスト情報が入ります。

すべてのプランで次にアクセスできます。

• asn Number

  • 受信リクエストの ASN です。例: 395747。

• asOrganization string

  • 受信リクエストの ASN を所有する組織です。例: Google Cloud。

• botManagement Object | null

  • Cloudflare Bot Management を使っている場合にだけ設定されます。次のプロパティを持つオブジェクトです。score、verifiedBot、signedAgent、staticResource、ja3Hash、ja4、detectionIds。詳細は Bot Management Variables を参照してください。

• clientAcceptEncoding string | null

  • Cloudflare が Accept-Encoding ヘッダーの値を置き換えた場合、元の値が clientAcceptEncoding プロパティに保存されます。例: "gzip, deflate, br"。

• clientQuicRtt number | undefined

  • QUIC 接続における Cloudflare とクライアント間の平滑化ラウンドトリップ時間（RTT）です。単位はミリ秒です。クライアントが QUIC（HTTP/3）で接続した場合にだけ存在します。例: 42。

• clientTcpRtt number | undefined

  • TCP 接続におけるクライアントと Cloudflare 間の平滑化ラウンドトリップ時間（RTT）です。単位はミリ秒です。クライアントが TCP（HTTP/1 および HTTP/2）で接続した場合にだけ存在します。例: 22。

• colo string

  • リクエストが到達したデータセンターの 3 文字 IATA ↗ 空港コードです。例: "DFW"。

• country string | null

  • 受信リクエストの国です。リクエスト内の 2 文字の国コードです。CF-IPCountry ヘッダーで提供される値と同じです。例: "US"。

• edgeL4 Object | undefined

  • クライアントと Cloudflare 間の接続のレイヤー 4 トランスポート統計です。次のプロパティを含みます。
    • deliveryRate number — 接続の直近のデータ配信レート推定値です。単位はバイト毎秒です。例: 123456。

• isEUCountry string | null

  • 受信リクエストの国が EU 内の場合、"1" を返します。それ以外では、このプロパティは省略されるか false です。

• httpProtocol string

  • HTTP プロトコルです。例: "HTTP/2"。

• hostMetadata Object | undefined

  • カスタムホスト名メタデータを持つゾーンからの受信リクエストの場合にだけ埋まります。追加できる カスタムホスト名メタデータ と、hostMetadata フィールドでの公開方法は、Cloudflare for Platforms のドキュメントを参照してください。

• requestPriority string | null

  • リクエストオブジェクト内の、ブラウザーが要求した優先度情報です。例: "weight=192;exclusive=0;group=3;group-weight=127"。

• tlsCipher string

  • Cloudflare への接続の暗号です。例: "AEAD-AES128-GCM-SHA256"。

• tlsClientAuth Object | null

  • クライアント証明書に関する各種詳細です（mTLS 接続向け）。詳細は クライアント証明書の変数 を参照してください。

• tlsClientCiphersSha1 string

  • TLS ハンドシェイク中にクライアントが送った暗号スイートの SHA-1 ハッシュ（Base64 エンコード）です。ビッグエンディアン形式です。例: "GXSPDLP4G3X+prK73a4wBuOaHRc="。

• tlsClientExtensionsSha1 string

  • ハンドシェイク中に送られた TLS クライアント拡張の SHA-1 ハッシュ（Base64 エンコード）です。ビッグエンディアン形式です。例: "OWFiM2I5ZDc0YWI0YWYzZmFkMGU0ZjhlYjhiYmVkMjgxNTU5YTU2Mg=="。

• tlsClientExtensionsSha1Le string

  • ハンドシェイク中に送られた TLS クライアント拡張の SHA-1 ハッシュ（Base64 エンコード）です。リトルエンディアン形式です。例: "7zIpdDU5pvFPPBI2/PCzqbaXnRA="。

• tlsClientHelloLength string

  • TLS ハンドシェイク ↗ で送られた client hello メッセージの長さです。例: "508"。具体的には、client hello のバイト列の長さです。

• tlsClientRandom string

  • TLS ハンドシェイク ↗ でクライアントが提供する 32 バイトの乱数値です。詳細は RFC 8446 ↗ を参照してください。

• tlsVersion string

  • Cloudflare への接続の TLS バージョンです。例: TLSv1.3。

• city string | null

  • 受信リクエストの都市です。例: "Austin"。

• continent string | null

  • 受信リクエストの大陸です。例: "NA"。

• latitude string | null

  • 受信リクエストの緯度です。例: "30.27130"。

• longitude string | null

  • 受信リクエストの経度です。例: "-97.74260"。

• postalCode string | null

  • 受信リクエストの郵便番号です。例: "78701"。

• metroCode string | null

  • 受信リクエストのメトロコード（DMA）です。例: "635"。

• region string | null

  • 判明している場合、受信リクエストの IP アドレスに紐づく第 1 レベルの地域の ISO 3166-2 ↗ 名です。例: "Texas"。

• regionCode string | null

  • 判明している場合、受信リクエストの IP アドレスに紐づく第 1 レベルの地域の ISO 3166-2 ↗ コードです。例: "TX"。

• timezone string

  • 受信リクエストのタイムゾーンです。例: "America/Chicago"。

これらのメソッドは、Request オブジェクトのインスタンス、またはそのプロトタイプからのみ使えます。

• clone() : Request

  • Request オブジェクトのコピーを作成します。

• arrayBuffer() : Promise<ArrayBuffer>

  • リクエストボディの ArrayBuffer ↗ 表現で解決する Promise を返します。

• formData() : Promise<FormData>

  • リクエストボディの FormData ↗ 表現で解決する Promise を返します。

• json() : Promise<Object>

  • リクエストボディの JSON 表現で解決する Promise を返します。

• text() : Promise<string>

  • リクエストボディの文字列（テキスト）表現で解決する Promise を返します。

受信 HTTP リクエストによって Worker が呼び出されるたびに、Worker の fetch() ハンドラー が呼ばれます。Request コンテキストは fetch() ハンドラーが呼ばれたときに始まり、非同期タスク（fetch() API によるサブリクエストなど）は Request コンテキスト内でのみ実行できます。

export default {
	async fetch(request, env, ctx) {
        // Request context starts here
		return new Response('Hello World!');
	},
};

Response の Promise を fetch イベントの .respondWith() メソッドに渡すと、Response の Promise が解決するまでの非同期タスクのあいだ、リクエストコンテキストは有効です。たとえば、イベントを非同期ハンドラーに渡せます。

addEventListener("fetch", event => {
  event.respondWith(eventHandler(event))
})

// No request context available here

async function eventHandler(event){
  // Request context available here
  return new Response("Hello, Workers!")
}

スクリプト起動中に fetch() などの API を使ったり、Request コンテキストへアクセスしたりすると、例外がスローされます。

const promise = fetch("https://example.com/") // Error
async function eventHandler(event){..}

このコード断片はスクリプト起動中にスローされ、"fetch" イベントリスナーは登録されません。

Content-Length ヘッダーは、Request のデータソースに基づいてランタイムが自動設定します。ユーザーコードが Headers に手動で設定した値は無視されます。特定の値の Content-Length ヘッダーを付けるには、Request の body を FixedLengthStream、または文字列や TypedArray のような固定長の値にする必要があります。

FixedLengthStream は、書き込めるバイト数が固定の identity TransformStream です。

  const { writable, readable } = new FixedLengthStream(11);

  const enc = new TextEncoder();
  const writer = writable.getWriter();
  writer.write(enc.encode("hello world"));
  writer.end();

  const req = new Request('https://example.org', { method: 'POST', body: readable });

リクエストのボディにそれ以外の種類の ReadableStream を使うと、Chunked-Encoding が使われます。

Workers の Request インターフェース実装には、Web 標準の Request API へのいくつかの拡張があります。意図的な違いであり、Workers ランタイム固有の追加機能を提供します。

Workers は、受信リクエストに関する Cloudflare 固有のメタデータを含む cf プロパティを Request オブジェクトに追加します。このプロパティは Web 標準の一部ではなく、Workers ランタイムでのみ利用できます。詳細は IncomingRequestCfProperties を参照してください。

headers プロパティは、Set-Cookie ヘッダー向けの getAll() などの追加メソッドを含む、Workers 固有の Headers オブジェクトを返します。Workers の Headers 実装が Web 標準とどう違うかは、Headers のドキュメント を参照してください。

fetch() ハンドラー に渡される受信 Request オブジェクトは不変です。受信リクエストのプロパティを変更するには、新しい Request オブジェクトを作る必要があります。

• 例: リクエストプロパティを変更する
• 例: cf オブジェクトへアクセスする
• リファレンス: Response
• 最適化された体験のため、Worker コードは ES modules 構文 で書いてください。