コンテンツにスキップ

設定

スキーマ検証 2.0では、すべての対応する設定呼び出しをAPI経由で行うことができます。この検証は、個々の エンドポイント により中心に置かれ、各エンドポイントに対して緩和アクションを個別に設定できます。さらに、Cloudflareが提供する学習済みスキーマを使用して、個々のエンドポイントのトラフィックから自動的に学習したものを利用できます。

APIを介してスキーマをスキーマ検証にアップロードする

  1. スキーマをアップロードします。
  2. エンドポイント管理にエンドポイントが追加されていることを確認します。
  3. スキーマがまだであれば、activeに設定します。
  4. スキーマ検証のゾーン全体のアクションをnoneからlogに設定します。
  5. スキーマに違反するテストトラフィックを送信します。
  6. Service > API Shield - Schema Validationでフィルタリングして、セキュリティイベントでテストトラフィックを表示します。
  7. オプション:
    • 単一のエンドポイントをblockに設定します。
    • スキーマ検証をゾーン全体でblockに設定します。
    • 一時的にすべてのスキーマをゾーン全体でnoneにオーバーライドします。
    • 一時的なオーバーライドを削除します。

Cloudflareは、設定を変更した後にテストトラフィックを再実行し、HTTPレスポンスコードを監視することを推奨します。これにより、スキーマ検証が期待通りに動作していることを確認できます。

設定の変更には数分かかる場合があります。

設定

スキーマをアップロードしてアクティブにする

POSTを使用してv4 API経由でスキーマをアップロードします。この例では、現在のフォルダーにexample_schema.yamlスキーマファイルが必要です。

cURLコマンド
curl --request POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas" \
--header "Authorization: Bearer <API_TOKEN>" \
--form file=@example_schema.yaml --form kind=openapi_v3 --form name=example_schema --form validation_enabled=false
結果
{
    "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リクエストを使用します。

cURLコマンド
curl --request PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json' \
--data '{
 "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":
    []
}

スキーマがアクティブになると、各操作に指定された緩和アクションが実行されます。デフォルトおよび操作固有の緩和アクションを変更するを参照してください。

エンドポイント管理に新しい操作を追加する

スキーマには、サーバー、パス、およびメソッドのセットが含まれており、これらが一緒になって操作を定義します。スキーマ検証は、API Shieldエンドポイント管理に追加された操作へのリクエストにのみ作用します。スキーマにエンドポイント管理に追加されていない操作が含まれている場合、それらは追加された操作に関する設定情報と一緒に取得できます。

cURLコマンド
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
    }
}

既存の操作の設定情報を受け取るには、Cloudflareは?feature=schema_infoパラメータを渡すことを推奨します。

スキーマ内の新しい操作をエンドポイント管理に追加するには、POSTを使用します。

cURLコマンド
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":
    []
}

スキーマ内のすべての操作をエンドポイント管理に追加するには、2つのコマンドを1つに結合することができます。このAPI呼び出しの最大操作数は20です。この例では、jqツールが必要です。

cURLコマンド
curl --silent "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data "$(curl --silent "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations?feature=schema_info&page=1&per_page=5000" --header "Authorization: Bearer <API_TOKEN>" | jq ".result")"

デフォルトおよび操作固有の緩和アクションを変更する

スキーマがアップロードされ、操作のセットに対してアクティブな場合、受信リクエストを各操作に対して検証し、緩和アクションを取るかどうかを決定します。この緩和アクションは操作ごとに定義され、none、log、blockの値を取ることができ、これはアクションなし、リクエストのログ記録、またはオリジンに到達する前にブロックすることに対応します。

新しい操作には緩和アクションが設定されず、ゾーン全体のデフォルト緩和アクションが使用されます。現在のデフォルト緩和アクションはGETを使用して取得できます。

cURLコマンド
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>"
結果
{
    "result":  {
        "validation_default_mitigation_action": "none",
        "validation_override_mitigation_action": null
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}

none、log、blockのいずれかの新しい値をPUTを使用して設定できます。

cURLコマンド
curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "validation_default_mitigation_action": "block"
}'
結果
{
    "result":  {
        "validation_default_mitigation_action": "block",
        "validation_override_mitigation_action": null
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}

特定の操作の緩和アクションが関心のある場合、現在の値は操作IDを使用してGETで取得できます。

cURLコマンド
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>"
結果
{
    "result":  {
        "mitigation_action": "null"
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}

値がnullの場合、これはこの操作に対して緩和アクションが指定されておらず、デフォルトの緩和アクションが使用されていることを意味します。

緩和アクションをnone、block、log、nullのいずれかの値に設定するには、PUTを使用します。

cURLコマンド
curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
    "mitigation_action": "block"
}'
結果
{
    "result":  {
        "mitigation_action": "block"
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}

すべてのスキーマをリストする

現在アクティブなスキーマの概要を取得するには、GETを使用します。

validation_enabled=trueはオプションのパラメータです。

cURLコマンド
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas?omit_source=true" \
--header "Authorization: Bearer <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を使用します。

cURLコマンド
curl --request DELETE "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/user_schemas/{schema_id}" \
--header "Authorization: Bearer <API_TOKEN>"
結果
{
    "result":  null,
    "success": true,
    "errors":
    [],
    "messages":
    []
}

操作のために学習したスキーマをアクティブにする

Cloudflareは、十分なリクエストがあるすべての操作に対して自動的に学習したパラメータスキーマを提供します。学習したスキーマはGETを使用して検査できます。

cURLコマンド
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}?feature=parameter_schemas" \
--header "Authorization: Bearer <API_TOKEN>"
結果
{
    "result":
    {
        "operation_id": "5c734fcd-455d-4040-9eaa-dbb3830526ae",
        "method": "PATCH",
        "host": "example.com",
        "endpoint": "/pets",
        "last_updated": "2023-04-04T16:07:37.575971Z",
        "features":
        {
            "parameter_schemas":
            {
                "last_updated": "2023-04-03T20:11:55.879006Z",
                "parameter_schemas":
                {
                    "responses": null,
                    "parameters":
                    [
                        {
                            "in": "query",
                            "name": "var1",
                            "schema":
                            {
                                "type": "string"
                            },
                            "required": true,
                            "description": "このパラメータに対して十分なリクエストが観察されており、このパラメータスキーマに高い信頼性を提供します。"
                        }
                    ],
                    "x-cf-parameter-schemas": "自動的に学習されたパスおよびクエリパラメータを持つ操作スキーマ"
                }
            }
        }
    },
    "success": true,
    "errors":
    [],
    "messages":
    []
}

検査したパラメータスキーマに満足している場合は、PUTを使用して追加およびアクティブにできます。

cURLコマンド
curl --request PUT "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/operations/{operation_id}/cloudflare_learned_schema?timestamp=2023-04-03T20:11:55.879006Z" \
--header "Authorization: Bearer <API_TOKEN>"
結果
{
    "result": null,
    "success": true,
    "errors":
    [],
    "messages":
    []
}

スキーマ検証を無効にする

ゾーン全体のスキーマ検証を迅速に無効にするには、PATCHを使用します。この操作はすべての操作の緩和アクションをオーバーライドします。

cURLコマンド
curl --request PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/api_gateway/settings/schema_validation" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json' \
--data '{
  "validation_override_mitigation_action": "none"
}'
結果
{
    "result":  {
        "validation_default_mitigation_action": "block",
        "validation_override_mitigation_action": "none"
    }
    "success": true,
    "errors":
    [],
    "messages":
    []
}
Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings