En esta página, se describe cómo configurar cuotas para tu API. A grandes rasgos, los pasos son los siguientes:
- Agrega la información sobre la cuota a tu archivo de configuración de OpenAPI.
- Implementa tu archivo de configuración de OpenAPI.
- Implementa el proxy de servicio extensible (ESP).
Para obtener una descripción general de la funcionalidad que proporcionan las cuotas, consulta Acerca de las cuotas.
Requisitos previos
Como punto de partida, en esta página se supone que ya:
- Configuraste Cloud Endpoints
- Implementaste la configuración de Endpoints.
- Implementaste el backend de la API.
- Configuraste tu API para que use una clave de API. Esto es necesario para que, en Endpoints, se identifique el proyecto de Google Cloud al que está asociada la aplicación desde la que se realiza la llamada. Consulta Compartir API protegidas por claves de API para obtener más información.
Cómo agregar una cuota a tu documento de OpenAPI
A continuación, se describe el procedimiento para agregar las extensiones necesarias a tu documento de OpenAPI a fin de configurar cuotas. Para simplificar, en esta página se hace referencia al documento de OpenAPI al igual que al archivo openapi.yaml
y se proporcionan las extensiones de OpenAPI solo en formato YAML.
Agrega las siguientes tres secciones al archivo openapi.yaml
:
x-google-management.metrics
: una métrica con nombre que cuenta las solicitudes enviadas a tu API. Debes proporcionar un nombre que describa el recuento. Este puede ser una categoría, comoread-requests
owrite-requests
. Como alternativa, si defines una cuota para un método en particular, es posible que necesites incluir el nombre del método, por ejemplo,echo-api/echo_requests
.x-google-management.quota.limits
: representa un único límite de aplicación forzosa de una métrica con nombre. Aquí es donde configuras el número permitido de solicitudes para una métrica que definiste. Por el momento, solo hay compatibilidad con límites por proyecto y por minuto.x-google-quota.metricCosts
: los métodos de mapametricCosts
a las métricas (varios a varios). Una solicitud a un método asigna un contador por cada una de las métricas asignadas. Cuando asocias un método a una métrica, siempre debes especificar un costo para la solicitud. Puedes configurar el costo de cada método de forma independiente. Esto permite que los diferentes métodos consuman de la misma métrica con nombre a diferentes velocidades. Si no tienes un requisito complejo de cuotas, puedes establecer el costo de cada métrica en 1.
Para configurar cuotas en tu API, completa los siguientes pasos:
- Abre el archivo
openapi.yaml
de tu proyecto en un editor de texto. - Si aún no lo tienes, agrega la extensión
x-google-management
en la raíz del archivo (sin sangría ni anidado) antes de la sección que define las rutas. Agrega la definición
metrics
con sangría enx-google-management
.x-google-management: metrics: - name: "YOUR_METRIC_NAME" displayName: "YOUR_METRIC-DISPLAY_NAME" valueType: INT64 metricKind: DELTA
- Reemplaza
YOUR_METRIC_NAME
por un nombre con el que se describa el recuento de solicitudes a la API. - Reemplaza
YOUR_METRIC_DISPLAY_NAME
por el texto que se muestra en la página Endpoints > Servicios > Cuotas para identificar la métrica. - El campo
valueType
debe serINT64
. - El campo
metricKind
debe serDELTA
.
- Reemplaza
Agrega un campo
quota
al mismo nivel quemetrics
, y un campolimits
anidado dentro de la secciónquota
.quota: limits: - name: "YOUR_LIMIT_NAME" metric: "YOUR_METRIC_NAME" unit: "1/min/{project}" values: STANDARD: VALUE_FOR_THE_LIMIT
- Reemplaza
YOUR_LIMIT_NAME
por un nombre con el que se describa el límite. - Reemplaza
YOUR_METRIC_NAME
por unmetric.name
que ya esté definido. - El campo
unit
debe ser"1/min/{project}"
. Este es el identificador del límite por minuto por proyecto. - El campo
values
debe contenerSTANDARD
. - Reemplaza
VALUE_FOR_THE_LIMIT
por un número entero. Esta es la cantidad de solicitudes que se pueden realizar en un minuto con una aplicación asociada al proyecto de Google Cloud de un consumidor.
- Reemplaza
De manera opcional, puedes definir métricas y límites adicionales para cada métrica.
En la sección
paths
del archivoopenapi.yaml
, agrega la extensiónx-google-quota
con sangría a cada método al que quieres aplicar una cuota.x-google-quota: metricCosts: YOUR_METRIC_NAME: YOUR_METRIC_COST
- Reemplaza
YOUR_METRIC_NAME
por unmetric.name
que ya esté definido. - Reemplaza
YOUR_METRIC_COST
por un número entero. En cada solicitud, el contador de solicitudes de la métrica aumenta según la cantidad que especifiques para el costo.
- Reemplaza
Guarda el archivo
openapi.yaml
.
Ejemplos de configuración de cuotas
En los tres ejemplos siguientes, se muestra cómo configurar cuotas en tu API.
En el ejemplo siguiente, se muestra cómo configurar el campo metric
:
x-google-management: metrics: # Define a metric for read requests. - name: "read-requests" displayName: "Read requests" valueType: INT64 metricKind: DELTA
En el ejemplo siguiente, se muestra cómo configurar los campos quota
y limits
dentro de la sección quota
:
x-google-management: metrics: # Define a metric for read requests. - name: "read-requests" displayName: "Read requests" valueType: INT64 metricKind: DELTA quota: limits: # Define the limit or the read-requests metric. - name: "read-limit" metric: "read-requests" unit: "1/min/{project}" values: STANDARD: 1000
En el ejemplo siguiente, se muestra cómo configurar la extensión x-google-quota
en la sección paths
:
x-google-management: metrics: # Define a metric for read requests. - name: "read-requests" displayName: "Read requests" valueType: INT64 metricKind: DELTA quota: limits: # Define the limit or the read-requests metric. - name: "read-limit" metric: "read-requests" unit: "1/min/{project}" values: STANDARD: 1000 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: []
Consulta las extensiones de OpenAPI para obtener más ejemplos y descripciones detalladas de las extensiones x-google-management
y x-google-quota
.
Implementa el archivo openapi.yaml
y el ESP
Para que la cuota se aplique, debes hacer lo siguiente:
- Implementa el archivo
openapi.yaml
en Administración de servicio para que se actualice la configuración de Endpoints. - Implementa el ESP. Los pasos para implementar el ESP varían según el backend en el que se implementa tu API.
Para ver los pasos detallados, consulta Implementa el backend de la API.