Configuring Quotas

This page describes how to configure quotas for your API. At a high level, the steps are:

  1. Add the information about the quota to your gRPC API configuration file.
  2. Deploy your gRPC API configuration file.
  3. Deploy the Extensible Service Proxy.

For an overview of the functionality provided by quotas, see About Quotas.

Prerequisites

As a starting point, this page assumes that you have:

Configuring your gRPC API configuration file

The following procedure describes adding the required settings to your gRPC API configuration file to set up quotas. For simplicity, this page refers to the gRPC API configuration file as api_config.yaml.

You will add three sections to api_config.yaml:

  • metrics: A named metric that counts requests to your API. You provide a name that describes the counter. The name could be a category, such as read-requests or write-requests. Alternatively, if you are defining a quota for a specific method, you might want to include the method name, for example: echo-api/echo_requests

  • quota.limits: Represents a single enforceable limit on a named metric. This is where you configure the allowed number of requests for a metric that you have defined. Currently, only per-minute, per-project limits are supported.

  • quota.metric_rules: A metric_rule maps methods to metrics (many-to-many). A request to a method allocates a counter for each of the mapped metrics. When you associate a method with a metric, you always specify a cost for the request. You can configure the cost of each method independently. This allows different methods to consume at different rates from the same named metric. If you don't have a complex quota requirement, you can configure the cost of every metric to 1.

To configure quotas on your API:

  1. Open your project's api_config.yaml file in a text editor.
  2. Add the metrics field at the top level of the file (not indented or nested), below the apis field.`

    metrics:
      -name: "[YOUR-METRIC-NAME]"
        display_name: "[YOUR-METRIC-DISPLAY-NAME]"
            value_type: INT64
        metric_kind: DELTA`
    
    1. Replace [YOUR-METRIC-NAME] with a name that describes the API requests counter.
    2. Replace [YOUR-METRIC-DISPLAY-NAME] with the text that will be displayed in the Endpoints dashboard on the Quotas page to identify the metric.
    3. The value_type field must be INT64.
    4. The metric_kind field must be DELTA.

  3. Add a quota field at the same level as metrics, and add a limits field nested within the quota section.

    quota:
      limits:
        - name: "[YOUR-LIMIT-NAME]"
          metric: "[YOUR-METRIC-NAME]"
          unit: "1/min/{project}"
          values:
            STANDARD: [VALUE-FOR-THE-LIMIT]
    
    1. Replace [YOUR-LIMIT-NAME] with a name that describes the limit.
    2. Replace [YOUR-METRIC-NAME] with a previously defined metric.name.
    3. The unit field must be "1/min/{project}". This is the identifier for the per-minute per-project limit.
    4. The values field must contain STANDARD.
    5. Replace [VALUE-FOR-THE-LIMIT] with an integer value. This is the number of requests that an application associated with a consumer's Cloud project can make in a minute.

  4. Optionally, define additional metrics and limits for each metric.

  5. Add a metric_rules line indented under quota, after the limits section. Within the metric_rules section, associate a previously defined metric with a method, as follows:

      metric_rules:
        - metric_costs:
            [YOUR-METRIC-NAME]: [YOUR-METRIC-COST]
          selector: [METHODS]
    
    1. Replace [YOUR-METRIC-NAME] with a previously defined metric.name.
    2. Replace [YOUR-METRIC-COST] with an integer. For each request, the request counter for the metric is incremented by the number you specify for the cost.
    3. For the selector field, you can specify one of the following:

      • To associate all methods in all APIs with the metric_cost: **selector: "*"**
      • To associate all methods within an API with the metric_cost: **selector: [YOUR-API-NAME].***
      • To associate a specific method within an API with the metric_cost: **selector: [YOUR-API-NAME].[YOUR-METHOD-NAME]**
  6. Save api_config.yaml.

The following example shows the three sections that you must add:

  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
  metric_rules:
      - metric_costs:
          "read-requests": 1
        selector: *

Deploying api_config.yaml and the Extensible Service Proxy

For the quota to take effect, you must:

  1. Deploy api_config.yaml to Service Management, which updates the configuration in Cloud Endpoints. For detailed steps, see Deploying the Endpoints Configuration](/endpoints/docs/grpc/deploy-endpoints-config).
  2. Deploy the Extensible Service proxy. For detailed steps, see Deploying the API Backend.

Send feedback about...

Cloud Endpoints with gRPC