ベータ版リリースについて
これは 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 仕様のパスに対して動詞が定義されていることを検証します。 |
| リクエスト メッセージの本文 |
注: ベータ版では、コンテンツ タイプが |
| パラメータ |
|
次の表に、OASValidation ポリシーによって検証されるレスポンス メッセージの内容をコンポーネント別に示します。
| コンポーネント | レスポンスの検証 |
|---|---|
| パス | リクエストパス（ベースパスを除く）が OpenAPI 仕様で定義されているパスパターンのいずれかと一致していることを検証します。 |
| 動詞 | OpenAPI 仕様のパスに対して動詞が定義されていることを検証します。 |
| レスポンス メッセージの本文 |
|
サンプル
次の例は、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>
この要素には、すべてのポリシーに共通する次の属性があります。
| 属性 | デフォルト | 必須？ | Description |
|---|---|---|---|
name |
なし | 必須 |
ポリシーの内部名。 必要に応じて |
continueOnError |
false | 省略可 | ポリシーが失敗したときにエラーを返すには、「false」に設定します。これはほとんどのポリシーで想定される挙動です。ポリシーが失敗した後でも、フローの実行を続行するには、「true」に設定します。 |
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セクション。
詳しくは、リソースの管理に関するページをご覧ください。
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 に設定すると、検証エラー後にフローの実行を継続するかどうかを制御できます。
| デフォルト値 | 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>
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 から入手できます。
エラーコード
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
| 障害コード | HTTP ステータス | 原因 | |
|---|---|---|---|
steps.oasvalidation.Failed |
500 | リクエスト メッセージの本文が、指定された OpenAPI 仕様に対して検証できない。 | |
steps.oasvalidation.SourceMessageNotAvailable |
500 |
ポリシーの |
|
steps.oasvalidation.NotMessageVariable |
500 |
|
build |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
| エラー名 | 原因 | |
|---|---|---|
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 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 |
複数のサーバーの定義 |