APIデプロイメントへのリクエスト検証の追加

API Gatewayによる検証リクエスト・ポリシーに対して受信リクエストを検証することで、無効なリクエストがバックエンド・サービスに送信されないようにする方法をご紹介します。

通常、バックエンド・サービスに不要な負荷をかけないようにするには、有効なリクエストをそれらのサービスに送信するだけです。無効なリクエストがバックエンド・サービスに送信されないようにするには、APIゲートウェイを使用して、受信リクエストを検証リクエスト・ポリシーに対して検証します。リクエストが検証ポリシー要件を満たさない場合は、ターゲット・バックエンド・サービスにリクエストを渡すのではなく、リクエストを拒否するようにAPIゲートウェイを構成できます。かわりに、APIゲートウェイは、リクエストを送信したAPIクライアントに4xxエラー・コード・レスポンスを送信します。

APIゲートウェイを使用して、検証リクエスト・ポリシーを設定し、次をチェックできます:

リクエストには特定のヘッダーが含まれます
リクエストに特定の問合せパラメータが含まれる
リクエスト本文は特定のコンテンツ・タイプです

APIゲートウェイが検証リクエスト・ポリシーを適用する方法を制御するには、ポリシーの検証モードを指定します:

強制モードでは、APIゲートウェイは検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。APIゲートウェイは、検証に失敗したリクエストをバックエンド・サービスに送信しません。APIゲートウェイは、検証に失敗したリクエストを送信するAPIクライアントに4xxエラー・コード・レスポンスを送信します。APIゲートウェイには、検証エラーのための実行ログのエントリが含まれます。
許可モードでは、APIゲートウェイは検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したか失敗したかに関係なく、すべてのリクエストをバックエンド・サービスに送信します。検証に失敗したリクエストは、引き続きバックエンド・サービスに送信されることに注意してください。APIゲートウェイには、検証エラーのための実行ログのエントリが含まれます。許可モードを使用して、現在リクエストを送信しているAPIクライアントに影響を与えずに、本番システムにすでに存在するシステムに検証リクエスト・ポリシーを適用した場合の影響を評価します。
無効モードでは、APIゲートウェイは検証リクエスト・ポリシーに対してリクエストを検証しません。APIゲートウェイは、すべてのリクエストをバックエンド・サービスに送信します。

APIゲートウェイは、CORSリクエスト・ポリシーの後、認証および認可リクエスト・ポリシーの後、変換リクエスト・ポリシーの前に検証リクエスト・ポリシーを適用します。

次を実行して、検証リクエスト・ポリシーを追加できます:

コンソールの使用
JSONファイルの編集

コンソールを使用した検証リクエスト・ポリシーの追加

コンソールを使用してAPIデプロイメント仕様に検証リクエスト・ポリシーを追加するには:

コンソールを使用してAPIデプロイメントを作成し、「最初から」オプションを選択して、「基本情報」ページで詳細を入力します。

詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイの更新を参照してください。
「次へ」を選択し、「認証」ページで認証オプションを指定します。

認証オプションの詳細は、APIデプロイメントへの認証と認可の追加を参照してください。
「次」を選択し、「ルート」ページのAPIデプロイメント内の個々のルートの詳細を入力します。
「ルート」ページで、検証リクエスト・ポリシーを指定するルートを選択します。
「ルート・リクエスト・ポリシーの表示」を選択します。
ヘッダー検証リクエスト・ポリシーを作成して、現在のルートのAPIゲートウェイへのリクエストに含まれるヘッダーを検証するには:
1. 「ヘッダー検証」の横にある「追加」ボタンを選択し、検証するリクエストの最初のヘッダーの詳細を指定します:
  - ヘッダー名:検証するリクエストのヘッダーの名前。たとえば、X-Username です。
  - 必須:指定したヘッダーが、リクエストが有効とみなされるようにリクエストに存在する必要があるかどうか。
2. (オプション)「別のヘッダー」を選択し、検証するリクエストに追加のヘッダーを指定します。
3. 「拡張オプションの表示」を選択し、「モード」を選択して、ヘッダー検証リクエスト・ポリシーの適用方法を指定します:
  - 強制: APIゲートウェイは、検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。
  - 許可: APIゲートウェイは、すべてのリクエストを検証リクエスト・ポリシーに対して検証します。APIゲートウェイは、検証に合格したか失敗したかに関係なく、すべてのリクエストをバックエンド・サービスに送信します。
  - 無効: APIゲートウェイは、検証リクエスト・ポリシーに対してリクエストを検証しません。APIゲートウェイは、すべてのリクエストをバックエンド・サービスに送信します。
  「強制」がデフォルトの検証モードであることに注意してください。
4. 「検証の追加」を選択します。
問合せパラメータ検証リクエスト・ポリシーを作成して、現在のルートのAPIゲートウェイへのリクエストに含まれる問合せパラメータを検証するには:
1. 「問合せパラメータ検証」の横にある「追加」ボタンを選択し、検証するリクエストの最初の問合せパラメータの詳細を指定します。
  - パラメータ名:検証するリクエストの問合せパラメータの名前。たとえば、stateです。
  - 必須:指定した問合せパラメータが、リクエストが有効とみなされるようにリクエストに存在する必要があるかどうか。
2. (オプション)「別のパラメータ」を選択し、検証するリクエストに追加の問合せパラメータを指定します。
3. 「拡張オプションの表示」を選択し、「モード」を選択して、問合せパラメータ検証リクエスト・ポリシーの適用方法を指定します:
  - 強制: APIゲートウェイは、検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。
  - 許可: APIゲートウェイは、すべてのリクエストを検証リクエスト・ポリシーに対して検証します。APIゲートウェイは、検証に合格したか失敗したかに関係なく、すべてのリクエストをバックエンド・サービスに送信します。
  - 無効: APIゲートウェイは、検証リクエスト・ポリシーに対してリクエストを検証しません。APIゲートウェイは、すべてのリクエストをバックエンド・サービスに送信します。
  「強制」がデフォルトの検証モードであることに注意してください。
4. 「検証の追加」を選択します。
本文検証リクエスト・ポリシーを作成して、現在のルートのAPIゲートウェイへのリクエストの本文のコンテンツを検証するには:
1. 「本文検証」の横にある「追加」ボタンを選択し、次を指定します:
  - 必須:リクエストの本文が有効とみなされるように指定するコンテンツ・タイプのいずれかである必要があります。
  - メディア・タイプ:リクエストの本文の有効なコンテンツ・タイプ。たとえば、application/json、application/xmlです。
2. (オプション)「別のメディア・タイプ」を選択し、リクエストの本文に追加の有効なコンテンツ・タイプを指定します。
  複数のコンテンツ・タイプを指定する場合、リクエスト本文は、リクエストが有効とみなされるように指定する許可されたコンテンツ・タイプの1つである必要があります。
3. 「拡張オプションの表示」を選択し、「モード」を選択して、本文検証リクエスト・ポリシーの適用方法を指定します:
  - 強制: APIゲートウェイは、検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。
  - 許可: APIゲートウェイは、すべてのリクエストを検証リクエスト・ポリシーに対して検証します。APIゲートウェイは、検証に合格したか失敗したかに関係なく、すべてのリクエストをバックエンド・サービスに送信します。
  - 無効: APIゲートウェイは、検証リクエスト・ポリシーに対してリクエストを検証しません。APIゲートウェイは、すべてのリクエストをバックエンド・サービスに送信します。
  「強制」がデフォルトの検証モードであることに注意してください。
4. 「検証の追加」を選択します。
「次」を選択して、個々のルートに入力した詳細を確認します。
APIデプロイメントを作成または更新するには、「作成」または「変更の保存」を選択します。
(オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

検証リクエスト・ポリシーを追加するためのJSONファイルの編集

JSONファイルのAPIデプロイメント仕様に検証リクエスト・ポリシーを追加するには:

任意のJSONエディタを使用して、検証リクエスト・ポリシーを追加する既存のAPIデプロイメント仕様を編集するか、新しいAPIデプロイメント仕様を作成します(APIデプロイメント仕様の作成を参照)。

たとえば、次の基本的なAPIデプロイメント仕様では、OCI Functionsの単純なHello Worldサーバーレス・ファンクションを単一のバック・エンドとして定義しています:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

検証リクエスト・ポリシーを適用するルートのbackendセクションの後にrequestPoliciesセクションを挿入します。例:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}

現在のルートのAPIゲートウェイへのリクエストに含まれるヘッダーを検証するには、headerValidations検証リクエスト・ポリシーを指定します:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "headerValidations": {
          "headers": {
            "name": "<header-name>",
            "required": <true|false>
          },
          "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"
        }
      }
    }
  ]
}
```
ここでは:
- "name":"<header-name>"は、検証するリクエストのヘッダーです。指定した名前では、大/小文字は区別されません。たとえば、X-Usernameです。
- "required": <true|false>は、リクエストが有効とみなされるために、"name":"<header-name>"で指定されたヘッダーがリクエストに存在する必要があるかどうかを示します。
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"は、次のように、APIゲートウェイがヘッダー検証リクエスト・ポリシーに対してリクエストを検証する方法を示します:
  - ENFORCING: APIゲートウェイは、検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。
  - PERMISSIVE: APIゲートウェイは、検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したか失敗したかに関係なく、すべてのリクエストをバックエンド・サービスに送信します。
  - DISABLED: APIゲートウェイは、検証リクエスト・ポリシーに対してリクエストを検証しません。APIゲートウェイは、すべてのリクエストをバックエンド・サービスに送信します。
  たとえば、"validationMode": "PERMISSIVE"です。"validationMode"を含めない場合は、ENFORCINGがデフォルトの検証モードとして使用されることに注意してください。
例:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "headerValidations": {
          "headers": {
            "name": "X-Username",
            "required": true
          },
          "validationMode": "ENFORCING"
        }
      }
    }
  ]
}
```
この例では、リクエストが有効とみなされるためには、リクエストにX-Usernameヘッダーが含まれている必要があります。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。
現在のルートのAPIゲートウェイへのリクエストに含まれる問合せパラメータを検証するには、queryParameterValidations検証リクエスト・ポリシーを指定します:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterValidations": {
          "parameters": {
            "name": "<query-parameter-name>",
            "required": <true|false>
          },
          "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"
        }
      }
    }
  ]
}
```
ここでは:
- "name":"<query-parameter-name>"は、検証するリクエストの問合せパラメータです。指定した名前では、大/小文字は区別されません。たとえば、stateです。
- "required": <true|false>は、リクエストが有効とみなされるために、"name":"<query-parameter-name>"で指定された問合せパラメータがリクエストに存在する必要があるかどうかを示します。
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"は、次のように、APIゲートウェイが問合せパラメータ検証リクエスト・ポリシーに対してリクエストをどのように検証するかを示します。
  - ENFORCING: APIゲートウェイは、検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。
  - PERMISSIVE: APIゲートウェイは、検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したか失敗したかに関係なく、すべてのリクエストをバックエンド・サービスに送信します。
  - DISABLED: APIゲートウェイは、検証リクエスト・ポリシーに対してリクエストを検証しません。APIゲートウェイは、すべてのリクエストをバックエンド・サービスに送信します。
  たとえば、"validationMode": "PERMISSIVE"です。"validationMode"を含めない場合は、ENFORCINGがデフォルトの検証モードとして使用されることに注意してください。
例:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterValidations": {
          "parameters": {
            "name": "state",
            "required": false
          },
          "validationMode": "ENFORCING"
        }
      }
    }
  ]
}
```
この例では、リクエストが有効とみなされるように、リクエストにオプションでstate問合せパラメータを含めることができます。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。
現在のルートのAPIゲートウェイへのリクエストの本文の内容を検証するには、bodyValidation検証リクエスト・ポリシーを指定します:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "bodyValidation": {
          "required": true,
          "content": {
            "<media-type-1>": {
              "validationType": "NONE"
            },
            "<media-type-2>": {
              "validationType": "NONE"
            }            
          },
          "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"
        }
      }
    }
  ]
}
```
ここでは:
- "required": trueは、リクエスト本文のコンテンツ・タイプが、指定したコンテンツ・タイプのいずれかである必要があることを示します。
- "content": {"<media-type-1>": {"validationType": "NONE"}, "<media-type-2>": {"validationType": "NONE"}}は、リクエスト本文で許可される1つ以上のコンテンツ・タイプを示します。リクエスト本文は、指定するコンテンツ・タイプの1つである必要があります。たとえば、application/json、application/xml。現在、"validationType"ではNONEのみがサポートされています。
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>"は、APIゲートウェイが本文検証リクエスト・ポリシーに対してリクエストをどのように検証するかを示します。
  - ENFORCING: APIゲートウェイは、検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。
  - PERMISSIVE: APIゲートウェイは、検証リクエスト・ポリシーに対してすべてのリクエストを検証します。APIゲートウェイは、検証に合格したか失敗したかに関係なく、すべてのリクエストをバックエンド・サービスに送信します。
  - DISABLED: APIゲートウェイは、検証リクエスト・ポリシーに対してリクエストを検証しません。APIゲートウェイは、すべてのリクエストをバックエンド・サービスに送信します。
  たとえば、"validationMode": "PERMISSIVE"です。"validationMode"を含めない場合は、ENFORCINGがデフォルトの検証モードとして使用されることに注意してください。
例:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "bodyValidation": {
          "required": true,
          "content": {
            "application/json": {
              "validationType": "NONE"
            },
            "application/xml": {
              "validationType": "NONE"
            }
          },
          "validationMode": "ENFORCING"
        }
      }
    }
  ]
}
```
この例では、リクエストが有効とみなされるためには、リクエスト本文のコンテンツ・タイプがapplication/jsonまたはapplication/xmlである必要があります。APIゲートウェイは、検証に合格したリクエストのみをバックエンド・サービスに送信します。
APIデプロイメント仕様を含むJSONファイルを保存します。
APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:
- JSONファイルをコンソールで「既存のAPIのアップロード」オプションで指定します
- APIゲートウェイREST APIへのリクエストでJSONファイルを指定します
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイの更新を参照してください。
(オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

Oracle Cloud Infrastructureドキュメント

APIデプロイメントへのリクエスト検証の追加

コンソールを使用した検証リクエスト・ポリシーの追加

検証リクエスト・ポリシーを追加するためのJSONファイルの編集