OASValidation ポリシー（ベータ版）

ベータ版リリースについて

これは OASValidation ポリシーのベータ版です。詳細については、プロダクトのリリースステージをご覧ください。

次の点にご注意ください。

OASValidation ポリシーのベータ版は、Apigee ハイブリッドのみで利用できます。
ベータ版リリースの場合、OASValidation ポリシーでは、サポート対象の OpenAPI 仕様の機能で定義されている OpenAPI 仕様の機能がサポートされます。 OASValidation ポリシーでは、サポート対象外の機能を使用する OpenAPI 仕様が拒否されません。代わりに、サポート対象外の機能の検証が自動的にパスします（実際には機能は検証されません）。たとえば、application/xml が仕様で有効なコンテンツタイプとして指定されている場合、そのコンテンツタイプのリクエストメッセージ本文のコンテンツ検証が自動的にパスします。

OASValidation ポリシーについて

OASValidation（OpenAPI Specification Validation）ポリシーを使用すると、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>` を使用してこのオプションを構成します。注: ベータ版では、コンテンツタイプが `application/json` に設定されている場合にのみ、OpenAPI 仕様に対してリクエストのメッセージ本文が検証されます。コンテンツタイプが `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>

デフォルトポリシー

次の例は、Edge 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	省略可	ポリシーを適用するには「true」に設定します。ポリシーを「turn off」するには、「false」に設定します。false に設定すると、ポリシーがフローに接続されている場合でも適用されません。
`async`	false	非推奨	この属性は非推奨となりました。

子要素のリファレンス

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

`<DisplayName>`

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

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

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

構文

    <PolicyElement>
      <DisplayName>policy_display_name</DisplayName>
      ...
    </PolicyElement>

例

    <AssignMessage>
      <DisplayName>My Validation Policy</DisplayName>
    </AssignMessage>

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

`<OASResource>`

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

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

詳しくは、リソースの管理に関するページをご覧ください。

OpenAPI 仕様は、{oas.resource.url} などのメッセージテンプレートを使用して指定できます。この場合、フロー変数 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 に設定すると、検証エラー後にフローの実行を継続するかどうかを制御できます。

注: ベータ版では、コンテンツタイプが application/json に設定されている場合にのみ、OpenAPI 仕様に対してリクエストのメッセージ本文が検証されます。コンテンツタイプが 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>

例

<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 から入手できます。

エラーコード

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.oasvalidation.Failed`	500	Request message body cannot be validated against the provided OpenAPI Specification.
`steps.oasvalidation.SourceMessageNotAvailable`	500	Variable specified in the `<Source>` element of the policy is either out of scope or cannot be resolved.
`steps.oasvalidation.NotMessageVariable`	500	`<Source>` element is set to a variable that is not of type message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
`ResourceDoesNotExist`	OpenAPI Specification referenced in the `<OASResource>` element does not exist.
`ResourceCompileFailed`	OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
`BadResourceURL`	OpenAPI Specification referenced in the `<OASResource>` element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "ResourceDoesNotExist"`
`oasvalidation.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`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（`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	複数のサーバーの定義

OASValidation ポリシー（ベータ版）

ベータ版リリースについて

OASValidation ポリシーについて

検証するコンテンツ

サンプル

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

パラメータを検証する

<OASValidation> 要素

構文

デフォルト ポリシー

子要素のリファレンス

<DisplayName>

構文

例

<OASResource>

構文

例

<Options>

構文

例

<ValidateMessageBody>

構文

例

<AllowUnspecifiedParameters>

構文

例

構文

例

構文

例

構文

例

<Source>

構文

例

スキーマ

エラーコード

Runtime errors

Deployment errors

Fault variables

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

関連トピック

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

`<OASValidation>` 要素

デフォルトポリシー

`<DisplayName>`

`<OASResource>`

`<AllowUnspecifiedParameters>`

`<Source>`