コンテンツにスキップ

リクエスト

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 optional

    • Requestに適用する設定を含むオプションのオプションオブジェクト。

options

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

  • cf RequestInitCfProperties optional

    • Cloudflareのグローバルネットワークがリクエストを処理する方法を制御するためにRequestに設定できるCloudflare特有のプロパティ。

  • method string optional

  • headers Headers optional

  • body string | ReadableStream | FormData | URLSearchParams optional

    • リクエストボディ（存在する場合）。
    • GETまたはHEADメソッドを使用するリクエストにはボディを持つことができないことに注意してください。

  • redirect string optional

    • 使用するリダイレクトモード：follow、error、またはmanual。新しいRequestオブジェクトのデフォルトはfollowです。ただし、FetchEventの受信Requestプロパティはリダイレクトモードmanualになります。

cfプロパティ（RequestInitCfProperties）

Requestオブジェクトに設定できるCloudflare特有のプロパティを含むオブジェクト。例えば：

// このリクエストのScrapeShieldを無効にします。
fetch(event.request, { cf: { scrapeShield: false } })

cfオブジェクト内の無効または不正確な名前のキーは静かに無視されます。cfオブジェクトの適切な使用を確保するために、TypeScriptおよび@cloudflare/workers-types ↗の使用を検討してください。

  • apps boolean optional

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

  • cacheEverything boolean optional

    • すべてのコンテンツを静的として扱い、Cloudflareのデフォルトキャッシュコンテンツを超えてすべてのファイルタイプをキャッシュします。オリジンウェブサーバーからのキャッシュヘッダーを尊重します。これは、ページルールキャッシュレベル（すべてキャッシュに設定）を設定することに相当します。デフォルトはfalseです。 このオプションはGETおよびHEADリクエストメソッドのみに適用されます。

  • cacheKey string optional

    • リクエストのキャッシュキーは、キャッシュ目的で2つのリクエストが同じかどうかを決定します。リクエストが以前のリクエストと同じキャッシュキーを持っている場合、Cloudflareは両方に対して同じキャッシュされたレスポンスを提供できます。

  • cacheTags Array<string> optional

    • このオプションは、オリジンサーバーからのレスポンスに追加のCache-Tagヘッダーを追加します。これにより、Workerによって提供されたタグに基づいてキャッシュコンテンツのパージが可能になります。これは、オリジンサーバーの変更なしに行われます。この機能は、現在Enterpriseゾーンでのみ利用可能なタグによるパージを使用して実行されます。このオプションが非Enterpriseゾーンで使用されると、追加のヘッダーは追加されません。

  • cacheTtl number optional

    • このオプションは、レスポンスに見られるヘッダーに関係なく、Cloudflareにこのリクエストのレスポンスをキャッシュさせます。これは、2つのページルールエッジキャッシュTTLおよびキャッシュレベル（すべてキャッシュに設定）を設定することに相当します。値はゼロまたは正の数でなければなりません。値が0の場合、キャッシュ資産は即座に期限切れになります。このオプションはGETおよびHEADリクエストメソッドのみに適用されます。

  • cacheTtlByStatus { [key: string]: number } optional

    • このオプションは、レスポンスのステータスコードに基づいてTTLを選択するcacheTtl機能のバージョンです。このリクエストのレスポンスが一致するステータスコードを持っている場合、Cloudflareは指示された時間だけキャッシュし、オリジンから送信されたキャッシュ指示を上書きします。例えば：{ "200-299": 86400, "404": 1, "500-599": 0 }。値は任意の整数（ゼロおよび負の整数を含む）であることができます。値が0の場合、キャッシュ資産は即座に期限切れになります。任意の負の値は、Cloudflareにキャッシュしないよう指示します。このオプションはGETおよびHEADリクエストメソッドのみに適用されます。

  • image Object | null optional

  • mirage boolean optional

    • このゾーンに対してMirage ↗を有効にするかどうか。デフォルトはtrueです。

  • polish string optional

    • Polish ↗モードを設定します。可能な値はlossy、losslessまたはoffです。

  • resolveOverride string optional

    • DNSルックアップをオーバーライドしてリクエストを別のオリジンサーバーに指示します。resolveOverrideの値は、オリジンIPアドレスを決定する際に使用される代替ホスト名を指定します。リクエストのHostヘッダーは、URLにあるものと一致します。したがって、resolveOverrideは、URL / Hostヘッダーが指定するものとは異なるサーバーにリクエストを送信することを可能にします。ただし、resolveOverrideは、URLホストとresolveOverrideで指定されたホストの両方があなたのゾーン内にある場合にのみ有効になります。どちらかが異なるゾーン/ドメインのホストを指定した場合、セキュリティ上の理由からオプションは無視されます。リクエストをゾーン外のホストに指示する必要がある場合（Hostヘッダーがゾーン内を指し続ける場合）、まずゾーン内にCNAMEレコードを作成して外部ホストを指し、その後resolveOverrideをCNAMEレコードを指すように設定します。セキュリティ上の理由から、リクエストが実際にそのホストに送信されている場合を除き、Hostヘッダーを使用してゾーン外のホストを指定することはできません。

  • scrapeShield boolean optional

    • このゾーンに対してScrapeShield ↗を有効にするかどうか。デフォルトはtrueです。

  • webp boolean optional

    • PolishでWebP ↗画像フォーマットを有効または無効にします。

プロパティ

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

  • body ReadableStream read-only

    • ボディコンテンツのストリーム。

  • bodyUsed Boolean read-only

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

  • cf IncomingRequestCfProperties read-only

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

  • headers Headers read-only

    • Headersオブジェクト ↗。

    • ブラウザと比較して、Cloudflare Workersは送信できるヘッダーに対して非常に少ない制限を課します。例えば、ブラウザはCookieヘッダーを設定することを許可しません。なぜなら、ブラウザはクッキーを自分で処理する責任があるからです。しかし、Workersはクッキーに特別な理解を持たず、Cookieヘッダーを他のヘッダーと同様に扱います。

  • method string read-only

    • リクエストのメソッドを含みます。例えば、GET、POSTなど。

  • redirect string read-only

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

  • url string read-only

    • リクエストのURLを含みます。

IncomingRequestCfProperties

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

すべてのプランでアクセス可能なプロパティ：

  • asn Number

    • 受信リクエストのASN。例えば、395747。

  • asOrganization string

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

  • botManagement Object | null

    • Cloudflare Bot Managementを使用している場合のみ設定されます。以下のプロパティを持つオブジェクト：score、verifiedBot、staticResource、ja3Hash、ja4、およびdetectionIds。詳細については、Bot Management Variablesを参照してください。

  • clientAcceptEncoding string | null

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

  • colo string

    • リクエストがヒットしたデータセンターの3文字のIATA ↗空港コード。例えば、"DFW"。

  • country string | null

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

  • isEUCountry string | null

    • 受信リクエストの国がEUにある場合、これは"1"を返します。そうでない場合、このプロパティは省略されます。

  • httpProtocol string

    • HTTPプロトコル。例えば、"HTTP/2"。

  • requestPriority string | null

    • リクエストオブジェクト内のブラウザ要求された優先順位情報。例えば、"weight=192;exclusive=0;group=3;group-weight=127"。

  • tlsCipher string

    • Cloudflareへの接続の暗号。例えば、"AEAD-AES128-GCM-SHA256"。

  • tlsClientAuth Object | null

    • Cloudflare AccessまたはAPI Shield（mTLS）を使用している場合のみ設定されます。以下のプロパティを持つオブジェクト：certFingerprintSHA1、certFingerprintSHA256、certIssuerDN、certIssuerDNLegacy、certIssuerDNRFC2253、certIssuerSKI、certIssuerSerial、certNotAfter、certNotBefore、certPresented、certRevoked、certSKI、certSerial、certSubjectDN、certSubjectDNLegacy、certSubjectDNRFC2253、certVerified。

  • tlsClientHelloLength string

    • TLSハンドシェイク ↗で送信されたクライアントハローのメッセージの長さ。例えば、"508"。具体的には、クライアントハローのバイト列の長さです。

  • tlsClientRandom string

  • 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アドレスに関連付けられた第一レベル地域のISO 3166-2 ↗名、例えば、"Texas"。

  • regionCode string | null

    • 知っている場合、受信リクエストのIPアドレスに関連付けられた第一レベル地域のISO 3166-2 ↗コード、例えば、"TX"。

  • timezone string

    • 受信リクエストのタイムゾーン、例えば、"America/Chicago"。

メソッド

インスタンスメソッド

これらのメソッドは、Requestオブジェクトのインスタンスまたはそのプロトタイプを通じてのみ利用可能です。

  • clone() : Promise<Request>

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

  • arrayBuffer() : Promise<ArrayBuffer>

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

  • formData() : Promise<FormData>

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

  • json() : Promise<Object>

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

  • text() : Promise<string>

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

Requestコンテキスト

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

export default {
  async fetch(request, env, ctx) {
        // リクエストコンテキストはここから始まります
    return new Response('Hello World!');
  },
};

Promiseをfetchイベントの.respondWith()に渡すとき

ResponseのPromiseをfetchイベントの.respondWith()メソッドに渡すと、ResponseのPromiseが解決される前に実行される非同期タスクの間、リクエストコンテキストがアクティブになります。例えば、イベントを非同期ハンドラに渡すことができます：

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


// ここではリクエストコンテキストは利用できません


async function eventHandler(event){
  // ここではリクエストコンテキストが利用可能です
  return new Response("Hello, Workers!")
}

非アクティブなRequestコンテキストにアクセスしようとしたときのエラー

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

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

このコードスニペットはスクリプトの起動中にエラーをスローし、"fetch"イベントリスナーは決して登録されません。

Content-Lengthヘッダーを設定する

Content-Lengthヘッダーは、Requestのデータソースに基づいてランタイムによって自動的に設定されます。Headers内でユーザーコードによって手動で設定された値は無視されます。特定の値を指定したContent-Lengthヘッダーを持たせるには、RequestのbodyはFixedLengthStreamまたは固定長の値（文字列またはTypedArray）でなければなりません。

FixedLengthStreamは、固定数のバイトのみを書き込むことを許可するアイデンティティ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が使用されます。

関連リソース

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings