カスタムメタデータ

Rules や Rate Limiting の規模では足りない、ホスト名（お客様）ごとの設定が必要になることがあります。

そのためには、まずアカウントチームに連絡し、Custom Metadata へのアクセスを有効にしてもらいます。カスタムメタデータを設定したあと、次の方法で利用できます。

• Cloudflare Workers からメタデータの JSON を読み取り、ホスト名ごとの動作を定義します（Workers へのアクセスが必要です）。
• 各種 Cloudflare セキュリティ製品の ルール式 でカスタムメタデータの値を使い、ルールの適用範囲を定義します。

• お客様ごとの URL 書き換え — たとえば、お客様 1〜10,000 はサーバー A、10,001〜20,000 はサーバー B からアセットを取得する、など
• カスタムヘッダーの追加 — たとえば、指定したメタデータに基づく X-Customer-ID: $number
• お客様ごとに HTTP Strict Transport Security（HSTS）ヘッダーを設定する

追加のロジックや要件については、ソリューションエンジニアに相談してください。

カスタムメタデータは、Custom Hostnames API 経由で Cloudflare に追加できます。特定のホスト名 ID に対する PATCH リクエスト で、そのホスト名のメタデータを設定します。例:

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"
		}
	}'

メタデータの変更は、30 秒以内に Cloudflare のエッジへ反映されます。

メタデータオブジェクトは、各リクエストの request.cf.hostMetadata プロパティで参照できます。Worker でこのデータを読み取り、動作をカスタマイズできます。

次の例では、前述の API 呼び出しで送信した "custom_metadata":{"customer_id":"12345","redirect_to_https": true,"security_tag":"low"} の customer_id を Worker で使い、オリジンへ送るリクエストヘッダーに customer_id を設定します。

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 フィールドでメタデータオブジェクトにアクセスします。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 や 1 / 0 ではなく、true / false を使います
• 整数は文字列ではなく数値で表します（"1" や "2" ではなく 1 や 2）
• メタデータがない場合のフォールバック動作を定義します
• メタデータのキーや値が不明な場合のフォールバック動作を定義します

一般的な指針として、適切な箇所では Google の JSON スタイルガイド ↗ に従います。

Cloudflare に渡せるメタデータには、次の制限があります。

• 有効な JSON である必要があります。
• オリジンの解決（特定ホスト名のリクエストを特定のバックエンドへ向けるなど）は、Cloudflare の DNS に存在するホスト名として指定する必要があります（権威 DNS でない構成でも同様です）。IP アドレスを直接指定すると、リクエストはエラーになります。
• ペイロード全体は 4 KB を超えてはいけません。
• スキーマを処理し、内容に応じたロジックを実行する Cloudflare Worker が必要です。

Terraform は単一の型のマップだけを扱えるため、カスタムホスト名向けカスタムメタデータの Terraform サポートは、文字列のキーと値に限られます。