Skip to content

非公式 / UnofficialCloudflare, Inc. 非提携。アカウント情報は入力しないでください。Not affiliated with Cloudflare, Inc. Do not enter Cloudflare credentials here.Official docsこのサイトについてプライバシー

Schema Validation

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

API スキーマは、対象エンドポイント、パスまたはクエリ変数の形式、HTTP メソッドなど、いくつかのリクエスト属性に基づいて、どの API リクエストが有効かを定義します。

Schema Validation は、受信リクエストをアップロードした OpenAPI スキーマと比較します。アップロードしたスキーマは、Schema Profile が期待するリクエスト構造を提供します。

アップロードしたプロファイルが利用可能になると、Cloudflare は 常時オンの検出 を生成します。違反の分析と緩和には cf.schema_validation.uploaded.violated を使います。

検出だけではトラフィックを緩和しません。カスタムルールでプロファイルを適用する前に、Profile Analysis で結果を確認してください。適用手順は Custom Rules でプロファイルを適用する を参照してください。

現行バージョンは Schema Validation 2.0 です。以前のバージョンについては、Classic Schema Validation を設定する を参照してください。

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

エンドポイントは、Web Assets > Operations にオペレーションとして存在する必要があります。ダッシュボードからアップロードすると、スキーマのオペレーションは自動で追加されます。

API または Terraform を使う場合は、スキーマのオペレーションを別途追加します。自動化の詳細は、API 構成 または Terraform を参照してください。

スキーマをアップロードする

  1. Cloudflare ダッシュボードで、Web Assets ページを開きます。

    公式ダッシュボードで Web assets を開く ↗
  2. Schema validation タブを開きます。

  3. Add validation を選択します。

  4. OpenAPI スキーマファイルをアップロードします。

  5. Add schema and endpoints を選択します。

変更の反映には、オペレーション数に応じて数分かかることがあります。

アップロードしたスキーマを管理する

  1. Cloudflare ダッシュボードで、Web Assets ページを開きます。

    公式ダッシュボードで Web assets を開く ↗
  2. Schema validation タブを開きます。

  3. Schema settings を選択します。

  4. API abuse で絞り込みます。

  5. Schema validation > Active schemas で、アップロード済みスキーマを確認します。

  6. スキーマのオーバーフローメニューから、スキーマをダウンロードまたは削除します。

アップロードしたスキーマを削除すると、そのプロファイル評価は停止します。関連するオペレーションは Web Assets のインベントリに残ります。

fallthrough ルールを追加する

fallthrough ルールは、既知のオペレーションに一致しないリクエストに一致します。未識別のエンドポイントを保護するには、この WAF Custom Rule を使います。

  1. Cloudflare ダッシュボードで、Security rules ページを開きます。

    公式ダッシュボードで Security rules を開く ↗
  2. Templates を選択します。

  3. Mitigate API requests to unidentified endpoints を見つけ、Preview template を選択します。

  4. 分かりやすいルール名を入力します。

  5. 対象のホスト名とルールアクションを選びます。

  6. Save as draft または Deploy を選択します。

独自のロジックを使う場合は、cf.api_gateway.fallthrough_detected を使います。ルールの範囲は、API のホスト名またはルートパスに絞ってください。


仕様

Cloudflare が現在受け付けるのは OpenAPI v3 スキーマ ↗ だけです。受け付けるファイル形式は YAML(.yml または .yaml)と JSON(.json)です。

ツールによって生成した OpenAPI スキーマは、Schema Validation に取り込むには具体性が足りないことがあります。OpenAPI 仕様に準拠しているかは、Swagger Editor ↗ などのサードパーティツールで確認してください。


制限

Cloudflare API Shield の Schema Validation(インポート)と Schema Learning(エクスポート)は、OpenAPI Specification (OAS) v3.0 ↗ に依存します。

この対応には、OAS v3.0.x などのパッチバージョンも含まれます。OAS v3.1 は未対応で、OpenAPI 2.0 への対応拡大予定もありません。

現在、API Shield は API スキーマの一部機能に未対応です。対象は次のとおりです。すべてのレスポンス、外部参照、基本以外のパステンプレート、unique items。

API Shield を契約している Enterprise のお客様では、有効なスキーマのオペレーション合計は 10,000 が上限です。上限を引き上げる場合は、担当チームに連絡してください。

検証対象のボディサイズ

Schema Validation は、プランごとの最大サイズまでリクエストボディを検査します。この上限を超えるリクエストは、アップロードしたスキーマでは評価しません。

デフォルトのボディサイズ上限は次のとおりです。

プラン デフォルトのボディサイズ上限
Free 1 KB
Pro 8 KB
Business 8 KB
Enterprise 128 KB

ボディサイズ上限を超えるリクエストを特定する

リクエストログを使い、ボディサイズをプラン上限と比較します。

API Shield 未契約の Free、Pro、Business、Enterprise のお客様の上限は、プラン を参照してください。

必須フィールド

OpenAPI 仕様では必須ではありませんが、Schema Validation では次のフィールドを必須とします。

schema

  • type ↗
    • すべてのスキーマに type の設定が必要です。Schema Validation が対応していない型の場合は、代わりに string を設定します。

parameter

検証対象および対応フィールドの注意

Schema Validation が現在対応している OpenAPI specification(OAS)のオブジェクトとフィールドの詳細です。

servers

  • url ↗
    • Schema Validation は相対 URL に対応していません。
  • variables ↗
    • サーバー変数は検証しません。

parameter

  • style ↗
    • 対応しているのはデフォルト値だけです。"simple"(path または header パラメーター)と "form"(query または cookie パラメーター)です。
  • explode ↗
    • 対応しているのはデフォルト値だけです。true(form の場合)と false(simple の場合)です。
  • content ↗
    • パラメーターの content フィールドには対応していません。代わりに schema フィールドを使います。
  • type ↗
    • 現在、object 型のパラメーターは検証しません。

reference

  • $ref ↗
    • 外部参照または相対参照には対応していません。

requestBody

  • content
    • Request Body Object ↗
    • Media Type Object ↗
      • Schema Validation は application/json ドキュメントを検証できます。スキーマが他のコンテンツタイプを許可している場合、それらのリクエストは検証なしで受け入れます。

parameter/schema

schema

  • format ↗
    • 検証する形式:
      • date-time
      • time
      • date
      • email
      • hostname
      • ipv4
      • ipv6
      • uri
      • uri-reference
      • iri
      • iri-reference
      • int32
      • int64
      • float
      • double
      • password
      • uuid
      • byte
      • uint64
  • uniqueItems ↗
    • このフィールドは、現在 Schema Validation では検証しません。

ボディ検査

API Shield は、アップロードしたスキーマに含まれるボディ仕様を識別し、受信 API リクエストのデータがそれに従っているかを検証できます。

Schema Validation が現在対応しているのは、content-type が application/json のリクエストです。

OpenAPI 仕様では、リクエストボディのスキーマはメディアレンジ(application/*、application/xml、application/json など)に関連付けられます。

Cloudflare が受信リクエストを検証するとき、リクエストの content-type が OpenAPI で指定したメディアレンジと一致するかを確認します。

たとえば、OpenAPI ファイルがリクエストボディの content マップで application/* を指定している場合、Cloudflare は application/xml と application/json のリクエストを受け入れます。ただし、指定したスキーマで検証するのは application/json のボディだけです。

メディアレンジは、個別のメディアタイプに設定して、できるだけ狭くすることを推奨します。1 つの API エンドポイントで複数の content-type を扱う必要がある場合は、ワイルドカードのメディアレンジを使えます。

オリジンが MIME sniffing ↗ を行う設定の場合も注意が必要です。たとえば、JSON ボディを持つリクエストが意図的に application/malicious の content-type を付け、Cloudflare が application/* のメディアレンジを許可している場合、JSON ボディの内容は検証されずにオリジンへ渡されます。一方、オリジンが content-type を無視し、試しにデシリアライズするか MIME タイプをスニフすると、スキーマのボディ検証を通過したと誤って判断して JSON ボディをデシリアライズする可能性があります。

そのため、同じエンドポイントで application/json と application/xml の両方が必要な場合は、application/* を使えます。Cloudflare は、content-type が application/json のリクエストボディに対して指定したスキーマを検証します。content-type が application/xml(および application/* に一致するその他)のリクエストは通過します。オリジンでは content-type のスニッフィングを無効にすることを、引き続き強く推奨します。

Cloudflare が OpenAPI のリクエストボディ content マップで受け付けるメディアレンジは次のとおりです。

  • */*
  • application/*
  • application/json

メディアレンジでは charset パラメーターの強制も設定できます。この場合、Cloudflare が受け付けるのは値が utf-8 の静的な charset パラメーターだけです。設定した場合、リクエストの content-type にもこの charset が必要です。


トラブルシューティング

このセクションでは、Schema Validation 利用時によくある問題を扱います。

OneOf 制約違反を解消する

OneOf 制約エラーは、リクエストがアップロードしたプロファイルに違反したことを意味します。ボディが oneOf ↗ オプションのちょうど 1 つに一致しませんでした。

リクエストが無効になった理由は、次のいずれかです。

  • 一致ゼロ: ペイロードが、利用可能なサブスキーマのどれにも正しく一致しませんでした。discriminator フィールドは設定されているが、その型に必要な他のフィールドが欠けている場合によく起きます。
  • 複数一致: ペイロードが曖昧で、複数のサブスキーマに一致しました。汎用的なスキーマで起きます(たとえば、ペイロードに email と phone の両方がある場合、email と phone の両方のスキーマ定義に一致し、「ちょうど 1 つ」の規則に違反することがあります)。

修正するには、サンプリングしたリクエストをスキーマ定義と比較します。必須フィールドの欠落や、競合する型への一致が原因のことがあります。


利用可否

API Security をご利用のお客様は、Schema Learning と Schema Validation を通じて Schema Profile にすでにアクセスできます。Cloudflare は、API Security を持たない招待制の Enterprise のお客様向けにクローズドベータを開始しています。関心がある場合は、担当チームに連絡してください。クローズドベータへのアクセスは、将来のプラン提供や価格を約束するものではありません。

役に立ちましたか?