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 pasarela. Estas extensiones te permiten especificar ajustes de gestión de APIs, métodos de autenticación, límites de cuota e integraciones de backend directamente en tu documento OpenAPI. Conocer estas extensiones te ayudará a adaptar el comportamiento de tu servicio e integrarlo con las funciones de API Gateway.

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

Aunque los ejemplos se muestran 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 gestión de APIs de nivel superior de 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 Defina métricas para aplicar límites de cuota.
quota map[string]Quota No Vacío Especifica los límites de cuota de tu servicio.
backends map[string]Backend Sí Vacío Configura los servicios de backend.
apiName string No Vacío Asocia un nombre a 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 Nombre visible de la métrica.

Objeto Quota

El objeto Quota define los límites de las cuotas.

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í Hacer referencia a una métrica declarada en este documento de OpenAPI.
values int64 Sí Define el valor máximo que puede alcanzar la métrica antes de que se denieguen las solicitudes del cliente.

Objeto Backend

El objeto Backend configura un servicio de backend. Debes definir 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 una audiencia JWT que coincida con el campo de dirección. Solo es necesario especificar jwt_audience manualmente cuando el backend de destino usa la autenticación basada en JWT y la audiencia esperada es diferente del valor especificado en el campo de dirección. En el caso de los backends remotos desplegados en App Engine o con IAP, debes anular la audiencia del JWT. App Engine e IAP usan su ID de cliente de OAuth como audiencia esperada.
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 Define la estrategia de traducción de la ruta al proxyizar solicitudes al backend de destino. Si x-google-backend se define en el nivel superior y no se especifica ningún path_translation, el valor predeterminado de pathTranslation es APPEND_PATH_TO_ADDRESS. Si x-google-backend está activado a nivel de operación y no se especifica ningún valor para path_translation, el valor predeterminado es CONSTANT_ADDRESS.
deadline double No 15.0 Especifica el número de segundos que se debe esperar para recibir una respuesta completa a una solicitud. Las respuestas que superen este plazo se agotan.
protocol string No http/1.1 Define el protocolo para enviar una solicitud al backend. Los valores posibles son http/1.1 y h2.

x-google-auth

Opcional.

La extensión x-google-auth define los ajustes de autenticación en 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 el emisor 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 para validar la firma del JSON Web Token. API Gateway admite dos formatos de clave pública asimétrica definidos por esta extensión de OpenAPI:

  1. Formato de conjunto 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, asigna al atributo jwksUri el URI de un archivo que contenga la cadena de clave codificada en base64url.
audiences [string] No Vacío Lista de audiencias con las que debe coincidir el campo aud de JWT durante la autenticación JWT.
jwtLocations [JwtLocations] No Vacío Personaliza las ubicaciones del token JWT. De forma predeterminada, un JWT se transmite en el encabezado Authorization (con el prefijo "Bearer "), en el encabezado X-Goog-Iap-Jwt-Assertion o en el parámetro de consulta 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 consulta que contiene el JWT.
valuePrefix string No Vacío Solo para el encabezado. Cuando se define, 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 OpenAPI o en una operación concreta.

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 las métricas definidas en el objeto. En este caso, asigne una métrica (como read-requests) a un importe para incrementarla. Las solicitudes se rechazan cuando el valor de la métrica alcanza el límite de la cuota.

x-google-backend

Obligatorio.

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

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

Campo Tipo Obligatorio Descripción
self string Sí Referencia el 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 la matriz servers de un documento de OpenAPI 3.x. Solo una entrada de servidor de tu documento OpenAPI puede usar la extensión x-google-endpoint.

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

  • CORS: puedes habilitar el uso compartido de recursos entre dominios (CORS) asignando el valor true a la propiedad allowCors.

  • Ruta base: se usa la ruta base definida en el servidor con x-google-endpoint para tu API. Por ejemplo, la siguiente configuración define v1 como ruta 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 CORS.

x-google-parameter

Opcional.

La extensión x-google-parameter se define en un elemento parameter. Se puede usar cuando la ruta usa 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 tener el valor **.

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 funciones de OpenAPI 3.x.

Siguientes pasos