Package google.api.servicecontrol.v1

Index

QuotaController

Google Quota Control API

Allows clients to allocate and release quota against a managed service.

AllocateQuota

rpc AllocateQuota(AllocateQuotaRequest) returns (AllocateQuotaResponse)

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.

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.

ServiceController

Google Service Control API

Lets clients check and report operations against a managed service.

Check

rpc Check(CheckRequest) returns (CheckResponse)

Checks an operation with Google Service Control to decide whether the given operation should proceed. It should be called before the operation is executed.

If feasible, the client should cache the check results and reuse them for 60 seconds. In case of server errors, the client can rely on the cached results for longer time.

NOTE: the CheckRequest has the size limit of 64KB.

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

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.

Report

rpc Report(ReportRequest) returns (ReportResponse)

Reports operation results to Google Service Control, such as logs and metrics. It should be called after an operation is completed.

If feasible, the client should aggregate reporting data for up to 5 seconds to reduce API traffic. Limiting aggregation to 5 seconds is to reduce data loss during client crashes. Clients should carefully choose the aggregation time window to avoid data loss risk more than 0.01% for business and compliance reasons.

NOTE: the ReportRequest has the size limit of 1MB.

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

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.

AllocateQuotaRequest

Request message for the AllocateQuota method.

Fields
service_name

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

allocate_operation

QuotaOperation

Operation that describes the quota allocation.

service_config_id

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.

AllocateQuotaResponse

Response message for the AllocateQuota method.

Fields
operation_id

string

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

allocate_errors[]

QuotaError

Indicates the decision of the allocate.

quota_metrics[]

MetricValueSet

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

  1. For rate quota, 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. For allocation quota, per quota metric total usage will be specified using the following gauge metric: "serviceruntime.googleapis.com/allocation/consumer/quota_used_count"

  3. For both rate quota and allocation quota, the quota limit reached condition will be specified using the following boolean metric: "serviceruntime.googleapis.com/quota/exceeded"

  4. For allocation quota, value for each quota limit associated with the metrics will be specified using the following gauge metric: "serviceruntime.googleapis.com/quota/limit"

service_config_id

string

ID of the actual config used to process the request.

CheckError

Defines the errors to be returned in google.api.servicecontrol.v1.CheckResponse.check_errors.

Fields
code

Code

The error code.

detail

string

Free-form text providing details on the error cause of the error.

Code

Error codes for Check responses.

Enums
ERROR_CODE_UNSPECIFIED This is never used in CheckResponse.
NOT_FOUND The consumer's project id was not found. Same as google.rpc.Code.NOT_FOUND.
PERMISSION_DENIED The consumer doesn't have access to the specified resource. Same as google.rpc.Code.PERMISSION_DENIED.
RESOURCE_EXHAUSTED Quota check failed. Same as google.rpc.Code.RESOURCE_EXHAUSTED.
SERVICE_NOT_ACTIVATED The consumer hasn't activated the service.
BILLING_DISABLED The consumer cannot access the service because billing is disabled.
PROJECT_DELETED The consumer's project has been marked as deleted (soft deletion).
PROJECT_INVALID The consumer's project number or id does not represent a valid project.
IP_ADDRESS_BLOCKED The IP address of the consumer is invalid for the specific consumer project.
REFERER_BLOCKED The referer address of the consumer request is invalid for the specific consumer project.
CLIENT_APP_BLOCKED The client application of the consumer request is invalid for the specific consumer project.
API_TARGET_BLOCKED The API targeted by this request is invalid for the specified consumer project.
API_KEY_INVALID The consumer's API key is invalid.
API_KEY_EXPIRED The consumer's API Key has expired.
API_KEY_NOT_FOUND The consumer's API Key was not found in config record.
NAMESPACE_LOOKUP_UNAVAILABLE The backend server for looking up project id/number is unavailable.
SERVICE_STATUS_UNAVAILABLE The backend server for checking service status is unavailable.
BILLING_STATUS_UNAVAILABLE The backend server for checking billing status is unavailable.

CheckRequest

Request message for the Check method.

Fields
service_name

string

The service name as specified in its 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.check

operation

Operation

The operation to be checked.

service_config_id

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.

CheckResponse

Response message for the Check method.

Fields
operation_id

string

The same operation_id value used in the CheckRequest. Used for logging and diagnostics purposes.

check_errors[]

CheckError

Indicate the decision of the check.

If no check errors are present, the service should process the operation. Otherwise the service should use the list of errors to determine the appropriate action.

service_config_id

string

The actual config id used to process the request.

Distribution

Distribution represents a frequency distribution of double-valued sample points. It contains the size of the population of sample points plus additional optional information:

  • the arithmetic mean of the samples
  • the minimum and maximum of the samples
  • the sum-squared-deviation of the samples, used to compute variance
  • a histogram of the values of the sample points
Fields
count

int64

The total number of samples in the distribution. Must be >= 0.

mean

double

The arithmetic mean of the samples in the distribution. If count is zero then this field must be zero.

minimum

double

The minimum of the population of values. Ignored if count is zero.

maximum

double

The maximum of the population of values. Ignored if count is zero.

sum_of_squared_deviation

double

The sum of squared deviations from the mean: Sum[i=1..count]((x_i - mean)^2) where each x_i is a sample values. If count is zero then this field must be zero, otherwise validation of the request fails.

bucket_counts[]

int64

The number of samples in each histogram bucket. bucket_counts are optional. If present, they must sum to the count value.

The buckets are defined below in bucket_option. There are N buckets. bucket_counts[0] is the number of samples in the underflow bucket. bucket_counts[1] to bucket_counts[N-1] are the numbers of samples in each of the finite buckets. And bucket_counts[N] is the number of samples in the overflow bucket. See the comments ofbucket_option` below for more details.

Any suffix of trailing zeros may be omitted.

Union field bucket_option. Defines the buckets in the histogram. bucket_option and bucket_counts must be both set, or both unset.

Buckets are numbered the the range of [0, N], with a total of N+1 buckets. There must be at least two buckets (a single-bucket histogram gives no information that isn't already provided by count).

The first bucket is the underflow bucket which has a lower bound of -inf. The last bucket is the overflow bucket which has an upper bound of +inf. All other buckets (if any) are called "finite" buckets because they have finite lower and upper bounds. As described below, there are three ways to define the finite buckets.

(1) Buckets with constant width. (2) Buckets with exponentially growing widths. (3) Buckets with arbitrary user-provided widths.

In all cases, the buckets cover the entire real number line (-inf, +inf). Bucket upper bounds are exclusive and lower bounds are inclusive. The upper bound of the underflow bucket is equal to the lower bound of the smallest finite bucket; the lower bound of the overflow bucket is equal to the upper bound of the largest finite bucket. bucket_option can be only one of the following:

linear_buckets

LinearBuckets

Buckets with constant width.

exponential_buckets

ExponentialBuckets

Buckets with exponentially growing width.

explicit_buckets

ExplicitBuckets

Buckets with arbitrary user-provided width.

ExplicitBuckets

Describing buckets with arbitrary user-provided width.

Fields
bounds[]

double

'bound' is a list of strictly increasing boundaries between buckets. Note that a list of length N-1 defines N buckets because of fenceposting. See comments on bucket_options for details.

The i'th finite bucket covers the interval [bound[i-1], bound[i]) where i ranges from 1 to bound_size() - 1. Note that there are no finite buckets at all if 'bound' only contains a single element; in that special case the single bound defines the boundary between the underflow and overflow buckets.

bucket number lower bound upper bound i == 0 (underflow) -inf bound[i] 0 < i < bound_size() bound[i-1] bound[i] i == bound_size() (overflow) bound[i-1] +inf

ExponentialBuckets

Describing buckets with exponentially growing width.

Fields
num_finite_buckets

int32

The number of finite buckets. With the underflow and overflow buckets, the total number of buckets is num_finite_buckets + 2. See comments on bucket_options for details.

growth_factor

double

The i'th exponential bucket covers the interval [scale * growth_factor^(i-1), scale * growth_factor^i) where i ranges from 1 to num_finite_buckets inclusive. Must be larger than 1.0.

scale

double

The i'th exponential bucket covers the interval [scale * growth_factor^(i-1), scale * growth_factor^i) where i ranges from 1 to num_finite_buckets inclusive. Must be > 0.

LinearBuckets

Describing buckets with constant width.

Fields
num_finite_buckets

int32

The number of finite buckets. With the underflow and overflow buckets, the total number of buckets is num_finite_buckets + 2. See comments on bucket_options for details.

width

double

The i'th linear bucket covers the interval [offset + (i-1) * width, offset + i * width) where i ranges from 1 to num_finite_buckets, inclusive. Must be strictly positive.

offset

double

The i'th linear bucket covers the interval [offset + (i-1) * width, offset + i * width) where i ranges from 1 to num_finite_buckets, inclusive.

LogEntry

An individual log entry.

Fields
name

string

Required. The log to which this log entry belongs. Examples: "syslog", "book_log".

timestamp

Timestamp

The time the event described by the log entry occurred. If omitted, defaults to operation start time.

severity

LogSeverity

The severity of the log entry. The default value is LogSeverity.DEFAULT.

insert_id

string

A unique ID for the log entry used for deduplication. If omitted, the implementation will generate one based on operation_id.

labels

map<string, string>

A set of user-defined (key, value) data that provides additional information about the log entry.

Union field payload. The log entry payload, which can be one of multiple types. payload can be only one of the following:
proto_payload

Any

The log entry payload, represented as a protocol buffer that is expressed as a JSON object. The only accepted type currently is AuditLog.

text_payload

string

The log entry payload, represented as a Unicode string (UTF-8).

struct_payload

Struct

The log entry payload, represented as a structure that is expressed as a JSON object.

MetricValue

Represents a single metric value.

Fields
labels

map<string, string>

The labels describing the metric value. See comments on google.api.servicecontrol.v1.Operation.labels for the overriding relationship.

start_time

Timestamp

The start of the time period over which this metric value's measurement applies. The time period has different semantics for different metric types (cumulative, delta, and gauge). See the metric definition documentation in the service configuration for details.

end_time

Timestamp

The end of the time period over which this metric value's measurement applies.

Union field value. The value. The type of value used in the request must agree with the metric definition in the service configuration, otherwise the MetricValue is rejected. value can be only one of the following:
bool_value

bool

A boolean value.

int64_value

int64

A signed 64-bit integer value.

double_value

double

A double precision floating point value.

string_value

string

A text string value.

distribution_value

Distribution

A distribution value.

MetricValueSet

Represents a set of metric values in the same metric. Each metric value in the set should have a unique combination of start time, end time, and label values.

Fields
metric_name

string

The metric name defined in the service configuration.

metric_values[]

MetricValue

The values in this metric.

Operation

Represents information regarding an operation.

Fields
operation_id

string

Identity of the operation. This must be unique within the scope of the service that generated the operation. If the service calls Check() and Report() on the same operation, the two calls should carry the same id.

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.

operation_name

string

Fully qualified name of the operation. Reserved for future use.

consumer_id

string

Identity of the consumer who is using the service. This field should be filled in for the operations initiated by a consumer, but not for service-initiated operations that are not related to a specific consumer.

This can be in one of the following formats: project:, project_number:, api_key:.

start_time

Timestamp

Required. Start time of the operation.

end_time

Timestamp

End time of the operation. Required when the operation is used in ServiceController.Report, but optional when the operation is used in ServiceController.Check.

labels

map<string, string>

Labels describing the operation. Only the following labels are allowed:

  • Labels describing monitored resources as defined in the service configuration.
  • Default labels of metric values. When specified, labels defined in the metric value override these default.
  • The following labels defined by Google Cloud Platform:
    • cloud.googleapis.com/location describing the location where the operation happened,
    • servicecontrol.googleapis.com/user_agent describing the user agent of the API request,
    • servicecontrol.googleapis.com/service_agent describing the service used to handle the API request (e.g. ESP),
    • servicecontrol.googleapis.com/platform describing the platform where the API is served (e.g. GAE, GCE, GKE).

metric_value_sets[]

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.

log_entries[]

LogEntry

Represents information to be logged.

importance

Importance

DO NOT USE. This is an experimental field.

Importance

Defines the importance of the data contained in the operation.

Enums
LOW The API implementation may cache and aggregate the data. The data may be lost when rare and unexpected system failures occur.
HIGH The API implementation doesn't cache and aggregate the data. If the method returns successfully, it's guaranteed that the data has been persisted in durable storage.

QuotaError

Represents error information for QuotaOperation.

Fields
code

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 for allocate and release responses. 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 Check method, without quota_properties 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.
OUT_OF_RANGE Quota release failed. This error is ONLY returned on a NORMAL release. More formally: if a user requests a release of 10 tokens, but only 5 tokens were previously allocated, in a BEST_EFFORT release, this will be considered a success, 5 tokens will be released, and the result will be "Ok". If this is done in NORMAL mode, no tokens will be released, and an OUT_OF_RANGE error will be returned. Same as google.rpc.Code.OUT_OF_RANGE.
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.

QuotaOperation

Represents information regarding a quota operation.

Fields
operation_id

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.

method_name

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

consumer_id

string

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

This can be in one of the following formats: project:, project_number:, api_key:.

labels

map<string, string>

Labels describing the operation.

quota_metrics[]

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.

quota_mode

QuotaMode

Quota mode for this operation.

QuotaMode

Supported quota modes. This can be specified only when the operation is associated with a AllocateQuota and ReleaseQuota request.

Enums
UNSPECIFIED Guard against implicit default. Must not be used.
NORMAL For 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. For ReleaseQuota request, this mode is supported only for precise quota limits. In this case, this operation releases quota for the amount specified in the service configuration or specified using the quota metrics. If the release can make used quota negative, release error will be returned and no quota will be released.
BEST_EFFORT For AllocateQuota request, this mode is supported only for imprecise quota limits. In this case, 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. For ReleaseQuota request, this mode is supported for both precise quota limits and imprecise quota limits. In this case, this operation releases quota for the amount specified in the service configuration or specified using the quota metrics. If the release can make used quota negative, request does not fail but only the used quota will be released. After the ReleaseQuota request completes, the used quota will be 0, and never goes to negative.
CHECK_ONLY For 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. Not supported for ReleaseQuota request.

ReportRequest

Request message for the Report method.

Fields
service_name

string

The service name as specified in its 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.report

operations[]

Operation

Operations to be reported.

Typically the service should report one operation per request. Putting multiple operations into a single request is allowed, but should be used only when multiple operations are natually available at the time of the report.

If multiple operations are in a single request, the total request size should be no larger than 1MB. See ReportResponse.report_errors for partial failure behavior.

service_config_id

string

Specifies which version of service config should be used to process the request.

If unspecified or no matching version can be found, the latest one will be used.

ReportResponse

Response message for the Report method.

Fields
report_errors[]

ReportError

Partial failures, one for each Operation in the request that failed processing. There are three possible combinations of the RPC status:

  1. The combination of a successful RPC status and an empty report_errors list indicates a complete success where all Operations in the request are processed successfully.
  2. The combination of a successful RPC status and a non-empty report_errors list indicates a partial success where some Operations in the request succeeded. Each Operation that failed processing has a corresponding item in this list.
  3. A failed RPC status indicates a general non-deterministic failure. When this happens, it's impossible to know which of the 'Operations' in the request succeeded or failed.

service_config_id

string

The actual config id used to process the request.

ReportError

Represents the processing error of one Operation in the request.

Fields
operation_id

string

The Operation.operation_id value from the request.

status

Status

Details of the error when processing the Operation.