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 puerta de enlace. En esta página, se describen las extensiones personalizadas específicas de Google para 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 administración de APIs.

Si bien los ejemplos proporcionados están en formato YAML, también se admite JSON.

Convención de nombres

Los nombres de las extensiones de OpenAPI de Google comienzan con 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 los métodos de API que enumeraste en tu especificación de OpenAPI se publican a través de API Gateway.

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

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

Cuando se usa all, debes tener especial cuidado en las dos áreas siguientes:

  • Cualquier clave de API o regla de autenticación
  • El enrutamiento de la ruta de backend en el servicio.

Como práctica recomendada, te sugerimos que configures tu API para que use el enrutamiento de rutas sensible a mayúsculas y minúsculas. Si usas el enrutamiento sensible a mayúsculas y minúsculas, tu API devolverá un código de estado HTTP 404 cuando el método solicitado en la URL no coincida con el nombre del método de la API que se indica en tu especificación de OpenAPI. Ten en cuenta que los frameworks de aplicaciones web, como Node.js Express, tienen un parámetro de configuración para habilitar o inhabilitar el enrutamiento sensible a mayúsculas y minúsculas. El comportamiento predeterminado depende del marco de trabajo que uses. Te recomendamos que revises la configuración de tu framework para asegurarte de que el enrutamiento sensible a mayúsculas y minúsculas esté habilitado. Esta recomendación concuerda con OpenAPI Specification v.2.0, que dice: "Todos los nombres de campo de la especificación distinguen entre mayúsculas y minúsculas".

Ejemplo

Supongamos lo siguiente:

  • x-google-allow se configura como all.
  • El método de API widgets se incluye en tu especificación de OpenAPI, pero Widgets no.
  • Configuraste la especificación de OpenAPI para que requiera una clave de API.

Como widgets aparece 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 pasa la siguiente solicitud a tu servicio sin una clave de API:

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

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

Los lenguajes y los marcos de trabajo diferentes tienen distintos métodos para controlar la distinción entre mayúsculas y minúsculas y el enrutamiento. Consulta la documentación para el marco de trabajo a fin de obtener más detalles.

x-google-backend

La extensión x-google-backend especifica cómo enrutar las solicitudes a los 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 parámetros para los backends 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. La URL del backend de destino El esquema de la dirección debe ser http o https.

Cuando se enruta a backends remotos (sin servidores), la dirección debe establecerse y la parte del esquema debe ser https.

jwt_audience | disable_auth

Solo se debe establecer una de estas dos propiedades.

Si una operación usa x-google-backend, pero no especifica jwt_audience ni disable_auth, API Gateway establecerá automáticamente jwt_audience de forma predeterminada para que coincida con address. Si no se configura address, API Gateway establecerá automáticamente disable_auth en true.

jwt_audience

jwt_audience: string

Es opcional. Es el público del JWT especificado cuando API Gateway obtiene un token de ID de instancia, que luego se usa cuando se realiza la solicitud de backend de destino.

Cuando configures API Gateway para Serverless, el backend remoto debe estar protegido para permitir solo el tráfico de API Gateway. API Gateway adjuntará un token de ID de instancia al encabezado Authorization cuando envíe solicitudes a través de un proxy. El token de ID de la instancia representa la cuenta de servicio del tiempo de ejecución que se usó para implementar API Gateway. Luego, el backend remoto puede verificar que la solicitud provenga de API Gateway según este token adjunto.

Por ejemplo, un backend remoto implementado en Cloud Run puede usar Identity and Access Management (IAM) para hacer lo siguiente:

  1. Restringir las invocaciones no autenticadas. Para ello, revoca roles/run.invoker de la principal allUsers especial.
  2. Otorga el rol roles/run.invoker a la cuenta de servicio del tiempo de ejecución de API Gateway para permitir que solo API Gateway invoque el backend.

De forma predeterminada, API Gateway creará el token de ID de instancia con un público de JWT que coincida con el campo address. 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 address. Para los backends remotos implementados en App Engine o con Identity-Aware Proxy (IAP), debes anular el público del JWT. App Engine y IAP usan su ID de cliente de OAuth como el público previsto.

Cuando esta función está habilitada, API Gateway mutará los encabezados en las solicitudes. Si una solicitud ya tiene establecido el encabezado Authorization, API Gateway hará lo siguiente:

  1. Copiará el valor original en un encabezado nuevo X-Forwarded-Authorization.
  2. Anulará el encabezado Authorization con el token de ID de instancia.

Por lo tanto, si un cliente de API establece el encabezado Authorization, un backend que se ejecuta detrás de API Gateway debe usar el encabezado X-Forwarded-Authorization para recuperar el JWT completo. El backend debe verificar el JWT en este encabezado, ya que API Gateway no realizará la verificación cuando no se configuren métodos de autenticación.

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

disable_auth

disable_auth: bool

Es opcional. Esta propiedad determina si API Gateway debe impedir la obtención de un token de ID de instancia y evitar que se adjunte a la solicitud.

Cuando configures tu backend de destino, es posible que no desees usar IAP o IAM para autenticar las solicitudes de API Gateway si se cumple alguna de las siguientes condiciones:

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

En este caso, configura este campo como true.

path_translation

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Es opcional. Establece la estrategia de traducción de rutas de acceso que usa API Gateway cuando envía solicitudes de proxy al backend de destino.

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

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

deadline

deadline: double

Es opcional. La cantidad de segundos que se espera una respuesta completa de una solicitud. Las respuestas que tarden más que la fecha límite configurada se agotarán. En un extremo de SSE o de transferencia fragmentada, el plazo sigue limitando la duración de toda la transmisión; en un extremo de gRPC o WebSocket, limita el intervalo entre mensajes. Consulta Cómo establecer la fecha límite de la transmisión para conocer los tiempos de espera que se aplican a cada tipo de solicitud. El plazo predeterminado es de 15.0 segundos.

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

El plazo se puede configurar hasta 3600 segundos. Una puerta de enlace sin transmisión aplica un máximo inferior de 600 segundos y rechaza un plazo mayor 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

protocol: [ http/1.1 | h2 ]

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

El valor predeterminado es http/1.1 para los backends HTTP y HTTPS.

Para los backends HTTP seguros (https://) que admiten HTTP/2, configura este campo como h2 para mejorar el rendimiento. Esta es la opción recomendada para los backends Google Cloud sin servidores.

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 incrementales: Puedes usar http/1.1 o h2. Recomendamos h2 para mejorar el rendimiento.

Comprende la traducción de rutas de acceso

A medida que API Gateway controla las solicitudes, toma la ruta de acceso de la solicitud original y la traduce antes de realizar una solicitud al backend de destino. La forma exacta en la que ocurre esta traducción depende de la estrategia de traducción de ruta de acceso que uses. Existen dos estrategias de traducción de ruta de acceso:

  • APPEND_PATH_TO_ADDRESS: La ruta de acceso de la solicitud al backend de destino se calcula mediante el agregado de la ruta de acceso de la solicitud original a la URL address de la extensión x-google-backend.
  • CONSTANT_ADDRESS: La ruta de acceso de la solicitud de destino es constante, tal como lo define la URL address de la extensión x-google-backend. Si la ruta de acceso de OpenAPI correspondiente contiene parámetros, el nombre del parámetro y su valor se convierten en parámetros de búsqueda.

Ejemplos:

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

Configura API Gateway para permitir solicitudes de CORS

Si tu API recibe una llamada desde una aplicación web en un origen diferente, la API debe admitir el uso compartido de recursos multiorigen (CORS). Consulta Cómo agregar compatibilidad con CORS a API Gateway para obtener información sobre cómo configurar API Gateway para que admita CORS.

Si necesitas implementar compatibilidad con CORS personalizada en tu código de backend, configura allowCors: True para que API Gateway pase todas las solicitudes de CORS a tu código de backend:

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

Agrega la extensión x-google-endpoints en el nivel superior de tu documento de OpenAPI (sin sangría ni anidado), 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 tomar la forma de un nombre de host o una dirección de correo electrónico.

x-google-jwks_uri

x-google-jwks_uri: URI

El URI del conjunto de claves públicas del proveedor configurado para validar la firma de JSON Web Token.

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

  • Formato fijo 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, configura x-google-jwks_uri (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) en el URI de un archivo que contenga la cadena de clave codificada en base64url.

x-google-jwt-locations

De forma predeterminada, los JWT se pasan en el encabezado Authorization (con el prefijo "Bearer "), en el encabezado X-Goog-Iap-Jwt-Assertion o en el parámetro de búsqueda access_token.

Como alternativa, usa la extensión x-google-jwt-locations en la sección securityDefinitions de OpenAPI para proporcionar las ubicaciones personalizadas desde donde 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 El nombre del encabezado que contiene el JWT o el nombre del parámetros de búsqueda que contiene el JWT.
value_prefix Opcional. Solo para el encabezado. Cuando se establece 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 deseas admitir solo un subconjunto de las ubicaciones de JWT predeterminadas, enuméralas de forma explícita en la extensión x-google-jwt-locations. Por ejemplo, para incluir asistencia solo 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 públicos que el campo aud del JWT debe coincidir durante la autenticación de JWT. Esta extensión acepta una sola cadena con valores separados por una coma. No se permiten espacios entre los públicos. Cuando no se especifica, el campo aud del 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 aspectos diferentes de la administración de API y contiene los campos que se describen en esta sección.

metrics

Usas metrics junto con la cuota y x-google-quota a fin de configurar una cuota para tu API. Una cuota te permite controlar la frecuencia con la que las aplicaciones pueden llamar a los métodos en 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 pares clave-valor siguientes:

Elemento Descripción
nombre Obligatorio. El nombre de esta métrica. Por lo general, este es el tipo de solicitud (por ejemplo, "solicitudes de lectura" o "solicitudes de escritura") que identifica la métrica de forma única.
displayName

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

A fin de facilitar la lectura, la unidad del límite de cuota asociado se agrega automáticamente al nombre visible en la consola deGoogle Cloud . Por ejemplo, si especificas "Solicitudes de lectura" para el nombre visible, se mostrará "Solicitudes de lectura por minuto por proyecto" en la consola deGoogle Cloud . Si no se especifica, se muestra la "cuota sin etiqueta" a los consumidores de tu API en las páginas Cuotas en IAM y administración y APIs y servicios.

Si deseas 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 tengas en cuenta lo siguiente para el nombre visible:

  • Utiliza "Solicitudes" cuando solo tengas una métrica.
  • Cuando tengas varias métricas, cada una debe describir el tipo de solicitud y debe contener la palabra "solicitudes" (por ejemplo, "Solicitudes de lectura" o "Solicitudes de escritura").
  • Utiliza "unidades de cuota" en lugar de "solicitudes" cuando alguno de los costos asociados con la métrica sea mayor que 1.
valueType Obligatorio. Debe ser INT64.
metricKind Obligatorio. Debe ser DELTA.

quota

Especificas el límite de cuota para una métrica definida en la sección quota. 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 pares clave-valor siguientes:

Elemento Descripción
nombre Obligatorio. Nombre del límite, que debe ser único dentro del servicio. El nombre puede contener letras mayúsculas y minúsculas, números y "-" (el carácter de guion), y debe tener una longitud máxima de 64 caracteres.
métrica Obligatorio. El 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 un nombre de métrica, recibirás un error cuando implementes tu documento de OpenAPI.
unidad Obligatorio. La 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 para la métrica. Debes especificarlo como un par clave-valor con el formato siguiente: 
STANDARD: YOUR-LIMIT-FOR-THE-METRIC
Reemplaza YOUR-LIMIT-FOR-THE-METRIC por un valor entero que sea la cantidad máxima de solicitudes permitidas para la unidad especificada (que solo es 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 paths de OpenAPI para asociar un método en tu API con una métrica. Los métodos que no tienen definido el valor de x-google-quota no poseen límites de cuota aplicados a ellos. Por ejemplo:

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

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

Elemento Descripción
metricCosts Un par clave-valor definido por el usuario: "YOUR-METRIC-NAME": METRIC-COST.
  • "YOUR-METRIC-NAME": El texto para "YOUR-METRIC-NAME" debe coincidir con un nombre de métrica definido.
  • METRIC-COST: Un valor de número entero que define el costo de cada solicitud. Cuando se realiza una solicitud, la métrica asociada se incrementa según el costo especificado. El costo permite que los métodos realicen un consumo de la misma métrica a velocidades diferentes. Por ejemplo, si una métrica tiene un límite de cuota de 1,000 y un costo de 1, la aplicación que realiza la llamada puede hacer 1,000 solicitudes por minuto antes de sobrepasar el límite. Con un costo de 2 para la misma métrica, la aplicación puede hacer solo 500 solicitudes por minuto antes de sobrepasar el límite.

Ejemplos de cuota

En el ejemplo siguiente, se muestra cómo agregar una métrica y un límite para las solicitudes de lectura y de 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

Cuando tu servicio contiene solo una API, el nombre de la API es el mismo que el nombre del servicio de API Gateway. (API Gateway usa el nombre que especificas en el campo host de tu documento de OpenAPI como el nombre de tu servicio). Cuando tu servicio contiene más de una API, especificas los nombres de API mediante el agregado de la extensión x-google-api-name a tu documento de OpenAPI. La extensión x-google-api-name te permite nombrar de forma explícita 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 documentos de OpenAPI que se muestran aquí:

  • API de productores en producer.yaml:

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

  • API de consumidores en consumer.yaml:

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

Puedes implementar los dos documentos de OpenAPI de forma conjunta con el comando siguiente:

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