API で URL rewrite rule を作成する

Rulesets API で、API 経由の URL Rewrite Rules を作成します。よくある用途は Rules の例ギャラリーを参照してください。

Terraform を使う場合は、Terraform で Transform Rules を設定するを参照してください。

基本的なルール設定

API で URL rewrite rule を作成するときは、次を確認してください。

ルールアクションを rewrite に設定する。
URL リライトの種類（静的または動的）に応じて、action_parameters フィールドに URL rewrite パラメーターを定義する。
ゾーン単位で、ルールを http_request_transform フェーズにデプロイする。

手順

API を使って、指定したゾーンに a URL rewrite rule を作成するには、次のワークフローに従います。

ゾーンルールセットを一覧する操作を使い、ゾーンレベルで http_request_transform フェーズのルールセットがすでにあるかを確認します。
フェーズのルールセットが存在しない場合は、ゾーンルールセットを作成する操作で作成します。新しいルールセットのプロパティには、次の値を設定します。
- kind: zone
- phase: http_request_transform
ゾーンルールセットを更新する操作を使い、ルールセットのルール一覧に a URL rewrite rule を追加します。または、前のステップで説明したゾーンルールセットを作成するリクエストにルールを含めます。

API 操作を行うには、API トークンに必要な権限があることを確認してください。

リクエスト例

例: 静的な URL リライトを行うルールを追加する

次の例は、Update a zone ruleset 操作を使い、既存のフェーズルールセット（$RULESET_ID）のルールを、URI パスを静的にリライトする URL rewrite rule 1 件に設定します。レスポンスには、更新したルールセットの完全な定義が含まれます。

Required API token permissions

At least one of the following token permissions is required:

Response Compression Write
Config Settings Write
Dynamic URL Redirects Write
Cache Settings Write
Custom Errors Write
Origin Write
Managed headers Write
Zone Transform Rules Write
Mass URL Redirects Write
Magic Firewall Write
L4 DDoS Managed Ruleset Write
HTTP DDoS Managed Ruleset Write
Sanitize Write
Transform Rules Write
Select Configuration Write
Bot Management Write
Zone WAF Write
Account WAF Write
Account Rulesets Write
Logs Write
Logs Write

Update a zone rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"ref": "rewrite_eu_to_emea",
						"expression": "(http.request.uri.query contains \"eu\")",
						"description": "My first static URL rewrite rule",
						"action": "rewrite",
						"action_parameters": {
								"uri": {
										"path": {
												"value": "/emea.html"
										}
								}
						}
				}
		]
	}'

{
	"result": {
		"ref": "rewrite_eu_to_emea",
		"id": "<RULESET_ID>",
		"name": "Zone-level Transform Ruleset",
		"description": "Zone-level ruleset that will execute Transform Rules.",
		"kind": "zone",
		"version": "2",
		"rules": [
			{
				"id": "<RULE_ID>",
				"version": "1",
				"action": "rewrite",
				"action_parameters": {
					"uri": {
						"path": {
							"value": "/emea.html"
						}
					}
				},
				"expression": "(http.request.uri.query contains \"eu\")",
				"description": "My first static URL rewrite rule",
				"last_updated": "2021-04-14T14:42:04.219025Z",
				"ref": "<RULE_REF>"
			}
		],
		"last_updated": "2021-04-14T14:42:04.219025Z",
		"phase": "http_request_transform"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Terraform を使う場合、更新をまたいでルール ID を安定させるには ref フィールドを使います。このフィールドを追加すると、変更時に Terraform がルールを再作成するのを防げます。詳細は Terraform ドキュメントのトラブルシューティングを参照してください。

例: 動的な URL リライトを行うルールを追加する

次の例は、Update a zone ruleset 操作を使い、既存のフェーズルールセット（$RULESET_ID）のルールを、URI パスを動的にリライトする URL rewrite rule 1 件に設定します。レスポンスには、更新したルールセットの完全な定義が含まれます。

Required API token permissions

At least one of the following token permissions is required:

Response Compression Write
Config Settings Write
Dynamic URL Redirects Write
Cache Settings Write
Custom Errors Write
Origin Write
Managed headers Write
Zone Transform Rules Write
Mass URL Redirects Write
Magic Firewall Write
L4 DDoS Managed Ruleset Write
HTTP DDoS Managed Ruleset Write
Sanitize Write
Transform Rules Write
Select Configuration Write
Bot Management Write
Zone WAF Write
Account WAF Write
Account Rulesets Write
Logs Write
Logs Write

Update a zone rulesetbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"ref": "rewrite_2012_to_archive",
						"expression": "starts_with(http.request.uri.path, \"/news/2012/\")",
						"description": "My first dynamic URL rewrite rule",
						"action": "rewrite",
						"action_parameters": {
								"uri": {
										"path": {
												"expression": "concat(\"/archive\", http.request.uri.path)"
										}
								}
						}
				}
		]
	}'

{
	"result": {
		"id": "<RULESET_ID>",
		"name": "Zone-level Transform Ruleset",
		"description": "Zone-level ruleset that will execute Transform Rules.",
		"kind": "zone",
		"version": "2",
		"rules": [
			{
				"ref": "rewrite_2012_to_archive",
				"id": "<RULE_ID>",
				"version": "1",
				"action": "rewrite",
				"action_parameters": {
					"uri": {
						"path": {
							"expression": "concat(\"/archive\", http.request.uri.path)"
						}
					}
				},
				"expression": "starts_with(http.request.uri.path, \"/news/2012/\")",
				"description": "My first dynamic URL rewrite rule",
				"last_updated": "2021-04-14T14:42:04.219025Z",
				"ref": "<RULE_REF>"
			}
		],
		"last_updated": "2021-04-14T14:42:04.219025Z",
		"phase": "http_request_transform"
	},
	"success": true,
	"errors": [],
	"messages": []
}

必要な API トークン権限

URL Rewrite Rules を管理する API リクエストで使う API トークンには、少なくとも次の権限が必要です。

Account > Transform Rules > Edit
Account > Account Rulesets > Read