Extensiones de OpenAPI 3.x

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

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 No Vacío Configura los servicios de backend.
apiName string No Vacío Asocia un nombre con las operaciones definidas en el documento de OpenAPI.
allowCors bool No False Pasa todas las solicitudes de CORS (OPTIONS) al backend.

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, Endpoints 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, el valor predeterminado de pathTranslation es APPEND_PATH_TO_ADDRESS. Cuando se establece x-google-backend en una operación, 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 para validar la firma del token web JSON.
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 Endpoints. 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

Obligatorio.

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
target string No Especifica la dirección IP a la que se resuelve el host.
allowCors bool No false Permite solicitudes de CORS.

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?

  • Explora la especificación de OpenAPI.
  • Revisa la documentación de Endpoints para conocer las configuraciones específicas de Endpoints o ESPv2.