OASValidation ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントはこちらをご覧ください。

OASValidation ポリシーについて

OASValidation（OpenAPI 仕様の検証）ポリシー（ベータ版）を使用すると、OpenAPI 3.0 仕様（JSON または YAML）と照らして受信リクエストまたはレスポンス メッセージを検証できます。検証するコンテンツをご覧ください。

OASValidation ポリシーでは、ポリシーが接続された手順が実施されるときに検証に使用する OpenAPI 仕様の名前を指定します。OpenAPI 仕様は、API プロキシ バンドル内の標準の場所（apiproxy/resources/oas）にリソースとして保存されます。OpenAPI 仕様には、拡張機能 .json、.yml、.yaml が必要です。

リソースの管理で説明しているように、UI または API を使用して、OpenAPI 仕様をリソースとして API プロキシ バンドルに追加します。

このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。すべてのユーザーがポリシーや環境のタイプを知る必要はありません。ポリシータイプと各環境タイプでの利用可否については、ポリシータイプをご覧ください。

注: OpenAPI 仕様は API プロキシ リビジョンでのみ保存できます。リソースの保存場所をご覧ください。

検証するコンテンツ

次の表に、OASValidation ポリシーによって検証されるリクエスト メッセージの内容をコンポーネント別に示します。

コンポーネント	リクエストの検証
ベースパス	API プロキシによって定義されたベースパスを検証します。OpenAPI 仕様で指定されたベースパスは無視されます。
パス	リクエストパス（ベースパスを除く）が OpenAPI 仕様で定義されているパスパターンのいずれかと一致していることを検証します。
動詞	OpenAPI 仕様のパスに対して動詞が定義されていることを検証します。
リクエスト メッセージの本文	必要に応じて、リクエストにメッセージ本文が存在することを検証します。 必要に応じて、OpenAPI 仕様でオペレーションのリクエスト本文のスキーマに照らしてメッセージ本文を検証します。<ValidateMessageBody> を使用してこのオプションを構成します。 注: このポリシーは、Content-Type が application/json に設定されている場合にのみ、OpenAPI 仕様に照らしてリクエスト メッセージ本文を検証します。Content-Type が application/json に設定されていない場合、リクエストのメッセージ本文の検証は自動的に成功になります（実際にコンテンツは検証されません）。
パラメータ	パス、ヘッダー、クエリ、Cookie パラメータなど、必要なパラメータがリクエスト内に存在することを検証します。 パラメータ値が OpenAPI 仕様で定義されているパラメータ値と一致していることを検証します。 必要に応じて、OpenAPI 仕様で定義されていないパラメータがリクエストに存在するかどうかを検証します。<AllowUnspecifiedParameters> を使用してこのオプションを構成します。

次の表に、OASValidation ポリシーによって検証されるレスポンス メッセージの内容をコンポーネント別に示します。

コンポーネント	レスポンスの検証
パス	リクエストパス（ベースパスを除く）が OpenAPI 仕様で定義されているパスパターンのいずれかと一致していることを検証します。
動詞	OpenAPI 仕様のパスに対して動詞が定義されていることを検証します。
レスポンス メッセージの本文	必要に応じて、レスポンスにメッセージ本文が存在することを検証します。 OpenAPI 仕様のレスポンス ヘッダーがレスポンス メッセージに存在することと、レスポンス ヘッダーの値がスキーマと一致していることを検証します。 必要に応じて、OpenAPI 仕様でオペレーションのレスポンス本文のスキーマに照らしてメッセージ本文を検証します。<ValidateMessageBody> を使用してこのオプションを構成します。

サンプル

次の例は、OASValidation ポリシーを使用して OpenAPI 3.0 仕様に照らしてメッセージを検証する方法の一部を示しています。

リクエスト メッセージを検証する

次の例では、myoaspolicy ポリシーを使用して、my-spec.json OpenAPI 仕様で定義されたオペレーションのリクエスト メッセージ本文のスキーマに照らしてリクエスト メッセージの本文を検証します。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

メッセージ本文が OpenAPI 仕様に準拠していない場合は、policies.oasvalidation.Failed エラーが返されます。

パラメータを検証する

次の例では、OpenAPI 仕様で定義されていないヘッダー、クエリ、Cookie パラメータがリクエストで指定されている場合、ポリシーは失敗するように構成されています。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<OASValidation> 要素

OpenAPI Specification Validation ポリシーを定義します。

デフォルト値	下記の [デフォルト ポリシー] タブをご覧ください。
必須かどうか	必須
型	複合オブジェクト
親要素	なし
子要素	<DisplayName> <OASResource> <Source> <Options> <Source>

構文

<OASValidation> 要素の構文は次のとおりです。

<OASValidation
  continueOnError="[true|false]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All OASValidation child elements are optional except OASResource -->
    <DisplayName>policy_display_name</DisplayName>
    <OASResource>validation_JSON_or_YAML</OASResource>
    <Options>
        <ValidateMessageBody>[true|false]</ValidateMessageBody>
        <AllowUnspecifiedParameters>
            <Header>[true|false]</Header>
            <Query>[true|false]</Query>
            <Cookie>[true|false]</Cookie>
        </AllowUnspecifiedParameters>
    </Options>
    <Source>message_to_validate</Source>
</OASValidation>

デフォルト ポリシー

次の例は、Apigee UI でフローに OAS Validation ポリシーを追加する場合のデフォルト設定を示しています。

<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1">
    <DisplayName>OpenAPI Spec Validation-1</DisplayName>
    <Properties/>
    <Source>request</Source>
    <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource>
</OASValidation>

この要素には、すべてのポリシーに共通する次の属性があります。

属性	デフォルト	必須かどうか	説明
name	なし	必須	ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。 管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
continueOnError	false	省略可	ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について） 現在のフローにおける障害処理
enabled	true	省略可	ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async	false	非推奨	この属性は非推奨となりました。

子要素のリファレンス

このセクションでは、<OASValidation> の子要素について説明します。

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

デフォルト値	なし
必須かどうか	省略可。<DisplayName> を省略した場合、ポリシーの name 属性の値が使用されます。
型	文字列
親要素	<PolicyElement>
子要素	なし

<DisplayName> 要素の構文は次のとおりです。

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 要素に属性や子要素はありません。

<OASResource>

検証する OpenAPI 仕様を指定します。このファイルは次の場所に保存できます。

• API プロキシ バンドルの /apiproxy/resources/oas の下にある API プロキシ スコープ
• API プロキシ エディタの [Navigator] ビューの [Resources] セクション

詳しくは、リソースの管理をご覧ください。

メッセージ テンプレート（{oas.resource.url} など）を使用して OpenAPI 仕様を指定できます。この場合、フロー変数 oas.resource.url の値（中かっこ内）が評価され、ランタイム時にペイロード文字列に置き換えられます。詳しくは、メッセージ テンプレートをご覧ください。

デフォルト値	なし
必須かどうか	必須
型	文字列
親要素	<OASValidation>
子要素	なし

構文

<OASResource> 要素の構文は次のとおりです。

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

例

次の例では、API プロキシ バンドルの /apiproxy/resources/oas に保存されている my-spec.yaml 仕様を参照します。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

<OASResource> 要素に属性や子要素はありません。

注: OASValidation ポリシーで、セキュリティ要件がグローバル レベルで設定された <OASResource> が指定されている場合、セキュリティ要件は適用されません。確実に適用するには、このポリシーの <OASResource> 要素で渡される OpenAPI の仕様で、すべてのセキュリティ要件をオペレーション レベルで設定する必要があります。詳細については、Apigee の既知の問題をご覧ください。

<Options>

ポリシーのオプションを構成します。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	<OASValidation>
子要素	<ValidateMessageBody> <AllowUnspecifiedParameters>

構文

<Options> 要素の構文は次のとおりです。

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <ValidateMessageBody>[true|false]</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

例

次の例では、ポリシーのオプションを構成しています。各オプションの詳細については、以下をご覧ください。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>false</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<ValidateMessageBody>

ポリシーを使用して、OpenAPI 仕様のオペレーションのリクエスト本文スキーマに照らしてメッセージ本文を検証する必要があるかどうかを指定します。メッセージ本文の内容を検証するには、true に設定します。メッセージ本文が存在するかどうかだけを検証する場合は false に設定します。

<OASValidation> 要素の continueOnError 属性を true に設定すると、検証エラーの後にフローの実行を継続するかどうかを制御できます。

注: このポリシーは、Content-Type が application/json に設定されている場合にのみ、OpenAPI 仕様に照らしてリクエスト メッセージ本文を検証します。Content-Type が application/json に設定されていない場合、リクエスト メッセージ本文の検証は自動的に成功します（実際にコンテンツは検証されません）。

デフォルト値	false
必須かどうか	省略可
型	ブール値
親要素	<Options>
子要素	なし

構文

<ValidateMessageBody> 要素の構文は次のとおりです。

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
         <ValidateMessageBody>[true|false]</ValidateMessageBody>
   </Options>
   ...
</OASValidation>

例

次の例では、メッセージ本文の内容の検証を有効にしています。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
</OASValidation>

<AllowUnspecifiedParameters>

OpenAPI 仕様で定義されていないヘッダー、クエリ、Cookie パラメータがリクエストに存在している場合のポリシーの動作を構成します。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	<Options>
子要素	<Header> <Query> <Cookie>

構文

<AllowUnspecifiedParameters> 要素の構文は次のとおりです。

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

例

次の例では、OpenAPI 仕様で定義されていないヘッダー、クエリ、Cookie パラメータがリクエストで指定されている場合、ポリシーは失敗するように構成されています。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Header>（<AllowUnspecifiedParameters> の子）

OpenAPI 仕様で定義されていないヘッダー パラメータがリクエストに存在している場合のポリシーの動作を構成します。

OpenAPI 仕様で定義されていないヘッダー パラメータをリクエストで指定できるようにするには、このパラメータを true に設定します。それ以外の場合は、このパラメータを false に設定してポリシーの実行が失敗するようにします。

デフォルト値	true
必須かどうか	ブール値
型	複合型
親要素	<AllowUnspecifiedParameters>
子要素	なし

構文

<Header> 要素の構文は次のとおりです。

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

例

次の例では、OpenAPI 仕様で定義されていないヘッダー パラメータがリクエストで指定されている場合、ポリシーは失敗するように構成されています。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Query>（<AllowUnspecifiedParameters> の子）

OpenAPI 仕様で定義されていないクエリ パラメータがリクエストに存在する場合のポリシーの動作を構成します。

OpenAPI 仕様で定義されていないクエリ パラメータをリクエストで指定できるようにするには、このパラメータを true に設定します。それ以外の場合は、このパラメータを false に設定してポリシーの実行が失敗するようにします。

デフォルト値	true
必須かどうか	ブール値
型	複合型
親要素	<AllowUnspecifiedParameters>
子要素	なし

構文

<Query> 要素の構文は次のとおりです。

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

例

次の例では、OpenAPI 仕様で定義されていないクエリ パラメータがリクエストで指定されている場合、ポリシーは失敗するように構成されています。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Cookie>（<AllowUnspecifiedParameters> の子）

OpenAPI 仕様で定義されていない Cookie パラメータがリクエストに存在する場合のポリシーの動作を構成します。

OpenAPI 仕様で定義されていない Cookie パラメータをリクエストで指定できるようにするには、このパラメータを true に設定します。それ以外の場合は、このパラメータを false に設定してポリシーの実行が失敗するようにします。

デフォルト値	true
必須かどうか	ブール値
型	複合型
親要素	<AllowUnspecifiedParameters>
子要素	なし

構文

<Cookie> 要素の構文は次のとおりです。

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

例

次の例では、OpenAPI 仕様で定義されていないクエリ パラメータがリクエストで指定されている場合、ポリシーは失敗するように構成されています。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Source>

JSON ペイロード攻撃に対して評価される JSON メッセージ。通常はクライアント アプリからの受信リクエストを評価する必要があるため、これは一般的に request に設定されます。レスポンス メッセージを評価するには、response に設定します。message に設定すると、ポリシーがリクエスト フローに接続されたときはリクエスト メッセージを自動的に評価し、ポリシーがレスポンス フローに接続されたときはレスポンス メッセージを評価します。

デフォルト値	リクエスト
必須かどうか	省略可
型	文字列
親要素	<Source>
子要素	なし

構文

<Source> 要素の構文は次のとおりです。

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Source>[message|request|response]</Source>
   ...
</OASValidation>

例

次の例では、ポリシーがリクエスト フローに接続されたときはリクエスト メッセージを自動的に評価し、ポリシーがレスポンス フローに接続されたときはレスポンス メッセージを評価します。

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Source>message</Source>
</OASValidation>

<Source> 要素には属性も子要素もありません。

スキーマ

各ポリシータイプは XML スキーマ（.xsd）によって定義されます。参照用のポリシー スキーマは GitHub から入手できます。

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード	HTTP ステータス	原因
steps.oasvalidation.Failed	400	リクエスト メッセージの本文が、指定された OpenAPI 仕様に対して検証できません。
steps.oasvalidation.Failed	500	レスポンス メッセージの本文が、指定された OpenAPI 仕様に対して検証できません。
steps.oasvalidation.SourceMessageNotAvailable	500	ポリシーの <Source> 要素で指定された変数が範囲外であるか、解決できません。
steps.oasvalidation.NonMessageVariable	500	<Source> 要素が、message 型以外の変数に設定されています。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名	原因
ResourceDoesNotExist	<OASResource> 要素で参照されている OpenAPI 仕様が存在しません。
ResourceCompileFailed	デプロイに含まれている OpenAPI 仕様に、コンパイルを妨げるエラーが存在します。これは通常、仕様が正しい形式の OpenAPI 仕様 3.0 ではないことを示しています。
BadResourceURL	<OASResource> 要素で参照されている OpenAPI 仕様が処理できません。これは、ファイルが JSON または YAML ファイルでない場合、またはファイルの URL が正しく指定されていない場合に発生することがあります。

障害変数

次の変数は、このポリシーでランタイム エラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数	説明	例
fault.category	障害のカテゴリ。ポリシーでリクエストが拒否された場合、常に Step が保持されます。	fault.category = "Step"
fault.name	障害の名前は、上記のランタイム エラーの表に記載されています。障害名は、障害コードの最後の部分です。	fault.name Matches "ResourceDoesNotExist"
fault.reason	障害の理由。障害の理由です。人が読める形式の文字列で示されます。	OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory	障害のサブカテゴリ。ポリシーでリクエストが拒否された場合、常に OASValidationFailure が保持されます。	fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed	policy_name は、障害が発生したポリシーのユーザー指定の名前です。	OASValidation.myoaspolicy.failed = true

サポートされる OpenAPI 仕様の機能

OASValidation ポリシーは、次の表にカテゴリ別にまとめられている OpenAPI 仕様の機能に対応しています。サポート対象外の機能も表示されています。

注: OASValidation ポリシーでは、サポート対象外の機能を使用する OpenAPI 仕様は拒否されます。この場合、ポリシーはサポート対象外の機能の検証に合格せず、API プロキシのデプロイは失敗します。

カテゴリ	サポート対象	サポート対象外
データ型の形式	boolean date date-time double email float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid	binary byte password
識別オブジェクト	mapping propertyName	なし
メディアタイプ オブジェクト	schema	encoding example examples
オペレーション オブジェクト	parameters requestBody responses security（部分サポート）	callbacks deprecated servers
パラメータ オブジェクト	allowEmptyValue in（query、header、path） required responses schema style（deepObject、form、formmatrix、label、pipeDelimited、simple、spaceDelimited） 注: deepObject では文字列パラメータのみがサポートされ、配列やネストされたオブジェクトはサポートされません。	allowReserved deprecated example examples content
パス オブジェクト	delete get head options parameters patch post put trace variables	servers
リクエスト本文オブジェクト	application/json application/hal+json application/x-www-form-urlencoded（encoding オブジェクトは対象外） content required	application/xml multipart/form-data text/plain text/xml
レスポンス オブジェクト	application/json application/hal+json application/x-www-form-urlencoded（encoding オブジェクトは対象外） content headers	application/xml links text/plain text/xml
レスポンス オブジェクト	default HTTP ステータス コード	なし
スキーマ オブジェクト	$ref additionalProperties（ブール値のフラグ バリアントのみ） allOf（additionalProperties が false の場合は無視） anyOf enum exclusiveMaximum/exclusiveMinimum format items maximum/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf not nullable oneOf pattern properties required title type uniqueItems	deprecated example readOnly writeOnly xml
セキュリティ スキーマ オブジェクト	in（header、query）（type が http の場合は無視） name type（apiKey、http）	bearerFormat flows openIdConnectUrl scheme
サーバー オブジェクト	url variables	複数サーバーの定義

関連トピック

• JSON Threat Protection ポリシー
• SOAPMessageValidation ポリシー