INTEGRITY Dokumentace

← Cloudflare Workers / workers / runtime-apis

Požadavek

Request ↗ rozhraní představuje HTTP požadavek a je součástí Fetch API.

Kontext

Nejběžnější způsob, jak se setkáte s Request objekt je jako vlastnost příchozího požadavku:

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

Můžete si také vytvořit Request sami, když potřebujete upravit objekt požadavku, protože příchozí request parametru, který obdržíte z fetch() handler je neměnné.

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

fetch() handler vyvolá Request konstruktor. RequestInit a RequestInitCfProperties typy definované níže také popisují platné parametry, které lze předat fetch() handler.

Konstruktor

let request = new Request(input, options)

Parametry

options

Objekt obsahující vlastnosti, které chcete použít na požadavek.

cf vlastnost (RequestInitCfProperties)

Objekt obsahující vlastnosti specifické pro Cloudflare, které lze nastavit na Request objekt. Například:

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

Neplatné nebo nesprávně pojmenované klíče v cf objekt bude tiše ignorován. Zvažte použití TypeScriptu a generování typů spuštěním wrangler types abyste zajistili správné použití cf objekt.

cf.vary vlastnost

cf.vary objekt řídí, jak Cloudflare zachází s hlavičkami požadavku pojmenovanými pomocí origin serveru Vary hlavička odpovědi pro jedno fetch() požadavek. Používá stejné default a headers tvar jako Cache Rules Vary, a stejné akce a chování při normalizaci jako Vary.

Pokud vynecháte cf.vary, Cloudflare pro danou zónu používá jiné chování Vary, včetně Cache Rules Vary, pokud jsou nakonfigurována.

Odpověď origin serveru musí obsahovat Vary hlavičku, aby toto nastavení ovlivnilo klíč mezipaměti. Odpověď obsahující Vary: * vždy obchází cache.

cf.vary objekt podporuje následující klíče:

Key Povinné Popis
default Ano Konfigurace pro libovolný název hlavičky v odpovědi originu Vary odpověď, která není zahrnuta v headers.
headers Ne Mapa názvů hlaviček žádosti psaných malými písmeny na konfigurační objekty.

Pokud vary objekt je přítomen, default je povinná. Prázdná vary objekt je neplatný. Neplatné cf.vary konfigurace se pro tento požadavek ignorují.

Každý objekt konfigurace hlavičky a default objekt musí obsahovat action s klíčem nastaveným na jednu z hodnot normalize, passthrough, nebo bypass. Návod najdete v Akce.

U některých názvů hlaviček lze zadat další parametry:

Hlavička Další klíč Popis
accept media_types Typy MIME, které se zachovají při normalizaci Accept hlavička. Maximálně 10 položek a 255 znaků na položku.
accept-language languages Jazyky, které se mají zachovat při normalizaci Accept-Language hlavička. Maximálně 20 položek a 64 znaků na položku.

default objekt a headers položky jiné než accept a accept-language podporují pouze action.

U většiny nasazení nastavte default.action na bypass, přidejte headers položky pro očekávaný origin Vary hlavičky a použijte normalize pro accept a accept-language pokud váš origin nevyžaduje nezpracované hodnoty hlaviček.

Platí následující limity a validační pravidla:

Následující fragment inicializace požadavku normalizuje Accept a Accept-Language, a cache obchází pro jakoukoli jinou hlavičku v origin Vary odpověď:

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

Vlastnosti

Všechny vlastnosti příchozího Request objekt (požadavek, který obdržíte z fetch() handler) jsou pouze pro čtení. Chcete-li upravit vlastnosti příchozího požadavku, vytvořte nový Request objekt a předá možnosti k úpravě do jeho konstruktor.

IncomingRequestCfProperties

Kromě vlastností standardního Request ↗ objekt, request.cf objekt v příchozím Request obsahuje informace o požadavku poskytnuté globální sítí Cloudflare.

Všechny tarify mají přístup k:

Metody

Metody instance

Tyto metody jsou k dispozici pouze na instanci Request objekt nebo prostřednictvím jeho prototypu.

Request kontext

Při každém volání Workeru příchozím HTTP požadavkem se fetch() handler je volána na vašem Workeru. Request kontext začíná, když fetch() handler zavolán a asynchronní úlohy (například vytvoření dílčího požadavku pomocí fetch() API) lze spustit pouze uvnitř Request kontext:

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

Při předání promise do fetch události .respondWith()

Pokud do události fetch předáte příslib objektu Response .respondWith() metoda, kontext požadavku je aktivní po celou dobu asynchronních úloh, které běží před vyřešením promise Response. Událost můžete předat asynchronnímu handleru, například:

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!")
}

Chyby při pokusu o přístup k neaktivnímu Request kontext

Jakýkoli pokus použít API, jako je fetch() nebo přistupovat k Request kontext během spouštění skriptu vyvolá výjimku:

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

Tento úryvek kódu vyvolá výjimku při spuštění skriptu a "fetch" posluchač události se nikdy nezaregistruje.

Nastavte Content-Length hlavička

Content-Length hlavička se automaticky nastaví podle toho, jaký je zdroj dat pro Request je. Jakákoli hodnota ručně nastavená kódem uživatele v Headers bude ignorován. Pokud chcete mít Content-Length hlavičky na konkrétní hodnotu se body Request musí být buď FixedLengthStream nebo hodnotu s pevnou délkou stejně jako řetězec nebo TypedArray.

A FixedLengthStream je identita TransformStream který umožňuje do sebe zapsat jen pevně daný počet bajtů.

  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 });

Použití jakéhokoli jiného typu ReadableStream jako tělo požadavku bude mít za následek použití Chunked-Encoding.

Rozdíly

Workers implementace pro Request rozhraní obsahuje několik rozšíření webového standardu Request API. Tyto rozdíly jsou záměrné a poskytují další funkce specifické pro prostředí Workers runtime.

cf vlastnost

Workers přidává cf vlastnost na Request objekt, který obsahuje metadata specifická pro Cloudflare o příchozím požadavku. Tato vlastnost není součástí webového standardu a je dostupná pouze v runtime Workers. Viz IncomingRequestCfProperties s podrobnostmi.

headers vlastnost

headers vlastnost vrátí verzi specifickou pro Workers Headers objekt, který zahrnuje další metody, jako například getAll() pro Set-Cookie hlavičky. Podrobnosti najdete v Dokumentace Headers pro podrobnosti o tom, jak Workers Headers implementace se liší od webového standardu.

Neměnnost

Příchozí Request objekty předané do fetch() handler jsou neměnné. Pokud chcete upravit vlastnosti příchozího požadavku, musíte vytvořit nový Request objekt.