Extensiones de OpenAPI 3.x en API Gateway

API Gateway acepta un conjunto de extensiones específicas de Google para la especificación de OpenAPI que configuran los comportamientos de la puerta de enlace. Estas extensiones te permiten especificar la configuración de administración de APIs, los métodos de autenticación, los límites de cuota y las integraciones de backend directamente en tu documento de OpenAPI. Comprender estas extensiones te ayuda a adaptar el comportamiento de tu servicio y a integrarlo con las funciones de API Gateway.

En esta página, se describen las extensiones específicas de Google para la especificación de OpenAPI 3.x.

Aunque los ejemplos que se proporcionan a continuación están en formato YAML, también se admite JSON.

x-google-api-management

Obligatorio.

La extensión x-google-api-management define la configuración de administración de la API de nivel superior para tu servicio. Coloca esta extensión en la raíz de tu documento de OpenAPI.

En la siguiente tabla, se describen los campos de x-google-api-management:

Campo Tipo Obligatorio Predeterminado Descripción
metrics map[string]Metric No Vacío Define métricas para aplicar límites de cuota.
quota map[string]Quota No Vacío Especifica los límites de cuota para tu servicio.
backends map[string]Backend Sí Vacío Configura los servicios de backend.
apiName string No Vacío Asocia un nombre con las operaciones definidas en el documento de OpenAPI.

Objeto Metric

El objeto Metric define una métrica que se usa para aplicar la cuota.

En la siguiente tabla, se describen los campos de Metric:

Campo Tipo Obligatorio Predeterminado Descripción
displayName string No Vacío Es el nombre visible de la métrica.

Objeto Quota

El objeto Quota define los límites de cuota.

En la siguiente tabla, se describen los campos de Quota:

Campo Tipo Obligatorio Predeterminado Descripción
limits map[string]QuotaLimit No Vacío Especifica los límites de cuota.

Objeto Quota Limit

El objeto QuotaLimit define un límite de cuota específico.

En la siguiente tabla, se describen los campos de QuotaLimit:

Campo Tipo Obligatorio Descripción
metric string Sí Hace referencia a una métrica declarada en este documento de OpenAPI.
values int64 Sí Establece el valor máximo que puede alcanzar la métrica antes de que se rechacen las solicitudes del cliente.

Objeto Backend

El objeto Backend configura un servicio de backend. Debes configurar jwtAudience o disableAuth.

En la siguiente tabla, se describen los campos de Backend:

Campo Tipo Obligatorio Predeterminado Descripción
address string No Vacío Especifica la URL del backend.
jwtAudience string No Vacío De forma predeterminada, API Gateway creará el token de ID de instancia con un público de JWT que coincida con el campo de dirección. Especificar jwt_audience de forma manual solo es necesario cuando el backend de destino usa la autenticación basada en JWT y el público previsto es diferente del valor especificado en el campo de dirección. Para los backends remotos implementados en App Engine o con IAP, debes anular el público de JWT. App Engine y IAP usan su ID de cliente de OAuth como el público previsto.
disableAuth bool No False Evita que el proxy del plano de datos obtenga un token de ID de instancia y lo adjunte a la solicitud.
pathTranslation string No APPEND_PATH_TO_ADDRESS o CONSTANT_ADDRESS Configura la estrategia de traducción de ruta de acceso cuando se envían solicitudes de proxy al backend de destino. Cuando x-google-backend se establece en el nivel superior y no se especifica ningún path_translation, el valor predeterminado de pathTranslation es APPEND_PATH_TO_ADDRESS. Cuando x-google-backend se configura a nivel de la operación y no se especifica ningún path_translation, el valor predeterminado es CONSTANT_ADDRESS.
deadline double No 15.0 Especifica la cantidad de segundos que se espera una respuesta completa de una solicitud. Las respuestas que excedan este plazo agotarán el tiempo de espera.
protocol string No http/1.1 Establece el protocolo para enviar una solicitud al backend. Los valores admitidos incluyen http/1.1 y h2.

x-google-auth

Opcional.

La extensión x-google-auth define la configuración de autenticación dentro de un objeto Security Scheme.

En la siguiente tabla, se describen los campos de x-google-auth:

Campo Tipo Obligatorio Predeterminado Descripción
issuer string No Vacío Especifica la entidad emisora de una credencial. Los valores pueden ser un nombre de host o una dirección de correo electrónico.
jwksUri string No Vacío

Proporciona el URI del conjunto de claves públicas del proveedor configurado para validar la firma del token web JSON. API Gateway admite dos formatos asimétricos de clave pública definidos por esta extensión de OpenAPI:

  1. Formato fijo de JWK. Por ejemplo: jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json".
  2. X509. Por ejemplo: jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com".

Si usas un formato de clave simétrica, configura jwksUri como el URI de un archivo que contiene la cadena de clave codificada en base64url.
audiences [string] No Vacío Enumera los públicos que deben coincidir con el campo aud del JWT durante la autenticación de JWT.
jwtLocations [JwtLocations] No Vacío Personaliza las ubicaciones del token JWT. De forma predeterminada, un JWT se pasa en el encabezado Authorization (con el prefijo “Bearer”), el encabezado X-Goog-Iap-Jwt-Assertion o el parámetro de búsqueda access_token.

Objeto JwtLocations

El objeto JwtLocations proporciona ubicaciones personalizadas para el token JWT.

En la siguiente tabla, se describen los campos de JwtLocations:

Campo Tipo Obligatorio Predeterminado Descripción
header | query string Sí N/A Especifica el nombre del encabezado que contiene el JWT o el nombre del parámetro de búsqueda que contiene el JWT.
valuePrefix string No Vacío Solo para el encabezado. Cuando se establece, su valor debe coincidir con el prefijo del valor del encabezado que contiene el JWT.

x-google-quota

Opcional.

La extensión x-google-quota define los límites de cuota. Puedes definir esta extensión en el nivel superior de tu documento de OpenAPI o para una operación individual.

En la siguiente tabla, se describen los campos de x-google-quota:

Campo Tipo Obligatorio Descripción
self map[string]int64 Sí El objeto quota (self) hace referencia a cualquier métrica definida dentro del objeto. En este caso, asigna una métrica (como read-requests) a un importe para incrementar la métrica. Las solicitudes se rechazan cuando el valor de la métrica alcanza el límite de cuota.

x-google-backend

Obligatorio.

La extensión x-google-backend hace referencia a un backend definido en x-google-api-management. Debes configurar esta extensión para API Gateway. Puedes definir esta extensión en el nivel superior de tu documento de OpenAPI o para una operación individual.

En la siguiente tabla, se describen los campos de x-google-backend:

Campo Tipo Obligatorio Descripción
self string Sí Hace referencia al ID de un backend definido en x-google-api-management.

x-google-endpoint

Opcional.

La extensión x-google-endpoint se usa para configurar las propiedades de un servidor definido en el array servers de un documento de OpenAPI 3.x. Solo una entrada del servidor en tu documento de OpenAPI puede usar la extensión x-google-endpoint.

La extensión también define otras funciones de backend, incluidas las siguientes:

  • CORS: Puedes habilitar el uso compartido de recursos entre dominios (CORS) configurando la propiedad allowCors en true.

  • Ruta base: Se usa la ruta base establecida en el servidor con x-google-endpoint para tu API. Por ejemplo, la siguiente configuración establece v1 como la ruta de acceso base:

servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

En la siguiente tabla, se describen los campos de x-google-endpoint:

Campo Tipo Obligatorio Predeterminado Descripción
allowCors bool No false Permite solicitudes de CORS.

x-google-parameter

Opcional.

La extensión x-google-parameter se define en un elemento parameter. Se puede usar cuando la ruta utiliza plantillas de ruta para especificar que se debe usar el comportamiento de coincidencia de comodín doble.

En la siguiente tabla, se describen los campos de x-google-parameter:

Campo Tipo Obligatorio Descripción
pattern string Sí Debe establecerse en **.

Información sobre las limitaciones de las extensiones de OpenAPI

Estas extensiones de OpenAPI tienen limitaciones específicas. Para obtener más información, consulta Limitaciones de las características de OpenAPI 3.x.

¿Qué sigue?