INTEGRITY Документация

← Cloudflare Workers / workers / runtime-apis

Запрос

Request ↗ интерфейс представляет HTTP-запрос и является частью Fetch API.

Контекст

Чаще всего вы столкнетесь с Request объект доступен как свойство входящего запроса:

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

Возможно, вы также захотите создать Request самостоятельно, если нужно изменить объект запроса, потому что входящий request параметр, который вы получаете из fetch() обработчик является неизменяемым.

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

fetch() handler вызывает Request конструктор. RequestInit и RequestInitCfProperties типы, определенные ниже, также описывают допустимые параметры, которые можно передать в fetch() handler.

Конструктор

let request = new Request(input, options)

Параметры

options

Объект, содержащий свойства, которые нужно применить к запросу.

cf свойство (RequestInitCfProperties)

Объект, содержащий специфичные для Cloudflare свойства, которые можно задать в Request объект. Например:

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

Недопустимые или неправильно названные ключи в cf объект будет молча проигнорирован. Рекомендуем использовать TypeScript и генерировать типы с помощью команды wrangler types чтобы обеспечить правильное использование cf объект.

cf.vary свойство

cf.vary объект определяет, как Cloudflare обрабатывает заголовки запроса, названные origin сервером Vary заголовок ответа для одного fetch() запрос. Он использует тот же default и headers такую же форму, что и Cache Rules Vary, и то же поведение действий и нормализации, что и Vary.

Если вы не укажете cf.vary, Cloudflare использует другое поведение Vary для зоны, включая Cache Rules Vary, если оно настроено.

Ответ источника должен включать Vary заголовок, чтобы эта настройка повлияла на ключ кэша. Ответ, содержащий Vary: * всегда обходит кеш.

cf.vary объект поддерживает следующие ключи:

Ключ Обязательный Описание
default Да Настройка для любого имени заголовка в источнике Vary ответ, не включенный в headers.
headers Нет Сопоставление имён заголовков запроса в нижнем регистре с объектами конфигурации.

Если vary объект присутствует, default обязателен. Пустой vary объект недействителен. Недействительные cf.vary конфигурации игнорируются для этого запроса.

Каждый объект конфигурации заголовка, а также default объект должен включать action с ключом, установленным на одно из normalize, passthrough, или bypass. Дополнительные указания см. в Действия.

Для некоторых имён заголовков можно указать дополнительные параметры:

Header Дополнительный ключ Описание
accept media_types MIME-типы, которые нужно сохранить при нормализации Accept заголовок. Максимум 10 элементов и 255 символов на элемент.
accept-language languages Языки, которые нужно сохранить при нормализации Accept-Language заголовок. Максимум 20 элементов и 64 символа на элемент.

default объект и headers записи, отличные от accept и accept-language поддерживают только action.

В большинстве развёртываний задайте default.action к bypass, добавьте headers записи для ожидаемого источника Vary заголовки и использовать normalize для accept и accept-language если только вашему источнику не требуются необработанные значения заголовков.

Действуют следующие ограничения и правила проверки:

Следующий фрагмент request init нормализует Accept и Accept-Language, и обходит кеш для любого другого заголовка в источнике Vary ответ:

Фрагмент 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"]
				}
			}
		}
	}
}

Свойства

Все свойства входящего Request объект (запрос, который вы получаете от fetch() обработчик) доступны только для чтения. Чтобы изменить свойства входящего запроса, создайте новый Request объект и передаёт параметры для изменения в его конструктор.

IncomingRequestCfProperties

Помимо свойств стандартного Request ↗ объект, request.cf объект во входящем Request содержит сведения о запросе, предоставленные глобальной сетью Cloudflare.

На всех тарифных планах доступно:

Методы

Методы экземпляра

Эти методы доступны только для экземпляра Request объект или через его прототип.

Request контекст

Каждый раз, когда Worker вызывается входящим HTTP-запросом, fetch() обработчик вызывается для вашего Worker. Request контекст начинается, когда fetch() обработчик вызван, и асинхронные задачи (например, выполнение подзапроса с помощью fetch() API) можно запускать только внутри Request контекст:

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

При передаче promise в событие fetch .respondWith()

Если вы передаёте Promise с Response в событие fetch .respondWith() метод, контекст запроса остаётся активным на протяжении всех асинхронных задач, выполняемых до завершения 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!")
}

Ошибки при попытке доступа к неактивному Request контекст

Любая попытка использовать API, такие как fetch() или получить доступ к Request контекст во время запуска скрипта вызовет исключение:

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

Этот фрагмент кода выбросит исключение при запуске скрипта, и "fetch" слушатель события никогда не будет зарегистрирован.

Задайте Content-Length заголовок

Content-Length заголовок автоматически устанавливается средой выполнения на основе источника данных для Request равно этому значению. Любое значение, вручную заданное пользовательским кодом в Headers будет проигнорирован. Чтобы иметь Content-Length заголовка с указанным конкретным значением body из Request должен быть либо FixedLengthStream или значение фиксированной длины, как и строка, или TypedArray.

A 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.

Различия

Реализация Workers для Request интерфейс включает несколько расширений веб-стандарта Request API. Эти отличия сделаны намеренно и обеспечивают дополнительные функции, специфичные для среды выполнения Workers.

cf свойство

Workers добавляет cf свойство в Request объект, который содержит специфичные для Cloudflare метаданные о входящем запросе. Это свойство не входит в веб стандарт и доступно только в среде выполнения Workers. См. IncomingRequestCfProperties для получения подробностей.

headers свойство

headers свойство возвращает специфичный для Workers Headers объект, который включает дополнительные методы, такие как getAll() для Set-Cookie заголовки. См. Документация Headers подробнее о том, как Workers Headers реализация отличается от веб-стандарта.

Неизменяемость

Входящий Request объекты, передаваемые в fetch() обработчик неизменяемы. Чтобы изменить свойства входящего запроса, необходимо создать новый Request объект.