Agregación de políticas de solicitud y políticas de respuesta a especificaciones de despliegue de API

Descubra cómo controlar el comportamiento de los despliegues de API agregando políticas de solicitud y respuesta a las especificaciones de API que ha creado anteriormente con API Gateway.

Puede controlar el comportamiento de un despliegue de API que cree en un gateway de API, agregando políticas de solicitud y respuesta a la especificación de despliegue de API:

una política de solicitud que describe las acciones que se deben llevar a cabo en una solicitud entrante de un cliente de API antes de que se envíe a un backend
una política de respuesta que describe las acciones que se deben llevar a cabo en una respuesta devuelta desde un backend antes de enviarla a un cliente de API

Puede utilizar políticas de solicitud y/o políticas de respuesta para:

Limitar el número de solicitudes enviadas a servicios de backend.
Activar el soporte de uso compartido de recursos de origen cruzado (CORS).
Proporcionar autenticación y autorización.
agregar soporte de mTLS
validar solicitudes antes de enviarlas a servicios de backend
modificar solicitudes entrantes y respuestas salientes
Respuestas de caché para mejorar el rendimiento y reducir la carga en los servicios de backend
Hacer que los despliegues de API sean elegibles para su inclusión en planes de uso que supervisan y gestionan el acceso de suscriptores

Puede agregar políticas a una especificación de despliegue de API que se aplican de forma global a todas las rutas de dicha especificación, así como políticas que se aplican solo a rutas concretas.

Tenga en cuenta que las políticas de solicitud y las políticas de respuesta de gateway de API son diferentes de las políticas de IAM, que controlan el acceso a los recursos de Oracle Cloud Infrastructure.

Puede agregar políticas de solicitud y respuesta 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 y políticas de respuesta

Para agregar políticas de solicitud y políticas de respuesta 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.
En la sección Políticas de solicitud de API de la página Información básica, especifique las políticas de solicitud que se aplican de forma global a todas las rutas de la especificación de despliegue de API:
- Mutual-TLS: política para controlar el acceso a las API que despliega en gateways de API según el certificado TLS presentado por el cliente de API que realiza una solicitud. Solo puede aplicar una política de mTLS globalmente a todas las rutas de la especificación de despliegue de API (no a rutas individuales). Consulte Adición de soporte de mTLS a despliegues de API.
- CORS: política para activar el soporte de CORS en las API que despliegue en gateways de API. También puede especificar políticas de CORS que se aplican a rutas individuales en la especificación de despliegue de API (no es necesario que haya introducido antes una política de CORS global). Consulte Agregación de soporte de CORS a despliegues de API.
- Limitación de frecuencia: política para limitar la frecuencia con la que los clientes de API pueden realizar solicitudes a servicios de backend. Solo puede aplicar una política de limitación de ratio globalmente a todas las rutas de la especificación de despliegue de API (no a rutas individuales). Consulte Limitación del número de solicitudes para backends de gateway de API.
Seleccione Siguiente para especificar opciones para definir una política de solicitud de autenticación global en la página Autenticación.

La política de solicitud de autenticación controla el acceso a las API que despliega en gateways de API. Tras especificar una política de autenticación global, puede especificar las políticas de autorización que se aplican a rutas individuales en la especificación de despliegue de API. Consulte Agregación de autenticación y autorización a despliegues de API.
Seleccione Siguiente para introducir detalles de rutas individuales en el despliegue de API en la página Rutas.
Para especificar políticas de solicitud que se aplican a una ruta individual, seleccione Mostrar políticas de solicitud de ruta y especifique:
- Autorización: política para especificar las operaciones que un usuario final puede realizar en función de sus ámbitos de acceso. Tenga en cuenta que debe haber especificado una política de autenticación global para poder especificar una política de autorización en una ruta individual. Consulte Agregación de autenticación y autorización a despliegues de API.
- CORS: política para activar el soporte de CORS para rutas individuales en la especificación de despliegue de API (no es necesario que haya introducido primero una política CORS global). Consulte Agregación de soporte de CORS a despliegues de API.
- Validaciones de cabecera: política para validar cabeceras en solicitudes. Consulte Using the Console to Add Validation Request Policies.
- Validaciones de parámetros de consulta: política para validar parámetros de consulta en solicitudes. Consulte Using the Console to Add Validation Request Policies.
- Validación de cuerpo: política para validar el contenido en el cuerpo de las solicitudes. Consulte Using the Console to Add Validation Request Policies.
- Transformaciones de cabecera: política para agregar, eliminar y modificar cabeceras en solicitudes. Consulte Uso de la consola para agregar políticas de solicitudes de transformación de cabecera.
- Transformaciones de consulta: política para agregar, eliminar y modificar parámetros de consulta en solicitudes. Consulte Uso de la consola para agregar políticas de solicitudes de transformación de parámetros de consulta.
Para especificar políticas de respuesta que se aplican a una ruta individual, seleccione Mostrar políticas de respuesta de ruta y especifique:
- Transformaciones de cabeceras: política para agregar, eliminar y modificar cabeceras en respuestas. Consulte Uso de la consola para agregar políticas de respuesta de transformación de cabecera.
Seleccione Siguiente para revisar los detalles introducidos para el despliegue de API.
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 y políticas de respuesta

Para agregar políticas de solicitud y políticas de respuesta 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 una política de solicitud o una política de respuesta, o cree una nueva especificación de despliegue de API (consulte Creación de una especificación de despliegue de API).

Como mínimo, la especificación de despliegue de API incluirá una sección routes que contiene:
- Una ruta de acceso. Por ejemplo, /hello.
- Uno o varios métodos. Por ejemplo, GET
- Una definición de backend. Por ejemplo, una URL o el OCID de una función en OCI Functions.
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": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
Para agregar una política de solicitud que se aplique de forma global a todas las rutas de la especificación de despliegue de API:
1. Inserte una sección requestPolicies antes de la sección routes. Por ejemplo:
```
{
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
2. Incluya una política de solicitud en la sección requestPolicies.
  
  Por ejemplo, para limitar el número de solicitudes enviadas a todas las rutas de una especificación de despliegue de API, debe incluir la política rateLimiting en la sección requestPolicies de la siguiente manera:
```
{
  "requestPolicies": {
    "rateLimiting": {
      "rateKey": "CLIENT_IP",
      "rateInRequestsPerSecond": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
  Para obtener más información sobre la política de solicitud rateLimiting, consulte Limitación del número de solicitudes para backends de gateway de API.

Para agregar una política de solicitud que se aplique a una ruta individual en la especificación de despliegue de la API:

Inserte una sección requestPolicies después de la sección backend de la ruta. Por ejemplo:

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

Incluya una política de solicitud en la sección requestPolicies.

Por ejemplo, para activar el soporte de CORS en un despliegue de API para una ruta concreta, debe incluir la política cors en la sección requestPolicies de la siguiente forma:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "cors":{
           "allowedOrigins": ["*", "https://oracle.com"],
           "allowedMethods": ["*", "GET"],
           "allowedHeaders": [],
           "exposedHeaders": [],
           "isAllowCredentialsEnabled": false,
           "maxAgeInSeconds": 3000
        }
      }
    }
  ]
}

Para obtener más información sobre la política de solicitud cors, consulte Agregación de soporte de CORS a despliegues de API.

Para agregar una política de respuesta que se aplique a una ruta individual en la especificación de despliegue de la API:

Inserte una sección responsePolicies después de la sección backend de la ruta. Por ejemplo:

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

Incluya una política de respuesta en la sección responsePolicies.

Por ejemplo, para cambiar el nombre de cualquier cabecera X-Username a X-User-ID en la respuesta de una ruta concreta, se debería incluir la política headerTransformations en la sección responsePolicies de la siguiente manera:

{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {
        "headerTransformations": {
          "renameHeaders": {
            "items": [
              {
                "from": "X-Username",
                "to": "X-User-ID"
              }
            ]
          }
        }
      }
    }
  ]
}

Para obtener más información sobre la política de respuesta headerTransformations, consulte Edición de un archivo JSON para agregar políticas de respuesta de transformación de cabecera.

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.

Documentación de Oracle Cloud Infrastructure

Agregación de políticas de solicitud y políticas de respuesta a especificaciones de despliegue de API

Uso de la consola para agregar políticas de solicitud y políticas de respuesta

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