Method: services.allocateQuota

Attempts to allocate quota for the specified consumer. It should be called before the operation is executed.

This method requires the servicemanagement.services.quota permission on the specified service. For more information, see Cloud IAM.

NOTE: The client must fail-open on server errors INTERNAL, UNKNOWN, DEADLINE_EXCEEDED, and UNAVAILABLE. To ensure system reliability, the server may inject these errors to prohibit any hard dependency on the quota functionality.

HTTP request

POST https://servicecontrol.googleapis.com/v1/services/{serviceName}:allocateQuota

The URL uses Google API HTTP annotation syntax.

Path parameters

Parameters
serviceName

string

Name of the service as specified in the service configuration. For example, "pubsub.googleapis.com".

See google.api.Service for the definition of a service name.

Authorization requires the following Google IAM permission on the specified resource service_name:

  • servicemanagement.services.quota

Request body

The request body contains data with the following structure:

JSON representation
{
  "allocateOperation": {
    object(QuotaOperation)
  },
  "serviceConfigId": string,
}
Fields
allocateOperation

object(QuotaOperation)

Operation that describes the quota allocation.

serviceConfigId

string

Specifies which version of service configuration should be used to process the request. If unspecified or no matching version can be found, the latest one will be used.

Response body

If successful, the response body contains data with the following structure:

Response message for the services.allocateQuota method.

JSON representation
{
  "operationId": string,
  "allocateErrors": [
    {
      object(QuotaError)
    }
  ],
  "quotaMetrics": [
    {
      object(MetricValueSet)
    }
  ],
  "serviceConfigId": string,
}
Fields
operationId

string

The same operationId value used in the AllocateQuotaRequest. Used for logging and diagnostics purposes.

allocateErrors[]

object(QuotaError)

Indicates the decision of the allocate.

quotaMetrics[]

object(MetricValueSet)

Quota metrics to indicate the result of allocation. Depending on the request, one or more of the following metrics will be included:

  1. Per quota group or per quota metric incremental usage will be specified using the following delta metric : "serviceruntime.googleapis.com/api/consumer/quota_used_count"

  2. The quota limit reached condition will be specified using the following boolean metric : "serviceruntime.googleapis.com/quota/exceeded"

serviceConfigId

string

ID of the actual config used to process the request.

Authorization

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/servicecontrol
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Auth Guide.

QuotaOperation

Represents information regarding a quota operation.

JSON representation
{
  "operationId": string,
  "methodName": string,
  "consumerId": string,
  "labels": {
    string: string,
    ...
  },
  "quotaMetrics": [
    {
      object(MetricValueSet)
    }
  ],
  "quotaMode": enum(QuotaMode),
}
Fields
operationId

string

Identity of the operation. This is expected to be unique within the scope of the service that generated the operation, and guarantees idempotency in case of retries.

UUID version 4 is recommended, though not required. In scenarios where an operation is computed from existing information and an idempotent id is desirable for deduplication purpose, UUID version 5 is recommended. See RFC 4122 for details.

methodName

string

Fully qualified name of the API method for which this quota operation is requested. This name is used for matching quota rules or metric rules and billing status rules defined in service configuration. This field is not required if the quota operation is performed on non-API resources.

Example of an RPC method name: google.example.library.v1.LibraryService.CreateShelf

consumerId

string

Identity of the consumer for whom this quota operation is being performed.

This can be in one of the following formats: project:, projectNumber:, apiKey:.

labels

map (key: string, value: string)

Labels describing the operation.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

quotaMetrics[]

object(MetricValueSet)

Represents information about this operation. Each MetricValueSet corresponds to a metric defined in the service configuration. The data type used in the MetricValueSet must agree with the data type specified in the metric definition.

Within a single operation, it is not allowed to have more than one MetricValue instances that have the same metric names and identical label value combinations. If a request has such duplicated MetricValue instances, the entire request is rejected with an invalid argument error.

quotaMode

enum(QuotaMode)

Quota mode for this operation.

QuotaMode

Supported quota modes.

Enums
UNSPECIFIED Guard against implicit default. Must not be used.
NORMAL For services.allocateQuota request, allocates quota for the amount specified in the service configuration or specified using the quota metrics. If the amount is higher than the available quota, allocation error will be returned and no quota will be allocated.
BEST_EFFORT The operation allocates quota for the amount specified in the service configuration or specified using the quota metrics. If the amount is higher than the available quota, request does not fail but all available quota will be allocated.
CHECK_ONLY For services.allocateQuota request, only checks if there is enough quota available and does not change the available quota. No lock is placed on the available quota either.

QuotaError

Represents error information for QuotaOperation.

JSON representation
{
  "code": enum(Code),
  "subject": string,
  "description": string,
}
Fields
code

enum(Code)

Error code.

subject

string

Subject to whom this error applies. See the specific enum for more details on this field. For example, "clientip:" or "project:".

description

string

Free-form text that provides details on the cause of the error.

Code

Error codes related to project config validations are deprecated since the quota controller methods do not perform these validations. Instead services have to call the services.check method, without quotaProperties field, to perform these validations before calling the quota controller methods. These methods check only for project deletion to be wipe out compliant.

Enums
UNSPECIFIED This is never used.
RESOURCE_EXHAUSTED Quota allocation failed. Same as google.rpc.Code.RESOURCE_EXHAUSTED.
BILLING_NOT_ACTIVE Consumer cannot access the service because the service requires active billing.
PROJECT_DELETED Consumer's project has been marked as deleted (soft deletion).
API_KEY_INVALID Specified API key is invalid.
API_KEY_EXPIRED Specified API Key has expired.