← Cloudflare for Platforms / cloudflare-for-platforms / cloudflare-for-saas / domain-support

Пользовательские метаданные

Возможно, вы захотите настроить параметры для отдельных имён хостов (клиентов), которые выходят за рамки возможностей Rules или Rate Limiting.

Для этого сначала нужно обратиться в свою account team, чтобы получить доступ к Custom Metadata. После настройки пользовательских метаданных их можно использовать следующими способами:

• Прочитайте метаданные JSON из Cloudflare Workers (требует доступа к Workers) для настройки поведения для каждого имени хоста.
• Используйте значения пользовательских метаданных в выражения правил разных продуктов безопасности Cloudflare, чтобы задать область действия правила.

• Перезапись URL для отдельных клиентов: например, клиенты 1-10,000 получают ресурсы с сервера A, 10,001-20,000 с сервера B и так далее.
• Добавление пользовательских заголовков, например, X-Customer-ID: $number на основе предоставленных вами метаданных
• Настройка заголовков HTTP Strict Transport Security («HSTS») для каждого клиента

Дополнительную логику и требования обсудите со своим Solutions Engineer.

Вы можете добавить пользовательские метаданные в Cloudflare через Custom Hostnames API. Эти данные можно добавить с помощью PATCH запрос к конкретному ID хостнейма, чтобы задать для него метаданные, например:

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_hostnames/$CUSTOM_HOSTNAME_ID" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"ssl": {
				"method": "http",
				"type": "dv"
		},
		"custom_metadata": {
				"customer_id": "12345",
				"redirect_to_https": true,
				"security_tag": "low"
		}
	}'

Изменения метаданных распространяются по периферийной сети Cloudflare в течение 30 секунд.

Объект metadata будет доступен при каждом запросе с помощью request.cf.hostMetadata свойство. После этого вы можете считывать эти данные и с помощью Worker настраивать на их основе любое поведение.

В примере ниже мы будем использовать в Worker значение user_id, отправленное с помощью описанного выше вызова API "custom_metadata":{"customer_id":"12345","redirect_to_https": true,"security_tag":"low"}, и настройте заголовок запроса так, чтобы он отправлял customer_id к origin:

export default {
	/**
	 * Fetch and add a X-Customer-Id header to the origin based on hostname
	 * @param {Request} request
	 */
	async fetch(request, env, ctx) {
		const customer_id = request.cf.hostMetadata.customer_id;
		const newHeaders = new Headers(request.headers);
		newHeaders.append("X-Customer-Id", customer_id);

		const init = {
			headers: newHeaders,
			method: request.method,
		};
		return fetch(request.url, init);
	},
};

export default {
	/**
	 * Fetch and add a X-Customer-Id header to the origin based on hostname
	 * @param {Request} request
	 */
	async fetch(request, env, ctx): Promise<Response> {
		const customer_id = request.cf.hostMetadata.customer_id;
		const newHeaders = new Headers(request.headers);
		newHeaders.append("X-Customer-Id", customer_id);

		const init = {
			headers: newHeaders,
			method: request.method,
		};
		return fetch(request.url, init);
	},
} satisfies ExportedHandler<Env>;

Используйте cf.hostname.metadata поле для доступа к объекту metadata в выражениях правил. Различные значения из объекта JSON можно получить с помощью lookup_json_string функцию.

Следующее выражение правила определяет, что правило сработает, если security_tag значение в пользовательских метаданных содержит значение low:

lookup_json_string(cf.hostname.metadata, "security_tag") eq "low"

• Убедитесь, что используемая схема JSON зафиксирована: изменения схемы без соответствующих изменений в Cloudflare Workers могут нарушить работу сайтов или привести к применению заданного поведения «по умолчанию»
• Отдавайте предпочтение плоской структуре JSON
• Используйте строковые ключи в формате snake_case (а не camelCase или PascalCase)
• Используйте настоящие булевы значения (true/false вместо true или 1 или 0)
• Используйте числа для представления целых чисел вместо строк (1 или 2 вместо "1" или "2")
• Определение запасного поведения при отсутствии метаданных
• Определение запасного поведения на случай, если ключ или значение в метаданных неизвестны

Как правило, рекомендуется следовать Google's JSON Style guide ↗ где это уместно.

На метаданные, которые можно передать Cloudflare, распространяются некоторые ограничения:

• Это должен быть допустимый JSON.
• Любое разрешение origin-сервера (например, направление запросов для определённого имени хоста на конкретный backend) должно быть задано в виде имени хоста, которое существует в DNS Cloudflare (это требование действует даже для неавторитативных конфигураций). Если указать IP-адрес напрямую, запросы будут завершаться ошибкой.
• Общий размер полезной нагрузки не должен превышать 4 КБ.
• Для этого требуется Cloudflare Worker, который умеет обрабатывать схему и запускать логику на основе содержимого.

Terraform допускает карты только одного типа, поэтому поддержка Terraform в Cloudflare для пользовательских метаданных пользовательских имён хостов ограничена строковыми ключами и значениями.