Extensiones de OpenAPI 2.0 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. En esta página se describen las extensiones personalizadas específicas de Google de la especificación de OpenAPI 2.0 que se usan para configurar los comportamientos de API Gateway, como el enrutamiento de backend, la autenticación y las funciones de gestión de APIs.

Aunque los ejemplos se muestran en formato YAML, también se admite JSON.

Convención de nomenclatura

Las extensiones de Google OpenAPI tienen nombres que empiezan por el prefijo x-google-.

x-google-allow

x-google-allow: [configured | all]

Esta extensión se usa en el nivel superior de una especificación de OpenAPI para indicar qué rutas de URL se deben permitir a través de API Gateway.

Los valores posibles son configured y all.

El valor predeterminado es configured, lo que significa que solo se sirven a través de API Gateway los métodos de API que hayas incluido en tu especificación de OpenAPI.

Cuando se usa all, las llamadas sin configurar (con o sin clave de API o autenticación de usuario) pasan por API Gateway a tu API.

API Gateway procesa las llamadas a tu API de forma que distingue entre mayúsculas y minúsculas. Por ejemplo, API Gateway considera que /widgets y /Widgets son métodos de API diferentes.

Cuando se usa all, debes tener especial cuidado en dos aspectos:

  • Cualquier clave de API o regla de autenticación.
  • La ruta de backend de tu servicio.

Te recomendamos que configures tu API para que use el enrutamiento de rutas que distingue entre mayúsculas y minúsculas. Si usas el enrutamiento que distingue entre mayúsculas y minúsculas, tu API devuelve el código de estado HTTP 404 cuando el método solicitado en la URL no coincide con el nombre del método de la API que figura en tu especificación de OpenAPI. Ten en cuenta que los frameworks de aplicaciones web, como Node.js Express, tienen un ajuste para habilitar o inhabilitar el enrutamiento que distingue entre mayúsculas y minúsculas. El comportamiento predeterminado depende del framework que estés usando. Te recomendamos que revises los ajustes de tu framework para asegurarte de que el enrutamiento que distingue entre mayúsculas y minúsculas esté habilitado. Esta recomendación coincide con la especificación OpenAPI v2.0, que indica que todos los nombres de campo de la especificación distinguen entre mayúsculas y minúsculas.

Ejemplo

Supongamos que:

  • La opción x-google-allow está configurada como all.
  • El método de la API widgets se incluye en tu especificación de OpenAPI, pero no en Widgets.
  • Has configurado tu especificación de OpenAPI para que requiera una clave de API.

Como widgets figura en tu especificación de OpenAPI, API Gateway bloquea la siguiente solicitud porque no tiene una clave de API:

https://my-project-id.appspot.com/widgets

Como Widgets no aparece en tu especificación de OpenAPI, API Gateway envía la siguiente solicitud a tu servicio sin una clave de API:

https://my-project-id.appspot.com/Widgets/

Si tu API usa enrutamiento sensible a mayúsculas y minúsculas (y no has enrutado llamadas a "Widgets" a ningún código), el backend de la API devuelve un 404. Sin embargo, si usas el enrutamiento que no distingue entre mayúsculas y minúsculas, tu backend de la API enruta esta llamada a "widgets".

Los diferentes lenguajes y frameworks tienen métodos distintos para controlar las mayúsculas y minúsculas, así como el enrutamiento. Consulta la documentación de tu framework para obtener más información.

x-google-backend

La extensión x-google-backend especifica cómo enrutar las solicitudes a backends remotos. La extensión se puede especificar en el nivel superior, en el nivel de operación o en ambos niveles de una especificación de OpenAPI.

La extensión x-google-backend también puede configurar otros ajustes para back-ends remotos, como la autenticación y los tiempos de espera. Todas estas configuraciones se pueden aplicar por operación.

La extensión x-google-backend contiene los siguientes campos:

address

address: URL

Obligatorio. URL del backend de destino. El esquema de la dirección debe ser http o https.

Cuando se enrutan solicitudes a back-ends remotos (sin servidor), se debe definir la dirección y la parte del esquema debe ser https.

jwt_audience | disable_auth

Solo se debe definir una de estas dos propiedades.

Si una operación usa x-google-backend, pero no especifica jwt_audience ni disable_auth, API Gateway asignará automáticamente el valor predeterminado de jwt_audience para que coincida con address. Si no se define address, API Gateway asignará automáticamente el valor true a disable_auth.

jwt_audience

jwt_audience: string

Opcional. La audiencia del JWT especificada cuando API Gateway obtiene un token de ID de instancia, que se usa al hacer la solicitud al backend de destino.

Al configurar API Gateway para Serverless, el backend remoto debe protegerse para que solo permita el tráfico de API Gateway. API Gateway adjuntará un token de ID de instancia al encabezado Authorization al proxyizar las solicitudes. El token de ID de instancia representa la cuenta de servicio de tiempo de ejecución que se ha usado para implementar API Gateway. El backend remoto puede verificar que la solicitud procede de API Gateway basándose en este token adjunto.

Por ejemplo, un backend remoto implementado en Cloud Run puede usar Gestión de Identidades y Accesos (IAM) para lo siguiente:

  1. Restringe las invocaciones no autenticadas revocando roles/run.invoker de la entidad principal especial allUsers.
  2. Permite que solo API Gateway invoque el backend. Para ello, concede el rol roles/run.invoker a la cuenta de servicio de tiempo de ejecución de API Gateway.

De forma predeterminada, API Gateway creará el token de ID de instancia con una audiencia JWT que coincida con el campo address. Solo es necesario especificar manualmente jwt_audience cuando el backend de destino usa la autenticación basada en JWT y la audiencia esperada es diferente del valor especificado en el campo address. En el caso de los back-ends remotos desplegados en App Engine o con Identity-Aware Proxy (IAP), debes anular la audiencia del JWT. App Engine e IAP usan su ID de cliente de OAuth como audiencia esperada.

Si esta función está habilitada, API Gateway modificará los encabezados de las solicitudes. Si una solicitud ya tiene definido el encabezado Authorization, API Gateway hará lo siguiente:

  1. Copia el valor original en un encabezado nuevo X-Forwarded-Authorization.
  2. Sustituye el encabezado Authorization por el token de ID de instancia.

Por lo tanto, si un cliente de API define el encabezado Authorization, un backend que se ejecute detrás de API Gateway debe usar el encabezado X-Forwarded-Authorization para obtener todo el JWT. El backend debe verificar el JWT de este encabezado, ya que API Gateway no realizará la verificación si no se configuran métodos de autenticación.

Para ver ejemplos de configuración, consulta Crear una configuración de API.

disable_auth

disable_auth: bool

Opcional. Esta propiedad determina si API Gateway debe impedir que se obtenga un token de ID de instancia y que se adjunte a la solicitud.

Al configurar el backend de destino, puede que no quieras usar IAP o IAM para autenticar las solicitudes de API Gateway si se da alguna de estas condiciones:

  1. El backend debe permitir las invocaciones sin autenticar.
  2. El backend requiere el encabezado Authorization original del cliente de la API y no puede usar X-Forwarded-Authorization (descrito en la sección jwt_audience).

En este caso, asigna el valor true a este campo.

path_translation

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Opcional. Define la estrategia de traducción de rutas que usa API Gateway al enviar solicitudes proxy al backend de destino.

Para obtener más información sobre la traducción de rutas, consulta la sección Información sobre la traducción de rutas.

Cuando se usa x-google-backend en el nivel superior de la especificación de OpenAPI, path_translation tiene el valor predeterminado APPEND_PATH_TO_ADDRESS. Cuando se usa x-google-backend en el nivel de operación de la especificación de OpenAPI, path_translation tiene el valor predeterminado CONSTANT_ADDRESS. Si falta el campo address, path_translation no se especificará y no se producirá.

deadline

deadline: double

Opcional. Número de segundos que se debe esperar para recibir una respuesta completa a una solicitud. Las respuestas que tarden más del plazo configurado se agotarán. El plazo predeterminado es de 15.0 segundos.

No se tendrán en cuenta los valores no positivos. API Gateway usará automáticamente el valor predeterminado en estos casos.

La fecha límite no se puede inhabilitar, pero se puede definir con un número alto, por ejemplo, 600 segundos (la fecha límite máxima).

protocol

protocol: [ http/1.1 | h2 ]

Opcional. El protocolo que se usa para enviar una solicitud al backend. Los valores posibles son http/1.1 y h2.

El valor predeterminado es http/1.1 para los back-ends HTTP y HTTPS.

En el caso de los back-ends HTTP seguros (https://) que admitan HTTP/2, defina este campo como h2 para mejorar el rendimiento. Esta es la opción recomendada para los backends sin servidor de Google Cloud .

Información sobre la traducción de rutas

Como API Gateway gestiona las solicitudes, tomará la ruta de solicitud original y la traducirá antes de enviar una solicitud al backend de destino. La forma exacta en que se produce esta traducción depende de la estrategia de traducción de rutas que utilices. Hay dos estrategias de traducción de rutas:

  • APPEND_PATH_TO_ADDRESS: la ruta de solicitud del backend de destino se calcula añadiendo la ruta de solicitud original a la URL address de la extensión x-google-backend.
  • CONSTANT_ADDRESS: la ruta de la solicitud de destino es constante, tal como se define en la URL address de la extensión x-google-backend. Si la ruta de OpenAPI correspondiente contiene parámetros, el nombre del parámetro y su valor se convierten en parámetros de consulta.

Ejemplos:

  • APPEND_PATH_TO_ADDRESS
    • address: https://my-project-id.appspot.com/BASE_PATH
    • Con parámetros de ruta de OpenAPI
      • Ruta de OpenAPI: /hello/{name}
      • Ruta de la solicitud: /hello/world
      • URL de solicitud de destino: https://my-project-id.appspot.com/BASE_PATH/hello/world
    • Sin parámetros de ruta de OpenAPI
      • Ruta de OpenAPI: /hello
      • Ruta de la solicitud: /hello
      • URL de solicitud de destino: https://my-project-id.appspot.com/BASE_PATH/hello
  • CONSTANT_ADDRESS
    • address: https://us-central1-my-project-id.cloudfunctions.net/helloGET
    • Con parámetros de ruta de OpenAPI
      • Ruta de OpenAPI: /hello/{name}
      • Ruta de la solicitud: /hello/world
      • URL de solicitud de destino: https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
    • Sin parámetros de ruta de OpenAPI
      • Ruta de OpenAPI: /hello
      • Ruta de la solicitud: /hello
      • URL de solicitud de destino: https://us-central1-my-project-id.cloudfunctions.net/helloGET

x-google-endpoints

En esta sección se describen los usos de la extensión x-google-endpoints.

Configurar API Gateway para permitir solicitudes CORS

Si se llama a tu API desde una aplicación web en un origen diferente, tu API debe admitir el uso compartido de recursos entre dominios (CORS). Consulta Añadir compatibilidad con CORS a API Gateway para obtener información sobre cómo configurar API Gateway para que sea compatible con CORS.

Si necesitas implementar la compatibilidad con CORS personalizada en el código de backend, define allowCors: True para que API Gateway transfiera todas las solicitudes CORS al código de backend:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  allowCors: True

Añade la extensión x-google-endpoints en el nivel superior de tu documento OpenAPI (sin sangría ni anidación). Por ejemplo:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

x-google-issuer

x-google-issuer: URI | EMAIL_ADDRESS

Esta extensión se usa en la sección securityDefinitions de OpenAPI para especificar la entidad emisora de una credencial. Los valores pueden ser un nombre de host o una dirección de correo electrónico.

x-google-jwks_uri

x-google-jwks_uri: URI

URI del conjunto de claves públicas del proveedor para validar la firma del token web JSON.

El campo x-google-jwks_uri (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) es obligatorio. API Gateway admite dos formatos de clave pública asimétrica definidos por esta extensión de OpenAPI:

  • Formato de conjunto de JWK. Por ejemplo:

    OpenAPI 2.0

    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

    OpenAPI 3.x

    jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Por ejemplo:

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    OpenAPI 3.x

    jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Si usas un formato de clave simétrica, asigna al parámetro x-google-jwks_uri (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) el URI de un archivo que contenga la cadena de clave codificada en base64url.

x-google-jwt-locations

De forma predeterminada, se envía un JWT 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.

También puede usar la extensión x-google-jwt-locations en la sección securityDefinitions de OpenAPI para proporcionar las ubicaciones personalizadas desde las que extraer el token JWT.

La extensión x-google-jwt-locations acepta una lista de ubicaciones de JWT. Cada ubicación de JWT contiene los siguientes campos:

Elemento Descripción
header/query Obligatorio. Nombre del encabezado que contiene el JWT o nombre del parámetro de consulta que contiene el JWT.
value_prefix Opcional. Solo para el encabezado. Cuando se define value_prefix, su valor debe coincidir con el prefijo del valor del encabezado que contiene el JWT.

Por ejemplo:

x-google-jwt-locations:
  # Expect header "Authorization": "MyBearerToken <TOKEN>"
  - header: "Authorization"
    value_prefix: "MyBearerToken "
  # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
  - header: "jwt-header-foo"
    value_prefix: "jwt-prefix-foo"
  # expect header "jwt-header-bar": "<TOKEN>"
  - header: "jwt-header-bar"
  # expect query parameter "jwt_query_bar=<TOKEN>"
  - query: "jwt_query_bar"

Si solo quieres admitir un subconjunto de las ubicaciones predeterminadas de JWT, inclúyelas explícitamente en la extensión x-google-jwt-locations. Por ejemplo, para incluir solo la compatibilidad con el encabezado Authorization con el prefijo "Bearer ", haz lo siguiente:

  x-google-jwt-locations:
    # Support the default header "Authorization": "Bearer <TOKEN>"
    - header: "Authorization"
      value_prefix: "Bearer "

x-google-audiences

x-google-audiences: STRING

Esta extensión se usa en la sección securityDefinitions de OpenAPI para proporcionar una lista de audiencias con las que debe coincidir el campo aud de JWT durante la autenticación con JWT. Esta extensión acepta una sola cadena con valores separados por comas. No se pueden incluir espacios entre las audiencias. Si no se especifica, el campo aud de JWT debe coincidir con el campo host del documento de OpenAPI.

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

x-google-management

La extensión x-google-management controla diferentes aspectos de la gestión de APIs y contiene los campos que se describen en esta sección.

metrics

metrics se usa junto con cuota y x-google-quota para configurar una cuota para tu API. Las cuotas te permiten controlar la frecuencia con la que las aplicaciones pueden llamar a los métodos de tu API. Por ejemplo:

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

El campo metrics contiene una lista con los siguientes pares clave-valor:

Elemento Descripción
name Obligatorio. Nombre de la métrica. Normalmente, se trata del tipo de solicitud (por ejemplo, "read-requests" o "write-requests") que identifica de forma única la métrica.
displayName

Opcional, pero recomendable. El texto que se muestra para identificar la métrica en la pestaña Cuotas de la página Endpoints > Services (Servicios) de la consola deGoogle Cloud . Este texto también se muestra a los consumidores de tu API en las páginas Cuotas de IAM y administración y APIs y servicios. El nombre visible debe tener un máximo de 40 caracteres.

Para que sea más fácil de leer, la unidad del límite de cuota asociado se añade automáticamente al nombre visible en laGoogle Cloud consola. Por ejemplo, si especifica "Solicitudes de lectura" en el nombre visible, se mostrará "Solicitudes de lectura por minuto y proyecto" en la consolaGoogle Cloud . Si no se especifica, se muestra "cuota sin etiqueta" a los consumidores de tu API en las páginas Cuotas de IAM y administración y APIs y servicios.

Para mantener la coherencia con los nombres visibles de los servicios de Google que se muestran en la página Cuotas que ven los consumidores de tu API, te recomendamos que uses el siguiente nombre visible:

  • Usa "Solicitudes" cuando solo tengas una métrica.
  • Si tienes varias métricas, cada una de ellas debe describir el tipo de solicitud y contener la palabra "solicitudes" (por ejemplo, "Solicitudes de lectura" o "Solicitudes de escritura").
  • Usa "unidades de cuota" en lugar de "solicitudes" cuando alguno de los costes asociados a la métrica sea superior a 1.
valueType Obligatorio. Debe ser INT64
metricKind Obligatorio. Debe ser DELTA

quota

En la sección quota, puede especificar el límite de cuota de una métrica definida. Por ejemplo:

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

El campo quota.limits contiene una lista con los siguientes pares clave-valor:

Elemento Descripción
name Obligatorio. Nombre del límite, que debe ser único en el servicio. El nombre puede contener letras mayúsculas y minúsculas, números y el carácter `-` (guion), y debe tener una longitud máxima de 64 caracteres.
métrica Obligatorio. Nombre de la métrica a la que se aplica este límite. Este nombre debe coincidir con el texto especificado en el nombre de una métrica. Si el texto especificado no coincide con el nombre de una métrica, se producirá un error al implementar el documento de OpenAPI.
unidad Obligatorio. Unidad del límite. Solo se admite "1/min/{project}", lo que significa que el límite se aplica por proyecto y el uso se restablece cada minuto.
valores Obligatorio. El límite de la métrica. Debes especificarlo como un par clave:valor con el siguiente formato: 
STANDARD: YOUR-LIMIT-FOR-THE-METRIC
Sustituye YOUR-LIMIT-FOR-THE-METRIC por un valor entero que sea el número máximo de solicitudes permitidas para la unidad especificada (que solo puede ser por minuto y por proyecto). Por ejemplo:
values:
  STANDARD: 5000

x-google-quota

La extensión x-google-quota se usa en la sección OpenAPI paths para asociar un método de tu API con una métrica. Los métodos que no tienen definido x-google-quota no tienen límites de cuota aplicados. Por ejemplo:

x-google-quota:
  metricCosts:
    read-requests: 1

La extensión x-google-quota contiene el siguiente elemento:

Elemento Descripción
metricCosts Un par clave-valor definido por el usuario: "YOUR-METRIC-NAME": METRIC-COST.
  • "YOUR-METRIC-NAME": El texto de "YOUR-METRIC-NAME" debe coincidir con un nombre de métrica definido.
  • METRIC-COST: Valor entero que define el coste de cada solicitud. Cuando se hace una solicitud, la métrica asociada se incrementa en el coste especificado. El coste permite que los métodos consuman a ritmos diferentes de la misma métrica. Por ejemplo, si una métrica tiene un límite de cuota de 1000 y un coste de 1, la aplicación que llama puede hacer 1000 solicitudes por minuto antes de superar el límite. Con un coste de 2 para la misma métrica, una aplicación que llama solo puede hacer 500 solicitudes por minuto antes de superar el límite.

Ejemplos de cuotas

En el siguiente ejemplo se muestra cómo añadir una métrica y un límite para las solicitudes de lectura y escritura.

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          read-requests: 1
      security:
      - api_key: []

x-google-api-name

Si tu servicio solo contiene una API, el nombre de la API es el mismo que el nombre del servicio de API Gateway. (API Gateway usa el nombre que especifiques en el campo host de tu documento de OpenAPI como nombre de tu servicio). Si tu servicio contiene más de una API, debes especificar los nombres de las APIs añadiendo la extensión x-google-api-name a tu documento de OpenAPI. La extensión x-google-api-name te permite asignar nombres explícitos a APIs individuales y establecer versiones independientes para cada API.

Por ejemplo, puedes configurar un servicio llamado api.example.com con dos APIs, producer y consumer, con los fragmentos de documento OpenAPI que se muestran a continuación:

  • API Producer en producer.yaml: 

    swagger: 2.0
host: api.example.com
x-google-api-name: producer
info:
  version: 1.0.3

  • API Consumer en consumer.yaml: 

    swagger: 2.0
host: api.example.com
x-google-api-name: consumer
info:
  version: 1.1.0

Puedes desplegar los dos documentos de OpenAPI conjuntamente con:

gcloud api-gateway api-configs create API_CONFIG_ID \
  --api=my-api \
  --openapi-spec="producer.yaml,consumer.yaml" \
  --project=my-project-id