Se usó la API de Cloud Translation para traducir esta página.

Extensiones de OpenAPI

OpenAPI | gRPC

Cloud Endpoints acepta un conjunto de extensiones específicas de Google para la especificación de OpenAPI, que configuran los comportamientos del proxy de servicio extensible y del Control de servicios. En esta página, se describen las extensiones específicas de Google para la especificación de OpenAPI.

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

Los valores posibles son configured y all.

El valor predeterminado es configured, lo que significa que solo se entregan mediante el ESP 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 del ESP hasta tu API.

El ESP procesa las llamadas a tu API con distinción entre mayúsculas y minúsculas. Por ejemplo, el ESP 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, el ESP bloquea la solicitud siguiente 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, el ESP 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 locales o remotos. La extensión se puede especificar en el nivel superior o el nivel de operación de una especificación de OpenAPI.

De forma predeterminada, el ESP está configurado para usar un proxy en todo el tráfico hacia un solo backend local. La dirección de backend local se especifica mediante la marca --backend (el valor predeterminado es http://127.0.0.1:8081). Puedes usar la extensión x-google-backend para anular este comportamiento predeterminado y especificar uno o más backends locales o remotos que pueden recibir solicitudes.

La extensión x-google-backend también puede establecer otras opciones de configuración para backends locales y 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

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

Si una operación usa x-google-backend, pero no especifica address, ESPv2 enrutará las solicitudes al backend local que especifica la marca --backend.

`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, el ESPv2 establecerá automáticamente de forma predeterminada el jwt_audience para que coincida con address. Si address no está configurado, ESPv2 establecerá automáticamente disable_auth en true.

`jwt_audience`

jwt_audience: string

Opcional. El público de JWT se especifica cuando el ESPv2 obtiene un token de ID de instancia, que luego se usa cuando se realiza la solicitud del backend de destino

Cuando se configura Endpoints para la computación sin servidores, el backend remoto debe protegerse solo a fin de permitir el tráfico desde ESPv2. El ESPv2 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 el ESPv2. El backend remoto puede verificar que la solicitud sea de ESPv2 según este token adjunto.

Por ejemplo, un backend remoto que se implementó en Cloud Run puede usar IAM para lo siguiente:

Restringir las invocaciones no autenticadas. Para ello, revoca roles/run.invoker de la principal allUsers especial.
Permite que solo el ESPv2 invoque el backend mediante la asignación de la función roles/run.invoker a la cuenta de servicio del entorno de ejecución del ESPv2.

De forma predeterminada, el ESPv2 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 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 característica está habilitada, el ESPv2 cambiará los encabezados en las solicitudes. Si una solicitud ya tiene el encabezado Authorization establecido, el ESPv2 hará lo siguiente:

Copiará el valor original en un encabezado nuevo X-Forwarded-Authorization.
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 el ESPv2 debe usar el encabezado X-Forwarded-Authorization para recuperar todo el JWT. El backend debe verificar el JWT en este encabezado, ya que el ESPv2 no realizará una verificación cuando los métodos de autenticación no están configurados.

`disable_auth`

disable_auth: bool

Opcional. Esta propiedad determina si el ESPv2 debería evitar obtener un token de ID de instancia y evitar adjuntarlo a la solicitud.

Cuando configuras tu backend de destino, es posible que no desees usar IAP o IAM para autenticar solicitudes desde ESPv2 si se cumple alguna de estas condiciones:

El backend debe permitir invocaciones sin autenticación.
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 ]

Opcional. Configura la estrategia de traducción de ruta de acceso que usa el ESPv2 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 para Comprende la traducción de la ruta 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

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. ESPv2 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, 3600.0 durante una hora.

`protocol`

protocol: [ http/1.1 | h2 ]

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 sin servidores de Google Cloud.

Habilita la compatibilidad de backends en el ESP

El ESPv2 detectará automáticamente cuando se configure x-google-backend.

El ESP requiere un cambio de configuración manual para habilitar esta función. Para habilitar la compatibilidad de x-google-backend en el ESP, proporciona el argumento --enable_backend_routing cuando ejecutes el contenedor del ESP. (En los entornos de ejecución en los que no controlas las opciones del contenedor del ESP, esta opción ya está disponible para ti). El siguiente es un ejemplo de cómo habilitar la compatibilidad de x-google-backend cuando se implementa el contenedor del ESP en GKE (este ejemplo se basa en el del instructivo de Endpoints en GKE):

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port", "8081",
    "--service", "SERVICE_NAME",
    "--rollout_strategy", "managed",
    "--enable_backend_routing"
  ]

Comprende la traducción de la ruta de acceso

Cuando el ESP 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 el DNS en el dominio `cloud.goog`

Si implementaste tu aplicación en Compute Engine o Google Kubernetes Engine, puedes crear una entrada de DNS para tu servicio de Endpoints en el dominio cloud.goog mediante el agregado siguiente a tu documento de OpenAPI:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

Agrega la extensión x-google-endpoints en el nivel superior de tu documento de OpenAPI (sin sangría ni anidado). Debes configurar el nombre de dominio con el siguiente formato: .endpoints.PROJECT_ID.cloud.goog

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"
  target: "192.0.2.1"

Google administra el dominio .cloud.goog, y los clientes de Google Cloud lo comparten. Debido a que los ID de proyecto de Google Cloud son únicos a nivel mundial, un nombre de dominio con el formato .endpoints.PROJECT_ID.cloud.goog es un nombre de dominio único para tu API.

Para simplificar la tarea, configura los campos host y x-google-endpoints.name de manera que sean iguales. Cuando implementas tu documento de OpenAPI, Service Management crea lo siguiente:

Un servicio administrado con el nombre que especificaste en el campo host
Un registro A de DNS con el nombre y la dirección IP que configuraste en la extensión x-google-endpoints

Para las API alojadas en el entorno flexible de App Engine, puedes usar el dominio appspot.com. Si deseas obtener más información, consulta Cómo configurar Endpoints.

Configurar ESP 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 sobre cómo configurar el ESP a fin de que admita el CORS, consulta la sección para agregar compatibilidad con el CORS al ESP.

Si necesitas implementar la compatibilidad personalizada del CORS en tu código de backend, configura allowCors: True para que el ESP 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 ESP admite dos formatos asimétricos de claves públicas que define la extensión x-google-jwks_uri de OpenAPI:

Formato fijo de JWK. Por ejemplo:

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

X509. Por ejemplo:

x-google-jwks_uri: "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 como el URI de un archivo que contenga la string de clave codificada en base64url.

Si omites x-google-jwks_uri, el ESP seguirá el protocolo OpenID Connect Discovery a fin de descubrir automáticamente el URI de JWKS para el proveedor de OpenID determinado. El ESP hará una solicitud a x-google-issuer/.well-known/openid-configuration, analizará la respuesta JSON y leerá el URI de JWKS desde el campo de nivel superior jwks_uri.

Ten en cuenta que omitir x-google-jwks_uri dará como resultado horas de inicio en frío más altos, ya que el ESP debe realizar una llamada remota adicional durante el inicio. Por lo tanto, solo se recomienda omitir este campo si el URI de JWKS cambia con frecuencia. La mayoría de los proveedores de OpenID certificados (como Google, Auth0 y Okta) tienen URI de JWKS estables.

`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. Consulta Realiza una llamada autenticada a una API de Endpoints para ver ejemplos sobre cómo pasar un JWT.

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 el campo aud de JWT debe coincidir durante la autenticación de 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 de JWT debe coincidir con el campo host en el documento de OpenAPI, a menos que se use la marca --disable_jwt_audience_service_name_check. Si se usa la marca y no se especifica x-google-audiences, el campo aud de JWT no está verificado.

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 Extremos > Servicios de la consola de Google Cloud. Este texto también se muestra a los consumidores de tu API en las páginas Cuotas en IAM y administración y API y servicios. 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 la consola de Google Cloud. Por ejemplo, si especificas “Solicitudes de lectura” para el nombre visible, se mostrará “Solicitudes de lectura por minuto por proyecto” en la consola de Google 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 de 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. Actualmente, 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

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

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: 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 Endpoints. (Endpoints 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 API individuales y establecer el control de versiones independiente para cada API.

Por ejemplo, puedes configurar un servicio llamado api.example.com con dos API, productor y consumidor, con los fragmentos de documento de OpenAPI siguientes:

API de productor en producer.yaml:

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

API de consumidor 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 endpoints services deploy producer.yaml consumer.yaml

Extensiones de OpenAPI

Convención de nombres

x-google-allow

Ejemplo

x-google-backend

address

jwt_audience | disable_auth

jwt_audience

disable_auth

path_translation

deadline

protocol

Habilita la compatibilidad de backends en el ESP

Comprende la traducción de la ruta de acceso

x-google-endpoints

Configura el DNS en el dominio cloud.goog