API로 규칙 만들기

원문 보기 위키 갱신 2026.10.07

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

Rulesets API를 사용해 캐시 규칙(cache rule)을 API로 만들 수 있어요. Cloudflare API를 구성하려면 API 문서를 참고해요.

출처: 문서

본문

기본 규칙 설정

API로 캐시 규칙을 만들 때 다음 사항을 확인해요:

규칙 액션을 set_cache_settings로 설정해요.
일치하는 요청에 대해 덮어쓰려는 설정에 따라 action_parameters 필드에 매개변수를 정의해요.
규칙을 http_request_cache_settings 단계 진입점(entry point) ruleset에 배포해요.

절차

List zone rulesets 메서드를 사용해 http_request_cache_settings 단계 진입점 ruleset에 이미 존재하는 규칙 목록을 얻어요.
단계 ruleset이 없으면 Create a zone ruleset 작업으로 만들어요. 새 ruleset 속성에서 다음 값을 설정해요:
- kind: zone
- phase: http_request_cache_settings
Update a zone ruleset 작업을 사용해 ruleset 규칙 목록에 캐시 규칙을 추가해요. 또는 이전 단계에서 언급한 Create a zone ruleset 요청에 규칙을 포함할 수도 있어요.
(선택) 기존 캐시 규칙을 업데이트하려면 Update a zone ruleset rule 작업을 사용해요. 예시는 아래 섹션을 참고해요.

예시 요청

이 예시들은 존의 모든 Cache Rules를 단일 규칙으로 설정해요. 이 예시를 그대로 사용하면 기존 규칙이 모두 삭제되기 때문이에요.

예시: example.com에 대해 모든 것을 캐시

Update a zone rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "(http.host eq \"example.com\")",
					"description": "cache everything for example.com",
					"action": "set_cache_settings",
					"action_parameters": {
							"cache": true
					}
				}
		]
	}'

예시: Android 클라이언트의 읽기 타임아웃 연장

Update a zone rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "(http.user_agent contains \"Android\")",
					"description": "extend read timeout for android clients",
					"action": "set_cache_settings",
					"action_parameters": {
							"cache": true,
							"read_timeout": 300
					}
				}
		]
	}'

예시: 자주 업데이트되는 자산에 대해 Cache Reserve 비활성화

Update a zone rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "(starts_with(http.request.uri, \"/feed/\"))",
					"description": "disable cache reserve for frequently updated assets",
					"action": "set_cache_settings",
					"action_parameters": {
							"cache": true,
							"cache_reserve": {
									"enabled": false
							}
					}
				}
		]
	}'

예시: 대형 미디어 파일에 Origin Range Requests 켜기

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_request_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "(http.request.uri.path.extension in {\"mp4\" \"mov\" \"m4v\"})",
					"description": "turn on origin range requests for large media files",
					"action": "set_cache_settings",
					"action_parameters": {
							"cache": true,
							"origin_range_requests": {
									"mode": "on"
							}
					}
				}
		]
	}'

예시: 기본 Origin Range Requests 끄기

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_request_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "true",
					"description": "turn off default Origin Range Requests",
					"action": "set_cache_settings",
					"action_parameters": {
							"origin_range_requests": {
									"mode": "off"
							}
					}
				}
		]
	}'

예시: 기본 캐시 TTL 끄기

Update a zone rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "(http.host eq \"example.com\")",
					"description": "turn off default cache ttls",
					"action": "set_cache_settings",
					"action_parameters": {
							"cache": true,
							"edge_ttl": {
									"mode": "bypass_by_default"
							}
					}
				}
		]
	}'

예시: 기대되는 Vary 응답 캐시

Update a zone entry point rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_request_cache_settings/entrypoint" \
	--request PUT \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"rules": [
				{
					"expression": "(http.host eq \"example.com\")",
					"description": "cache expected vary responses",
					"action": "set_cache_settings",
					"action_parameters": {
							"cache": true,
							"vary": {
									"default": {
											"action": "bypass"
									},
									"headers": {
											"accept": {
													"action": "normalize",
													"media_types": [
															"text/html",
															"application/json"
													]
											},
											"accept-language": {
													"action": "normalize",
													"languages": [
															"en",
															"fr",
															"de"
													]
											}
									}
							}
					}
				}
		]
	}'

예시: 기존 규칙의 위치 업데이트

Update a zone ruleset rulebash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID/rules/$RULE_ID" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUD...OKEN" \
	--json '{
		"expression": "(http.host eq \"example.com\")",
		"description": "cache everything for example.com",
		"action": "set_cache_settings",
		"action_parameters": {
				"cache": true
		},
		"enabled": true,
		"position": {
				"before": "da5e8e506c8e7877fe06cdf4c41add54"
		}
	}'

필요한 API 토큰 권한

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

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

더 알아보기 (Learn more)

Rulesets API를 사용해 http_request_cache_settings 단계에 캐시 규칙을 배포할 수 있어요. 캐시 여부, 읽기 타임아웃, Cache Reserve, Origin Range Requests, Edge TTL, Vary 등 다양한 설정을 요청 조건과 함께 구성할 수 있어요.