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.

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

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é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 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 overriden)
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-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 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?