package google.api.servicecontrol.v1

Get desktop application:
View/edit binary Protocol Buffers messages

[Google Quota Control API](/service-control/overview) Allows clients to allocate and release quota against a [managed service](https://cloud.google.com/service-management/reference/rpc/google.api/servicemanagement.v1#google.api.servicemanagement.v1.ManagedService).

• rpc AllocateQuota (AllocateQuotaRequest, AllocateQuotaResponse)

  quota_controller.proto:45

  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](https://cloud.google.com/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.

  message AllocateQuotaRequest

  quota_controller.proto:51

  Request message for the AllocateQuota method.

  • string service_name = 1

    Name of the service as specified in the service configuration. For example, `"pubsub.googleapis.com"`. See [google.api.Service][google.api.Service] for the definition of a service name.

  • optional QuotaOperation allocate_operation = 2

    Operation that describes the quota allocation.

  • string service_config_id = 4

    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.

  message AllocateQuotaResponse

  quota_controller.proto:139

  Response message for the AllocateQuota method.

  • string operation_id = 1

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

  • repeated QuotaError allocate_errors = 2

    Indicates the decision of the allocate.

  • repeated MetricValueSet quota_metrics = 3

    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"

  • string service_config_id = 4

    ID of the actual config used to process the request.

[Google Service Control API](/service-control/overview) Lets clients check and report operations against a [managed service](https://cloud.google.com/service-management/reference/rpc/google.api/servicemanagement.v1#google.api.servicemanagement.v1.ManagedService).

• rpc Check (CheckRequest, CheckResponse)

  service_controller.proto:50

  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][google.api.servicecontrol.v1.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](https://cloud.google.com/iam).

  message CheckRequest

  service_controller.proto:74

  Request message for the Check method.

  • string service_name = 1

    The service name as specified in its service configuration. For example, `"pubsub.googleapis.com"`. See [google.api.Service](https://cloud.google.com/service-management/reference/rpc/google.api#google.api.Service) for the definition of a service name.

  • optional Operation operation = 2

    The operation to be checked.

  • string service_config_id = 4

    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.

  message CheckResponse

  service_controller.proto:95

  Response message for the Check method.

  • string operation_id = 1

    The same operation_id value used in the [CheckRequest][google.api.servicecontrol.v1.CheckRequest]. Used for logging and diagnostics purposes.

  • repeated CheckError check_errors = 2

    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.

  • string service_config_id = 5

    The actual config id used to process the request.

  • optional CheckResponse.CheckInfo check_info = 6

    Feedback data returned from the server during processing a Check request.

• rpc Report (ReportRequest, ReportResponse)

  service_controller.proto:68

  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][google.api.servicecontrol.v1.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](https://cloud.google.com/iam).

  message ReportRequest

  service_controller.proto:127

  Request message for the Report method.

  • string service_name = 1

    The service name as specified in its service configuration. For example, `"pubsub.googleapis.com"`. See [google.api.Service](https://cloud.google.com/service-management/reference/rpc/google.api#google.api.Service) for the definition of a service name.

  • repeated Operation operations = 2

    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][google.api.servicecontrol.v1.ReportResponse.report_errors] for partial failure behavior.

  • string service_config_id = 3

    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.

  message ReportResponse

  service_controller.proto:157

  Response message for the Report method.

  • repeated ReportResponse.ReportError report_errors = 1

    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.

  • string service_config_id = 2

    The actual config id used to process the request.

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

Used in: CheckResponse

• CheckError.Code code = 1

  The error code.

• string detail = 2

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

Error codes for Check responses.

Used in: CheckError

• ERROR_CODE_UNSPECIFIED = 0

  This is never used in `CheckResponse`.

• NOT_FOUND = 5

  The consumer's project id was not found. Same as [google.rpc.Code.NOT_FOUND][].

• PERMISSION_DENIED = 7

  The consumer doesn't have access to the specified resource. Same as [google.rpc.Code.PERMISSION_DENIED][].

• RESOURCE_EXHAUSTED = 8

  Quota check failed. Same as [google.rpc.Code.RESOURCE_EXHAUSTED][].

• SERVICE_NOT_ACTIVATED = 104

  The consumer hasn't activated the service.

• BILLING_DISABLED = 107

  The consumer cannot access the service because billing is disabled.

• PROJECT_DELETED = 108

  The consumer's project has been marked as deleted (soft deletion).

• PROJECT_INVALID = 114

  The consumer's project number or id does not represent a valid project.

• IP_ADDRESS_BLOCKED = 109

  The IP address of the consumer is invalid for the specific consumer project.

• REFERER_BLOCKED = 110

  The referer address of the consumer request is invalid for the specific consumer project.

• CLIENT_APP_BLOCKED = 111

  The client application of the consumer request is invalid for the specific consumer project.

• API_TARGET_BLOCKED = 122

  The API targeted by this request is invalid for the specified consumer project.

• API_KEY_INVALID = 105

  The consumer's API key is invalid.

• API_KEY_EXPIRED = 112

  The consumer's API Key has expired.

• API_KEY_NOT_FOUND = 113

  The consumer's API Key was not found in config record.

• NAMESPACE_LOOKUP_UNAVAILABLE = 300

  The backend server for looking up project id/number is unavailable.

• SERVICE_STATUS_UNAVAILABLE = 301

  The backend server for checking service status is unavailable.

• BILLING_STATUS_UNAVAILABLE = 302

  The backend server for checking billing status is unavailable.

Used in: CheckResponse

• optional ConsumerInfo consumer_info = 2

  Consumer info of this check.

`ConsumerInfo` provides information about the consumer project.

Used in: CheckInfo

• int64 project_number = 1

  The Google cloud project number, e.g. 1234567890. A value of 0 indicates no project number is found.

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

Used in: MetricValue

• int64 count = 1

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

• double mean = 2

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

• double minimum = 3

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

• double maximum = 4

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

• double sum_of_squared_deviation = 5

  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.

• repeated int64 bucket_counts = 6

  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 of `bucket_option` below for more details. Any suffix of trailing zeros may be omitted.

• oneof bucket_option

  Defines the buckets in the histogram. `bucket_option` and `bucket_counts` must be both set, or both unset. Buckets are numbered in 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.

  • Distribution.LinearBuckets linear_buckets = 7

    Buckets with constant width.

  • Distribution.ExponentialBuckets exponential_buckets = 8

    Buckets with exponentially growing width.

  • Distribution.ExplicitBuckets explicit_buckets = 9

    Buckets with arbitrary user-provided width.

Describing buckets with arbitrary user-provided width.

Used in: Distribution

• repeated double bounds = 1

  '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

Describing buckets with exponentially growing width.

Used in: Distribution

• int32 num_finite_buckets = 1

  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.

• double growth_factor = 2

  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.

• double scale = 3

  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.

Describing buckets with constant width.

Used in: Distribution

• int32 num_finite_buckets = 1

  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.

• double width = 2

  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.

• double offset = 3

  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.

An individual log entry.

Used in: Operation

• string name = 10

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

• optional protobuf.Timestamp timestamp = 11

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

• logging.type.LogSeverity severity = 12

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

• string insert_id = 4

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

• map<string, string> labels = 13

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

• oneof payload

  The log entry payload, which can be one of multiple types.

  • protobuf.Any proto_payload = 2

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

  • string text_payload = 3

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

  • protobuf.Struct struct_payload = 6

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

Represents a single metric value.

Used in: MetricValueSet

• map<string, string> labels = 1

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

• optional protobuf.Timestamp start_time = 2

  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.

• optional protobuf.Timestamp end_time = 3

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

• oneof 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.

  • bool bool_value = 4

    A boolean value.

  • int64 int64_value = 5

    A signed 64-bit integer value.

  • double double_value = 6

    A double precision floating point value.

  • string string_value = 7

    A text string value.

  • Distribution distribution_value = 8

    A distribution value.

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.

Used in: AllocateQuotaResponse, Operation, QuotaOperation

• string metric_name = 1

  The metric name defined in the service configuration.

• repeated MetricValue metric_values = 2

  The values in this metric.

Represents information regarding an operation.

Used in: CheckRequest, ReportRequest

• string operation_id = 1

  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.

• string operation_name = 2

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

• string consumer_id = 3

  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_id>, project_number:<project_number>, api_key:<api_key>.

• optional protobuf.Timestamp start_time = 4

  Required. Start time of the operation.

• optional protobuf.Timestamp end_time = 5

  End time of the operation. Required when the operation is used in [ServiceController.Report][google.api.servicecontrol.v1.ServiceController.Report], but optional when the operation is used in [ServiceController.Check][google.api.servicecontrol.v1.ServiceController.Check].

• map<string, string> labels = 6

  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).

• repeated MetricValueSet metric_value_sets = 7

  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.

• repeated LogEntry log_entries = 8

  Represents information to be logged.

• Operation.Importance importance = 11

  DO NOT USE. This is an experimental field.

Defines the importance of the data contained in the operation.

Used in: Operation

• LOW = 0

  The API implementation may cache and aggregate the data. The data may be lost when rare and unexpected system failures occur.

• HIGH = 1

  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.

Represents error information for [QuotaOperation][google.api.servicecontrol.v1.QuotaOperation].

Used in: AllocateQuotaResponse

• QuotaError.Code code = 1

  Error code.

• string subject = 2

  Subject to whom this error applies. See the specific enum for more details on this field. For example, "clientip:<ip address of client>" or "project:<Google developer project id>".

• string description = 3

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

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.

Used in: QuotaError

• UNSPECIFIED = 0

  This is never used.

• RESOURCE_EXHAUSTED = 8

  Quota allocation failed. Same as [google.rpc.Code.RESOURCE_EXHAUSTED][].

• BILLING_NOT_ACTIVE = 107

  Consumer cannot access the service because the service requires active billing.

• PROJECT_DELETED = 108

  Consumer's project has been marked as deleted (soft deletion).

• API_KEY_INVALID = 105

  Specified API key is invalid.

• API_KEY_EXPIRED = 112

  Specified API Key has expired.

Represents information regarding a quota operation.

Used in: AllocateQuotaRequest

• string operation_id = 1

  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.

• string method_name = 2

  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

• string consumer_id = 3

  Identity of the consumer for whom this quota operation is being performed. This can be in one of the following formats: project:<project_id>, project_number:<project_number>, api_key:<api_key>.

• map<string, string> labels = 4

  Labels describing the operation.

• repeated MetricValueSet quota_metrics = 5

  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.

• QuotaOperation.QuotaMode quota_mode = 6

  Quota mode for this operation.

Supported quota modes.

Used in: QuotaOperation

• UNSPECIFIED = 0

  Guard against implicit default. Must not be used.

• NORMAL = 1

  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.

• BEST_EFFORT = 2

  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 = 3

  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.

Represents the processing error of one [Operation][google.api.servicecontrol.v1.Operation] in the request.

Used in: ReportResponse

• string operation_id = 1

  The [Operation.operation_id][google.api.servicecontrol.v1.Operation.operation_id] value from the request.

• optional rpc.Status status = 2

  Details of the error when processing the [Operation][google.api.servicecontrol.v1.Operation].