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 Configurar servicios de backend
apiName string No Vacío Asocia un nombre con las operaciones definidas en el documento de OpenAPI.
ai AI No Vacío Configurar funciones de inteligencia artificial, incluido el enrutamiento de modelos

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 Backends

Obligatorio.

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

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

Campo Tipo Obligatorio Predeterminado Descripción
address string Sí 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 establece en el 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. El límite máximo del plazo es de 600 segundos.
protocol string No http/1.1 Establece el protocolo para enviar una solicitud al backend. Los valores admitidos incluyen http/1.1 y h2.

Objeto AI

El objeto AI configura las capacidades de inteligencia artificial para tu servicio, como el enrutamiento de modelos.

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

Campo Tipo Obligatorio Predeterminado Descripción
models Models No Vacío Configurar integraciones de modelos de IA

Objeto Models

El objeto Models define configuraciones específicas del modelo.

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

Campo Tipo Obligatorio Predeterminado Descripción
routing Routing No Vacío Configura los parámetros de enrutamiento del modelo.

Objeto Routing

El objeto Routing define las reglas y los enrutadores de enrutamiento del modelo.

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

Campo Tipo Obligatorio Predeterminado Descripción
routers map[string]Router No Vacío Define routers de modelos con nombre.

Objeto Router

El objeto Router define un router de modelos con nombre.

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

Campo Tipo Obligatorio Predeterminado Descripción
defaultModel DefaultModel Sí Vacío Es el destino del modelo de resguardo obligatorio que se usa cuando una solicitud entrante no coincide con ninguna regla explícita.
rules [Rule] No Vacío Es la lista de reglas de enrutamiento explícitas del modelo.

Objeto DefaultModel

El objeto DefaultModel especifica el destino de resguardo.

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

Campo Tipo Obligatorio Predeterminado Descripción
backend string Sí Vacío Hace referencia a un backend declarado en x-google-api-management.backends.
targetModel string Sí Vacío Especifica el identificador del modelo de destino en el formato <provider>/<model-id>. Para las rutas compatibles con OpenAI, este valor se reenvía como el atributo model saliente en el cuerpo de la solicitud cuando se produce una resiliencia.

Objeto Rule

El objeto Rule define una regla de enrutamiento del modelo explícita.

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

Campo Tipo Obligatorio Predeterminado Descripción
model string Sí Vacío Es la cadena entrante que coincide con el atributo model en la carga útil de JSON del cliente. Para las rutas compatibles con OpenAI, esta cadena se reenvía como el atributo model saliente en el cuerpo de la solicitud y debe ser una cadena <provider>/<model-id> válida.
backend string Sí Vacío Hace referencia a un backend declarado en x-google-api-management.backends.
targetModel string Sí Vacío Especifica el identificador del modelo de destino en el formato <provider>/<model-id>. Este valor selecciona la traducción del proveedor y se devuelve en el campo model de la respuesta.

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 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étrico, 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 de 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 se usa en operaciones individuales para especificar qué métricas definidas en x-google-api-management.metrics se ven afectadas por las solicitudes a esa operación.

x-google-quota es un objeto que contiene pares clave-valor, en el que cada clave es un nombre de métrica y el valor es el costo entero de cada solicitud a la operación. Por ejemplo:

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overridden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

x-google-backend

Obligatorio.

La extensión x-google-backend hace referencia a un backend definido en x-google-api-management.backends. Cuando se usa, su valor debe ser una cadena que coincida con el nombre de un backend definido en x-google-api-management.backends. 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 para anular el backend de nivel superior.

Por ejemplo:

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

x-google-model-router

Opcional.

La extensión x-google-model-router hace referencia a un router de modelos definido en x-google-api-management.ai.models.routing.routers. Cuando se usa, su valor debe ser una cadena que coincida con el nombre de un router definido en x-google-api-management.ai.models.routing.routers.

Esta extensión solo se admite en las especificaciones de OpenAPI 3.x y no se puede usar con las especificaciones de OpenAPI 2.0 (Swagger). Solo puedes definir esta extensión a nivel de la operación individual para las operaciones que usan el método HTTP POST. No puedes especificar x-google-model-router y x-google-backend en la misma operación, ni mezclar operaciones de enrutamiento de modelos y de no modelos en diferentes rutas de acceso dentro de la misma especificación de API.

Por ejemplo:

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

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 multiorigen (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 de acceso usa plantillas de ruta de acceso 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?