Configura cuotas

OpenAPI | gRPC

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, como read-requests o write-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 mapa metricCosts 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 en x-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 ser INT64.
- El campo metricKind debe ser DELTA.
Agrega un campo quota al mismo nivel que metrics, y un campo limits anidado dentro de la sección quota.
```
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 un metric.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 contener STANDARD.
- 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.
De manera opcional, puedes definir métricas y límites adicionales para cada métrica.
En la sección paths del archivo openapi.yaml, agrega la extensión x-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 un metric.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.
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.