Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

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 gestión de API, 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 en 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 proporcionados 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 gestión de 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	Asociar un nombre con las operaciones definidas en el documento de OpenAPI
`ai`	`AI`	No	Vacío	Configura las funciones de inteligencia artificial, incluido el enrutamiento a modelos.
`mcp`	`MCP` o `bool`	No	Vacío	Habilitar o configurar las funciones del Protocolo de contexto del modelo (MCP)

Objeto `Metric`

El objeto Metric define una métrica que se usa para la aplicación de 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 `QuotaLimit`

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í	Haz 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 de los clientes.

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. Solo se requiere especificar `jwt_audience` de forma manual cuando el backend de destino usa la autenticación basada en JWT y el público esperado 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 del 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`	Establece la estrategia de traducción de rutas de acceso cuando se envían solicitudes de proxy al backend de destino. Cuando se establece `x-google-backend` en el nivel superior y no se especifica `path_translation`, el valor predeterminado de `pathTranslation` es `APPEND_PATH_TO_ADDRESS`. Cuando se configura `x-google-backend` a nivel de la operación y no se especifica `path_translation`, el valor predeterminado es `CONSTANT_ADDRESS`.
`deadline`	`double`	No	`15.0`	Especifica la cantidad de segundos que se debe esperar para obtener una respuesta completa de una solicitud. Las respuestas que exceden este plazo agotan el tiempo de espera. En un extremo de SSE o de transferencia fragmentada, el plazo sigue limitando la duración de todo el flujo; en un extremo de gRPC o WebSocket, limita el intervalo entre mensajes. Consulta Establece el plazo de transmisión para conocer los tiempos de espera que se aplican a cada tipo de solicitud. Omite el campo o establécelo en `0` para usar el valor predeterminado. Se rechaza un valor negativo. La fecha límite se puede configurar hasta 3,600 segundos. Una puerta de enlace que no es de transmisión aplica un máximo inferior de 600 segundos, lo que rechaza un plazo más alto en la creación o actualización de la puerta de enlace, en lugar de en la creación de la configuración de la API.
`protocol`	`string`	No	`http/1.1`	Establece el protocolo para enviar una solicitud al backend. Los valores admitidos incluyen `http/1.1` y `h2`. Los requisitos del protocolo dependen del tipo de transmisión: - gRPC: Debes establecer el protocolo en `h2`. - WebSockets: Debes usar `http/1.1`. - Eventos enviados por el servidor (SSE) y entrega de respuestas incremental: Puedes usar `http/1.1` o `h2`. Te recomendamos `h2` para mejorar el rendimiento.

Objeto `AI`

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

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

Campo	Tipo	Obligatorio	Predeterminado	Descripción
`models`	`Models`	No	Vacío	Configura las integraciones de modelos de IA.

Objeto `Models`

El objeto Models define las 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	Establece la configuración de enrutamiento a modelos.

Objeto `Routing`

El objeto Routing define las reglas de enrutamiento a modelos y los routers.

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

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

Objeto `Router`

El objeto Router define un enrutador 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 explícitas de enrutamiento a modelos.

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	Haz referencia a un backend declarado en `x-google-api-management.backends`.
`targetModel`	`string`	Sí	Vacío	Especifica el identificador del modelo de destino con el formato `<provider>/<model-id>`. En el caso de las rutas compatibles con OpenAI, este valor se reenvía como el atributo `model` saliente en el cuerpo de la solicitud cuando se produce el resguardo.

Objeto `Rule`

El objeto Rule define una regla de enrutamiento a modelos explícita.

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

Campo	Tipo	Obligatorio	Predeterminado	Descripción
`model`	`string`	Sí	Vacío	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	Haz referencia a un backend declarado en `x-google-api-management.backends`.
`targetModel`	`string`	Sí	Vacío	Especifica el identificador del modelo de destino con el formato `<provider>/<model-id>`. Este valor selecciona la traducción del proveedor y se repite en el campo `model` de la respuesta.

Objeto `MCP`

El objeto MCP configura las funciones del Protocolo de contexto del modelo (MCP) para tu servicio. Puedes establecer mcp en un valor booleano o un objeto. Establécelo en true para habilitar MCP de forma global en todas las operaciones aptas con la configuración predeterminada.

En la siguiente tabla, se describen los campos del objeto MCP:

Campo	Tipo	Obligatorio	Predeterminado	Descripción
`tools-list`	`ToolsList`	No	Vacío	Establece la configuración del método `tools/list` de MCP.

Objeto `ToolsList`

El objeto ToolsList establece la configuración del método tools/list de MCP.

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

Campo	Tipo	Obligatorio	Predeterminado	Descripción
`security`	`map`	No	Vacío	Habilita la autenticación en `tools/list`. Como práctica recomendada de seguridad, se recomienda configurar esta opción. Debe nombrar exactamente un esquema de seguridad de JWT o clave de API definido en `components.securitySchemes`.

`x-google-auth`

Opcional.

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

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 de clave pública asimétrica definidos por esta extensión de OpenAPI: Formato fijo de JWK. Por ejemplo: `jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"`. 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, establece el `jwksUri` en el URI de un archivo que contenga la cadena de clave codificada en base64url.
`audiences`	`[string]`	No	Vacío	Enumera los públicos con los que debe coincidir 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 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 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 los 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 con el objetivo de 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 enrutador 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; no se puede usar con las especificaciones de OpenAPI 2.0 (Swagger). Solo puedes definir esta extensión a nivel de 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 a modelos y de enrutamiento que no sea a modelos en diferentes rutas de acceso dentro de la misma especificación de la API. Además, no puedes usar el enrutamiento a modelos junto con el Protocolo de contexto del modelo (MCP). Si habilitas x-google-api-management.mcp, esta extensión no estará disponible.

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-mcp-tool`

Opcional.

La extensión x-google-mcp-tool se usa en operaciones individuales para exponerlas como herramientas de MCP y, de forma opcional, anular el nombre y la descripción de la herramienta generada.

Acepta un valor booleano o un objeto.

Formato booleano: Se establece en true para habilitar esta operación. Establece el valor en false para inhabilitarlo, lo que anula la habilitación global.
Formulario de objeto: Habilita y anula la configuración de la herramienta generada.

En la siguiente tabla, se describen los campos de x-google-mcp-tool cuando se usa como un objeto:

Campo	Tipo	Obligatorio	Predeterminado	Descripción
`name`	`string`	No	El `operationId` de la operación	Es el nombre de la herramienta de MCP. Debe coincidir con `[A-Za-z0-9_.-]{1,128}` y ser único en toda la especificación.
`description`	`string`	No	La descripción de la operación, que recurre al resumen	La descripción de la herramienta de MCP. Esta es la señal principal que usa un LLM para seleccionar herramientas.

Por ejemplo:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

`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 de 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 de origen cruzado (CORS) si configuras la propiedad allowCors como true.
Ruta de acceso base: La ruta de acceso base establecida en el servidor con x-google-endpoint se usa 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`	Permitir solicitudes de CORS

`x-google-parameter`

Opcional.

La extensión x-google-parameter se define en un elemento parameter. Esto 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 `**`.

Comprende 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.

¿Qué sigue?

Explora la especificación de OpenAPI.
Modifica una puerta de enlace para usar OpenAPI 3.0.

Extensiones de OpenAPI 3.x en API Gateway

x-google-api-management

Objeto Metric

Objeto Quota

Objeto QuotaLimit

Objeto Backends

Objeto AI

Objeto Models

Objeto Routing

Objeto Router

Objeto DefaultModel

Objeto Rule

Objeto MCP

Objeto ToolsList

x-google-auth

Objeto JwtLocations

x-google-quota

x-google-backend

x-google-model-router

x-google-mcp-tool

x-google-endpoint

x-google-parameter

Comprende las limitaciones de las extensiones de OpenAPI

¿Qué sigue?

`x-google-api-management`

Objeto `Metric`

Objeto `Quota`

Objeto `QuotaLimit`

Objeto `Backends`

Objeto `AI`

Objeto `Models`

Objeto `Routing`

Objeto `Router`

Objeto `DefaultModel`

Objeto `Rule`

Objeto `MCP`

Objeto `ToolsList`

`x-google-auth`

Objeto `JwtLocations`

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-mcp-tool`

`x-google-endpoint`

`x-google-parameter`