WIKI 기술 지식 베이스

API로 규칙 만들기

원문 보기 위키 갱신 2026.10.07

API로 규칙 만들기 (Create a rule via API)

Rulesets API를 사용해 Cache Response Rule을 API로 만들 수 있어요. Cloudflare API를 구성하려면 API 문서를 참고해요.

출처: 문서

본문

기본 규칙 설정

API로 Cache Response Rule을 만들 때 다음 사항을 확인해요:

규칙 액션을 사용 가능한 액션 중 하나로 설정해요.
일치하는 응답에 대해 구성하려는 설정에 따라 action_parameters 필드에 매개변수를 정의해요.
규칙을 http_response_cache_settings 단계 진입점(entry point) ruleset에 배포해요.

절차

List zone rulesets 메서드를 사용해 http_response_cache_settings 단계에 ruleset이 이미 존재하는지 확인해요.
단계 ruleset이 없으면 Create a zone ruleset 작업으로 만들어요. 새 ruleset 속성에서 다음 값을 설정해요:
- kind: zone
- phase: http_response_cache_settings
Update a zone ruleset 작업을 사용해 ruleset에 규칙을 추가해요. 또는 이전 단계에서 언급한 Create a zone ruleset 요청에 규칙을 포함할 수도 있어요.

예시 요청

이 예시들은 요청 및 응답 일치 기준을 사용해 Cache Response Rules의 모든 사용 가능한 액션을 보여 줘요. 이 예시를 그대로 사용하면 단계의 기존 규칙이 교체돼요.

예시: 캐싱 전에 JS 파일에서 응답 헤더 제거

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "http.request.uri.path.extension eq \"js\"",
					"description": "Strip caching headers from JS files",
					"action": "set_cache_settings",
					"action_parameters": {
							"strip_etags": true,
							"strip_set_cookie": true,
							"strip_last_modified": true
					}
				}
		]
	}'

예시: API 응답에 정적 캐시 태그 설정

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "http.request.uri.path starts_with \"/api/\"",
					"description": "Tag API responses for targeted purging",
					"action": "set_cache_tags",
					"action_parameters": {
							"operation": "set",
							"values": [
									"api-response",
									"dynamic-content"
							]
					}
				}
		]
	}'

예시: 표현식을 사용해 응답 헤더에서 캐시 태그 추가

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "any(http.response.headers.names[*] == \"Surrogate-Keys\")",
					"description": "Extract cache tags from alternative CDN response header",
					"action": "set_cache_tags",
					"action_parameters": {
							"operation": "add",
							"expression": "split(http.response.headers[\"Surrogate-Keys\"][0], \",\", 1)"
					}
				}
		]
	}'

예시: max-age로 cache-control 덮어쓰기

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "http.response.code eq 200",
					"description": "Override cache-control for successful responses",
					"action": "set_cache_control",
					"action_parameters": {
							"max-age": {
									"operation": "set",
									"value": 3600,
									"cloudflare_only": true
							}
					}
				}
		]
	}'

예시: 한정자(qualifier)로 private 지시어 설정

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "http.request.uri.path starts_with \"/user/\"",
					"description": "Mark user content as private",
					"action": "set_cache_control",
					"action_parameters": {
							"private": {
									"operation": "set",
									"qualifiers": [
											"X-User-Id",
											"X-Session-Token"
									]
							},
							"no-cache": {
									"operation": "set"
							}
					}
				}
		]
	}'

예시: 정적 폰트 자산에 immutable 설정

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "http.request.uri.path.extension in {\"woff2\" \"woff\" \"ttf\"}",
					"description": "Mark fonts as immutable",
					"action": "set_cache_control",
					"action_parameters": {
							"immutable": {
									"operation": "set"
							},
							"max-age": {
									"operation": "set",
									"value": 31536000
							}
					}
				}
		]
	}'

예시: 헤더 제거, 응답 태깅, cache control 설정이 포함된 여러 규칙

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_response_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "http.response.code eq 200 and http.request.uri.path.extension eq \"html\"",
					"description": "Strip tracking headers from HTML responses",
					"action": "set_cache_settings",
					"action_parameters": {
							"strip_etags": true,
							"strip_set_cookie": true
					}
				},
				{
					"expression": "http.request.uri.path starts_with \"/products/\"",
					"description": "Tag product pages for purging",
					"action": "set_cache_tags",
					"action_parameters": {
							"operation": "add",
							"values": [
									"product-catalog",
									"storefront"
							]
					}
				},
				{
					"expression": "http.response.code eq 200",
					"description": "Set cache control for all 200 responses",
					"action": "set_cache_control",
					"action_parameters": {
							"s-maxage": {
									"operation": "set",
									"value": 86400,
									"cloudflare_only": true
							},
							"must-revalidate": {
									"operation": "set"
							}
					}
				}
		]
	}'

필요한 API 토큰 권한

Cache Response Rules를 관리하는 API 요청에 사용되는 API 토큰은 다음 권한이 있어야 해요:

Zone > Cache Rules > Edit
Account Rulesets > Edit
Account Filter Lists > Edit

더 알아보기 (Learn more)

Rulesets API를 사용해 http_response_cache_settings 단계에 Cache Response Rule을 배포할 수 있어요. 응답 헤더 제거(set_cache_settings), 캐시 태그 설정(set_cache_tags), cache-control 지시어 수정(set_cache_control) 액션을 요청·응답 일치 조건과 함께 구성할 수 있어요.