OASValidation ポリシー

Apigee X のドキュメントが表示されています。
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 プロキシ バンドルに追加します。

検証するコンテンツ

次の表に、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 ポリシーを定義します。

デフォルト値 下記の [Default Policy] タブをご覧ください。
必須 必須
複合オブジェクト
親要素 なし
子要素 <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 文字を超えることはできません。

必要に応じて <DisplayName> 要素を使用して、管理 UI プロキシ エディタのポリシーに別の自然言語の名前でラベルを付けます。

continueOnError false 任意 ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される挙動です。ポリシーが失敗してもフローの実行を続けるには true に設定します。
enabled はい 任意 ポリシーを適用するには、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> 要素には属性も子要素もありません。

<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 に設定すると、エラーの検証後にフローの実行を継続するかどうかを制御できます。

デフォルト値 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>

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>

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 500 リクエスト メッセージの本文が、指定された OpenAPI 仕様に対して検証できない。
steps.oasvalidation.SourceMessageNotAvailable 500

ポリシーの <Source> 要素で指定された変数が範囲外であるか、解決できない。

steps.oasvalidation.NotMessageVariable 500

<Source> 要素が、メッセージ型以外の変数に設定されている。

デプロイエラー

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

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

障害変数

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

変数 ここで
fault.name="fault_name" fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 fault.name Matches "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name は、障害をスローしたポリシーのユーザー指定の名前です。 oasvalidation.myoaspolicy.failed = true

サポート対象の OpenAPI 仕様の機能

OASValidation ポリシーでは、次の表でカテゴリ別にまとめられている OpenAPI 仕様の機能がサポートされています。サポートされていない機能も記載されています。

カテゴリ サポート対象 サポート対象外
データ型の形式 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(queryheaderpath
required
responses
schema
style(deepObjectformformmatrixlabelpipeDelimitedsimplespaceDelimited

注: 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(additionalPropertiesfalse の場合は無視されます)
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(headerquery)(typehttp の場合は無視されます)
name
type(apiKeyhttp
bearerFormat
flows
openIdConnectUrl
scheme
サーバー オブジェクト url
variables
複数のサーバーの定義

関連トピック