Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

API 設定

最終更新 Markdown で表示Agent セットアップ

API で OpenAPI スキーマのアップロード、有効化、一覧表示、削除を行います。アップロードしたスキーマは、その operation 向けの Schema Profile を提供します。

アップロードしたスキーマを設定する

  1. スキーマをアップロードします。
  2. スキーマの operation を Web Assets のインベントリへ追加します。
  3. スキーマを有効化し、アップロードしたプロファイルの評価を使えるようにします。
  4. 設定した operation へ、代表的なトラフィックを流します。
  5. Profile Analysis で cf.schema_validation.uploaded.violated を分析します。
  6. WAF Custom Rules で緩和を設定します。

設定の変更が反映されるまで、数分かかることがあります。

設定

スキーマをアップロードして有効化する

POST でスキーマをアップロードします。この例では、カレントディレクトリの example_schema.yaml を使います。

Required API token permissions

At least one of the following token permissions is required:
  • Account API Gateway
  • Domain API Gateway
Upload a schemabash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"kind": "openapi_v3",
		"name": "example_schema",
		"source": "<SOURCE>",
		"validation_enabled": true
	}'
{
	"result": {
		"schema": {
			"schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
			"name": "example_schema",
			"kind": "openapi_v3",
			"source": "<SOURCE>",
			"created_at": "2023-04-03T15:10:08.902309Z"
		}
	},
	"success": true,
	"errors": [],
	"messages": []
}

デフォルトでは、アップロードしたスキーマの評価は無効です。アップロード時に評価を使えるようにするには、validation_enabled=true を設定します。

スキーマを確認したあとに評価を有効化するには、PATCH を使います。

Required API token permissions

At least one of the following token permissions is required:
  • Account API Gateway
  • Domain API Gateway
Enable validation for a schemabash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/api_gateway/user_schemas/$SCHEMA_ID" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"validation_enabled": true
	}'
{
	"result": {
		"schema_id": "0bf58160-5da3-48ac-80a9-069f9642c1a0",
		"name": "api_schema.json",
		"kind": "openapi_v3",
		"validation_enabled": true,
		"created_at": "0001-01-01T00:00:00Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

有効化すると、設定済み operation に対してアップロードしたプロファイルの評価が使えるようになります。緩和の設定は行いません。

スキーマの operation を追加する

スキーマには、operation を定義するホスト、パス、メソッドが含まれます。operation は、HTTP メソッド、ホスト名パターン、パスパターンでエンドポイントを表します。

Schema Validation は、Web Assets に追加した operation のリクエストだけを評価します。スキーマの operation とその設定は、GET で取得します。

cURL コマンドbash
curl --request GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&operation_status=new&page=1&per_page=5000" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json'
{
	"result": [
		{
			"method": "GET",
			"host": "example.com",
			"endpoint": "/pets"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 30,
		"count": 1,
		"total_count": 1
	}
}

既存 operation の設定情報を取得するには、?feature=schema_info パラメーターの指定を推奨します。

スキーマの operation を Web Assets へ追加するには、POST を使います。

cURL コマンドbash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json' \
--data '[
  {
   "method": "GET",
   "host": "example.com",
   "endpoint": "/pets",
  }
]'
{
	"result": [
		{
			"operation_id": "6c734fcd-455d-4040-9eaa-dbb3830526ae",
			"method": "GET",
			"host": "example.com",
			"endpoint": "/pets",
			"last_updated": "2023-04-04T16:07:37.575971Z"
		}
	],
	"success": true,
	"errors": [],
	"messages": []
}

Web Assets にまだないスキーマの operation も追加できます。この API 呼び出しは最大 20 件まで対応し、jq が必要です。新しい operation が 20 件を超えるスキーマでは、同じコマンドを再度実行して次のバッチを追加します。

cURL コマンドbash
response="$(curl --silent --fail-with-body "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&page=1&per_page=20&operation_status=new" --header "Authorization: Bearer <API_TOKEN>")" || exit 1
operations="$(printf "%s" "$response" | jq --exit-status ".result")" || exit 1

if [ "$(printf "%s" "$operations" | jq "length")" -eq 0 ]; then
	printf "No new operations found.\n"
else
	curl --silent --fail-with-body "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \
	--header "Authorization: Bearer <API_TOKEN>" \
	--header "Content-Type: application/json" \
	--data "$operations" || exit 1
fi

スキーマを一覧表示する

ゾーンにアップロードしたスキーマは、GET で一覧表示します。

validation_enabled=true は任意のパラメーターです。

Required API token permissions

At least one of the following token permissions is required:
  • Account API Gateway
  • Account API Gateway Read
  • Domain API Gateway
  • Domain API Gateway Read
List all uploaded schemasbash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
    "result":  [
        {
	        "schema_id": "af632e95-c986-4738-a67d-2ac09995017a",
	        "name": "example_schema",
	        "kind": "openapi_v3",
	        "source": "<SOURCE>",
	        "created_at": "2023-04-03T15:10:08.902309Z"
	    }
    ]
    "success": true,
    "errors":
    [],
    "messages":
    []
}

スキーマを削除する

スキーマは DELETE で削除できます。

Required API token permissions

At least one of the following token permissions is required:
  • Account API Gateway
  • Domain API Gateway
Delete a schemabash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/schema_validation/schemas/$SCHEMA_ID" \
	--request DELETE \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
	"result": null,
	"success": true,
	"errors": [],
	"messages": []
}

役に立ちましたか？