Adición de validación de solicitud a despliegues de API

Descubra cómo evitar que se envíen solicitudes no válidas a servicios de backend validando las solicitudes entrantes en una política de solicitud de validación con API Gateway.

Normalmente, desea evitar colocar cargas innecesarias en los servicios de backend enviando solo solicitudes válidas a esos servicios. Para evitar que se envíen solicitudes no válidas a servicios de backend, puede utilizar un gateway de API para validar las solicitudes entrantes con una política de solicitud de validación. Si una solicitud no cumple los requisitos de la política de validación, puede configurar el gateway de API para rechazar la solicitud en lugar de transferirla al servicio de backend de destino. En su lugar, el gateway de API envía una respuesta de código de error 4xx al cliente de API que envió la solicitud.

Mediante un gateway de API, puede configurar políticas de solicitud de validación para comprobarlo:

la solicitud incluye encabezados específicos
la solicitud incluye parámetros de consulta específicos
el cuerpo de solicitud es de un tipo de contenido específico

Puede controlar cómo un gateway de API aplica una política de solicitud de validación especificando un modo de validación para la política:

En el modo de aplicación, el gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API solo envía solicitudes que pasan la validación al servicio de backend. El gateway de API no envía solicitudes que no superan la validación al servicio de backend. El gateway de API envía una respuesta de código de error 4xx a un cliente de API que envía una solicitud que falla en la validación. El gateway de API incluye entradas en los logs de ejecución para los errores de validación.
En el modo permisivo, el gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend, independientemente de si pasan o no la validación. Tenga en cuenta que las solicitudes que fallan en la validación se siguen enviando al servicio de backend. El gateway de API incluye entradas en los logs de ejecución para los errores de validación. Utilice el modo permisivo para evaluar el impacto probable de aplicar una política de solicitud de validación a un sistema que ya está en el sistema de producción, sin afectar a los clientes de API que actualmente envían solicitudes.
En el modo Desactivado, el gateway de API no valida ninguna solicitud con respecto a la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend.

El gateway de API aplica políticas de solicitud de validación después de las políticas de solicitud de CORS y después de las políticas de solicitud de autenticación y autorización, pero antes de las políticas de solicitud de transformación.

Puede agregar políticas de solicitud de validación a una especificación de despliegue de API mediante:

uso de la consola
edición de un archivo JSON

Uso de la consola para agregar políticas de solicitud de validación

Para agregar políticas de solicitud de validación a una especificación de despliegue de API mediante la consola:

Cree o actualice un despliegue de API con la consola, seleccione la opción Desde cero e introduzca los detalles en la página Información básica.

Para obtener más información, consulte Despliegue de una API en un gateway de API mediante la creación de un despliegue de API y Actualización de un gateway de API.
Seleccione Siguiente y especifique las opciones de autenticación en la página Autenticación.

Para obtener más información sobre las opciones de autenticación, consulte Agregación de autenticación y autorización a despliegues de API.
Seleccione Siguiente e introduzca detalles de rutas individuales en el despliegue de API en la página Rutas.
En la página Rutas, seleccione la ruta para la que desea especificar políticas de solicitud de validación.
Seleccione Mostrar políticas de solicitud de ruta.
Para validar las cabeceras incluidas en una solicitud en el gateway de API para la ruta actual mediante la creación de una política de solicitud de validación de cabecera:
1. Seleccione el botón Agregar junto a Validaciones de cabecera y especifique los detalles de la primera cabecera de la solicitud que validar:
  - Nombre de cabecera: nombre de una cabecera en la solicitud para validar. Por ejemplo, X-Username .
  - Necesario: indica si la cabecera especificada debe estar presente en la solicitud para que la solicitud se considere válida.
2. (Opcional) Seleccione Otra cabecera y especifique cabeceras adicionales en la solicitud para validar.
3. Seleccione Mostrar opciones avanzadas y seleccione un modo para especificar cómo se aplica la política de solicitud de validación de cabecera:
  - Aplicación: el gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API solo envía solicitudes que transfieren la validación al servicio backend.
  - Permiso: el gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend, independientemente de si pasan o no la validación.
  - Desactivado: el gateway de API no valida ninguna solicitud con respecto a la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend.
  Tenga en cuenta que Aplicación es el modo de validación por defecto.
4. Seleccione Agregar validaciones.
Para validar los parámetros de consulta incluidos en una solicitud en el gateway de API para la ruta actual mediante la creación de una política de solicitud de validación de parámetros de consulta:
1. Seleccione el botón Agregar junto a Validaciones de Parámetros de Consulta y especifique los detalles del primer parámetro de consulta en la solicitud que validar:
  - Nombre de parámetro: nombre de un parámetro de consulta en la solicitud para validar. Por ejemplo, state .
  - Necesario: si el parámetro de consulta especificado debe estar presente en la solicitud para que la solicitud se considere válida.
2. (Opcional) Seleccione Otro parámetro y especifique parámetros de consulta adicionales en la solicitud para validar.
3. Seleccione Mostrar opciones avanzadas y seleccione un modo para especificar cómo se aplica la política de solicitud de validación de parámetros de consulta:
  - Aplicación: el gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API solo envía solicitudes que transfieren la validación al servicio backend.
  - Permiso: el gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend, independientemente de si pasan o no la validación.
  - Desactivado: el gateway de API no valida ninguna solicitud con respecto a la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend.
  Tenga en cuenta que Aplicación es el modo de validación por defecto.
4. Seleccione Agregar validaciones.
Para validar el contenido del cuerpo de una solicitud en el gateway de API para la ruta actual mediante la creación de una política de solicitud de validación de cuerpo:
1. Seleccione el botón Agregar junto a Validación de cuerpo y especifique:
  - Necesario: indica si el cuerpo de una solicitud debe ser uno de los tipos de contenido que especifique para que la solicitud se considere válida.
  - Tipo de medio: tipo de contenido válido para el cuerpo de una solicitud. Por ejemplo, application/json, application/xml.
2. (Opcional) Seleccione Otro tipo de medio y especifique tipos de contenido válidos adicionales para el cuerpo de la solicitud.
  Si especifica varios tipos de contenido, el cuerpo de la solicitud debe ser uno de los tipos de contenido permitidos que especifique para que la solicitud se considere válida.
3. Seleccione Mostrar Opciones Avanzadas y seleccione un Modo para especificar cómo se aplica la política de solicitud de validación de cuerpo:
  - Aplicación: el gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API solo envía solicitudes que transfieren la validación al servicio backend.
  - Permiso: el gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend, independientemente de si pasan o no la validación.
  - Desactivado: el gateway de API no valida ninguna solicitud con respecto a la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend.
  Tenga en cuenta que Aplicación es el modo de validación por defecto.
4. Seleccione Agregar validaciones.
Seleccione Siguiente para revisar los detalles introducidos para las rutas individuales.
Seleccione Crear o Guardar cambios para crear o actualizar el despliegue de API.
(Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Edición de un archivo JSON para agregar políticas de solicitud de validación

Para agregar políticas de solicitud de validación a una especificación de despliegue de API en un archivo JSON:

Con su editor de JSON preferido, edite la especificación de despliegue de API existente a la que desea agregar políticas de solicitud de validación o cree una nueva especificación de despliegue de API (consulte Creación de una especificación de despliegue de API).

Por ejemplo, la siguiente especificación básica de despliegue de API define una función sencilla de Hello World sin servidor en OCI Functions como un único backend:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

Introduzca una sección requestPolicies después de la sección backend para la ruta a la que desea aplicar la política de solicitud de validación. Por ejemplo:

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

Para validar las cabeceras incluidas en una solicitud en el gateway de API para la ruta actual, especifique una política de solicitud de validación 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>"
        }
      }
    }
  ]
}
```
donde:
- "name":"<header-name>" es una cabecera de la solicitud que se va a validar. El nombre que especifique no es sensible a mayúsculas y minúsculas. Por ejemplo, X-Username.
- "required": <true|false> indica si la cabecera especificada por "name":"<header-name>" debe estar presente en la solicitud para que la solicitud se considere válida.
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>" indica cómo el gateway de API valida las solicitudes en la política de solicitud de validación de cabecera, de la siguiente forma:
  - ENFORCING: El gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API solo envía solicitudes que pasan la validación al servicio de backend.
  - PERMISSIVE: El gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend, independientemente de si pasan o no la validación.
  - DISABLED: El gateway de API no valida ninguna solicitud con respecto a la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend.
  Por ejemplo, "validationMode": "PERMISSIVE". Tenga en cuenta que ENFORCING se utiliza como modo de validación por defecto si no incluye "validationMode".
Por ejemplo:
```
{
  "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"
        }
      }
    }
  ]
}
```
En este ejemplo, para que la solicitud se considere válida, la solicitud debe incluir la cabecera X-Username. El gateway de API solo envía solicitudes que pasan la validación al servicio de backend.
Para validar los parámetros de consulta incluidos en una solicitud en el gateway de API para la ruta actual, especifique una política de solicitud de validación 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>"
        }
      }
    }
  ]
}
```
donde:
- "name":"<query-parameter-name>" es un parámetro de consulta en la solicitud para validar. El nombre que especifique no es sensible a mayúsculas y minúsculas. Por ejemplo, state.
- "required": <true|false> indica si el parámetro de consulta especificado por "name":"<query-parameter-name>" debe estar presente en la solicitud para que la solicitud se considere válida.
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>" indica cómo el gateway de API valida las solicitudes en la política de solicitud de validación de parámetros de consulta, de la siguiente forma:
  - ENFORCING: El gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API solo envía solicitudes que pasan la validación al servicio de backend.
  - PERMISSIVE: El gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend, independientemente de si pasan o no la validación.
  - DISABLED: El gateway de API no valida ninguna solicitud con respecto a la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend.
  Por ejemplo, "validationMode": "PERMISSIVE". Tenga en cuenta que ENFORCING se utiliza como modo de validación por defecto si no incluye "validationMode".
Por ejemplo:
```
{
  "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"
        }
      }
    }
  ]
}
```
En este ejemplo, para que la solicitud se considere válida, la solicitud puede incluir opcionalmente el parámetro de consulta state. El gateway de API solo envía solicitudes que pasan la validación al servicio de backend.
Para validar el contenido del cuerpo de una solicitud en el gateway de API para la ruta actual, especifique una política de solicitud de validación 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>"
        }
      }
    }
  ]
}
```
donde:
- "required": true indica que el tipo de contenido del cuerpo de la solicitud debe ser uno de los tipos de contenido que especifique.
- "content": {"<media-type-1>": {"validationType": "NONE"}, "<media-type-2>": {"validationType": "NONE"}} indica uno o más tipos de contenido permitidos para el cuerpo de la solicitud. El cuerpo de la solicitud debe ser uno de los tipos de contenido que especifique. Por ejemplo, application/json, application/xml. Actualmente solo está soportado NONE para "validationType".
- "validationMode": "<ENFORCING|PERMISSIVE|DISABLED>" indica cómo el gateway de API valida las solicitudes en la política de solicitud de validación de cuerpo, de la siguiente forma:
  - ENFORCING: El gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API solo envía solicitudes que pasan la validación al servicio de backend.
  - PERMISSIVE: El gateway de API valida todas las solicitudes en la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend, independientemente de si pasan o no la validación.
  - DISABLED: El gateway de API no valida ninguna solicitud con respecto a la política de solicitud de validación. El gateway de API envía todas las solicitudes al servicio de backend.
  Por ejemplo, "validationMode": "PERMISSIVE". Tenga en cuenta que ENFORCING se utiliza como modo de validación por defecto si no incluye "validationMode".
Por ejemplo:
```
{
  "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"
        }
      }
    }
  ]
}
```
En este ejemplo, para que la solicitud se considere válida, el tipo de contenido del cuerpo de la solicitud debe ser application/json o application/xml. El gateway de API solo envía solicitudes que pasan la validación al servicio de backend.
Guarde el archivo JSON que contiene la especificación de despliegue de API.
Utilice la especificación de despliegue de API al crear o actualizar un despliegue de API de las siguientes formas:
- Especificando el archivo JSON en la consola al seleccionar la opción Cargar API.
- Especificando el archivo JSON en una solicitud para la API REST de gateway de API.
Para obtener más información, consulte Despliegue de una API en un gateway de API mediante la creación de un despliegue de API y Actualización de un gateway de API.
(Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Documentación de Oracle Cloud Infrastructure

Adición de validación de solicitud a despliegues de API

Uso de la consola para agregar políticas de solicitud de validación

Edición de un archivo JSON para agregar políticas de solicitud de validación