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.

Aunque los ejemplos que se proporcionan a continuación 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 se entregan mediante API Gateway los métodos de API que incluiste en tu especificación de OpenAPI.

Cuando se usa all, las llamadas sin configurar (ya sea con o sin una clave de API o autenticación del usuario) pasan a través de API Gateway hasta tu API.

API Gateway procesa las llamadas a tu API con distinción entre 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.

Recomendamos que configures tu API para utilizar un enrutamiento de ruta que distinga entre mayúsculas y minúsculas. Si se usa el enrutamiento con distinción entre mayúsculas y minúsculas, tu API muestra un código de estado HTTP de 404 cuando el método solicitado en la URL no coincide con el nombre del método de API que figura en tu especificación de OpenAPI. Ten en cuenta que los marcos de trabajo de las aplicaciones web, como Node.js Express, tienen una configuración para habilitar o inhabilitar el enrutamiento que distingue entre mayúsculas y minúsculas. El comportamiento predeterminado depende del marco de trabajo que uses. Te recomendamos que revises la configuración en el marco de trabajo para asegurarte de que el enrutamiento que distingue entre 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.

Debido a que 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

Debido a que Widgets no aparece en tu especificación de OpenAPI, API Gateway pasa la solicitud siguiente a tu servicio sin una clave de API:

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

Si tu API usa un enrutamiento que distingue entre mayúsculas y minúsculas (y no enrutaste las llamadas a "Widgets" a ningún código), el backend de tu API muestra un 404. Sin embargo, si usas un enrutamiento que no distingue entre mayúsculas y minúsculas, el backend de tu 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 solicitudes a backends remotos. La extensión se puede especificar en el nivel superior, el nivel de operación o ambos niveles de una especificación de OpenAPI.

La extensión x-google-backend también puede establecer otros parámetros de configuración para 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 de forma predeterminada el jwt_audience para que coincida con address. Si address no está configurado, API Gateway establecerá automáticamente disable_auth en true.

jwt_audience

jwt_audience: string

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

Cuando configures API Gateway para la computación sin servidores, el backend remoto debe protegerse solo a fin de permitir el tráfico desde API Gateway. API Gateway adjuntará un token de ID de instancia al encabezado Authorization cuando se envíen solicitudes de proxy. El token de ID de instancia representa la cuenta de servicio del entorno 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 que se implementó en Cloud Run puede usar Identity and Access Management (IAM) para lo siguiente:

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

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 de 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 cambiará los encabezados en las solicitudes. Si una solicitud ya tiene el encabezado Authorization establecido, 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 la API establece el encabezado Authorization, un backend que se ejecuta con API Gateway debe usar el encabezado X-Forwarded-Authorization para recuperar todo el JWT. El backend debe verificar el JWT en este encabezado, ya que la puerta de enlace de API no realizará una verificación cuando los métodos de autenticación no estén configurados.

Para ver ejemplos de configuración, consulta Cómo crear una configuración de API.

disable_auth

disable_auth: bool

Es opcional. Esta propiedad determina si API Gateway debería evitar obtener un token de ID de instancia y evitar adjuntarlo a la solicitud.

Cuando configures tu backend de destino, es posible que no desees usar IAP o IAM para autenticar solicitudes desde API Gateway si se cumple alguna de estas 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. Configura la estrategia de traducción de ruta de acceso que usa API Gateway cuando se envían solicitudes de proxy al backend de destino.

Si deseas obtener más detalles sobre la traducción de rutas de acceso, consulta la sección Comprende 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 no se especificará y no ocurrirá.

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 el plazo configurado agotarán el tiempo de espera. El plazo predeterminado es 15.0 segundos.

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

El plazo no se puede inhabilitar, pero se puede establecer en un número alto, por ejemplo, 600 segundos (el plazo máximo).

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 backends HTTP seguros (https://) compatibles con HTTP/2, establece este campo en h2 con el fin de mejorar el rendimiento. Esta es la opción recomendada para los backends Google Cloud sin servidores.

Comprende la traducción de rutas de acceso

Cuando API Gateway maneje las solicitudes, tomará la ruta de acceso de la solicitud original y la traducirá 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). Si deseas obtener información para configurar API Gateway de modo que admita CORS, consulta Cómo agregar compatibilidad con CORS a API Gateway.

Si necesitas implementar la compatibilidad personalizada del CORS 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étrico, configura x-google-jwks_uri (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) como el URI de un archivo que contiene 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 con los que debe coincidir el campo aud del JWT durante la autenticación con JWT. Esta extensión acepta una sola cadena con valores separados por comas. 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 & Services. El nombre comercial debe contener un máximo de 40 caracteres.

Para facilitar la lectura, la unidad del límite de cuota asociado se agrega automáticamente al nombre visible en laGoogle Cloud consola. 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 "cuota sin etiquetar" a los consumidores de tu API en las páginas Cuotas en IAM y administración y API 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
Reemplazas YOUR-LIMIT-FOR-THE-METRIC por un valor de número entero que representa el número máximo de solicitudes que se permiten para la unidad especificada (actualmente es solo por minuto, 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 explícitamente APIs individuales y establecer el control de versiones independiente para cada API.

Por ejemplo, puedes configurar un servicio llamado api.example.com con dos APIs, productor y consumidor, con los fragmentos de documento 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