Managing Consumer Quota

This page describes how to use the Service Consumer Management API to view and override the quota limits enforced on individual consumers of your service.

Be sure to familiarize yourself with the service quota model to better understand the terminology used in this tutorial.

To program against the Service Infrastructure API, we recommend that you use one of our provided client libraries. To experiment with the API, you can follow the instructions in this guide and use the curl command to test the API without setting up a full application development environment.

Displaying service quota

For the purpose of this tutorial we'll use a project named consumer-project-id and a service named myservice.appspot.com. In each gcurl command, substitute your own service and consumer project of interest.

To use gcurl, first run the following alias command with authentication token:

alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

For more information, see Getting Started

To see all quota limits on all metrics that apply to a particular consumer, use the following method:

gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/services/myservice.appspot.com/projects/consumer-project-id/consumerQuotaMetrics

This call responds with a list of metrics defined by the service, each with the list of limits on those metrics that apply to this consumer, the values for those limits, and any overrides. Here's an example response:

{
  "metrics": [
    {
      "name": "services/myservice.appspot.com/projects/consumer-project-id/consumerQuotaMetrics/airport_requests",
      "metric": "airport_requests"
      "displayName": "Airport Requests"
      "consumerQuotaLimits": [
        {
          "name": "services/myservice.appspot.com/projects/consumer-project-id/consumerQuotaMetrics/airport_requests/limits/%2Fmin%2Fproject",
          "metric": "airport_requests",
          "unit": "1/min/{project}",
          "quotaBuckets": [
            {
              "effectiveLimit": "5",
              "defaultLimit": "5",
            }
          ]
        }
      ],
    }
  ]
}

Each metric in the response has a name field; to inspect quota settings for just that metric, rather than for all metrics, use its name in the URL:

gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/{name}

Similarly, each limit within a metric has a name field; to inspect quota settings for just that limit on that metric, rather than for all limits on a metric or all metrics, use its name in the URL:

gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/{name}

Applying a producer override

The owner or administrator of a service may apply a producer override to a specific limit for a specific consumer, granting a quota increase on that limit.

To identify a limit, first use one of the methods above to find the quota limit of interest, and use its name field to apply a producer override to it:

gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/{name}/producerOverrides -d '{"override": {"override_value": "12345"} }'

This call can be used to apply a new override or update an existing override to a new value. To grant unlimited quota on a limit, use "-1" as the override value.

If the call succeeds, it will return an operation identifier, which represents ongoing work on the server, as the quota change propagates to backend systems:

{
  "name": "operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
}

To check the progress of the operation, use its name:

gcurl https://serviceconsumermanagement.googleapis.com/v1/{name}

When this call responds with a message that includes "done":true, then the operation is finished. If the operation failed, the message will include error details.

You can also check whether a change has been applied by repeating the original get call on the specific limit. The limit should now have an additional "producerOverride" field.

Forcing large quota changes

If an override would cause the enforced quota to decrease by more than 10%, the call is rejected, as a safety measure to avoid accidentally decreasing quota too quickly. To disregard this restriction, use the force flag:

gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/{name}/producerOverrides -d '{"override": {"override_value": "0"}, "force": true}'

Applying regional or zonal quota overrides

Some quota limits are enforced on a per-region or per-zone basis; this is indicated by the presence of /{region} or /{zone} in the limit unit.

Applying an override to such a limit changes the base quota on every region or zone. To change the quota for only a specific region or zone, use the location field:

gcurl https://serviceconsumermanagement.googleapis.com/v1beta1/{name}/producerOverrides -d '{"override": {"override_value": "135", "dimensions": {"region": "asia-south1"} } }'