--- /dev/null
+// Copyright 2017 Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.api.servicecontrol.v1;
+
+import "google/api/annotations.proto";
+import "google/api/servicecontrol/v1/metric_value.proto";
+
+option cc_enable_arenas = true;
+option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
+option java_multiple_files = true;
+option java_outer_classname = "QuotaControllerProto";
+option java_package = "com.google.api.servicecontrol.v1";
+
+// [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).
+service QuotaController {
+ // 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.
+ rpc AllocateQuota(AllocateQuotaRequest) returns (AllocateQuotaResponse) {
+ option (google.api.http) = {
+ post: "/v1/services/{service_name}:allocateQuota"
+ body: "*"
+ };
+ }
+}
+
+// Request message for the AllocateQuota method.
+message AllocateQuotaRequest {
+ // 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.
+ string service_name = 1;
+
+ // Operation that describes the quota allocation.
+ QuotaOperation allocate_operation = 2;
+
+ // 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.
+ string service_config_id = 4;
+}
+
+// Represents information regarding a quota operation.
+message QuotaOperation {
+ // Supported quota modes.
+ enum QuotaMode {
+ // Guard against implicit default. Must not be used.
+ UNSPECIFIED = 0;
+
+ // 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.
+ NORMAL = 1;
+
+ // 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.
+ BEST_EFFORT = 2;
+
+ // 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.
+ CHECK_ONLY = 3;
+ }
+
+ // 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 operation_id = 1;
+
+ // 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 method_name = 2;
+
+ // 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>.
+ string consumer_id = 3;
+
+ // Labels describing the operation.
+ map<string, string> labels = 4;
+
+ // 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 MetricValueSet quota_metrics = 5;
+
+ // Quota mode for this operation.
+ QuotaMode quota_mode = 6;
+}
+
+// Response message for the AllocateQuota method.
+message AllocateQuotaResponse {
+ // The same operation_id value used in the AllocateQuotaRequest. Used for
+ // logging and diagnostics purposes.
+ string operation_id = 1;
+
+ // Indicates the decision of the allocate.
+ repeated QuotaError allocate_errors = 2;
+
+ // 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"
+ repeated MetricValueSet quota_metrics = 3;
+
+ // ID of the actual config used to process the request.
+ string service_config_id = 4;
+}
+
+// Represents error information for
+// [QuotaOperation][google.api.servicecontrol.v1.QuotaOperation].
+message QuotaError {
+ // 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.
+ enum Code {
+ // This is never used.
+ UNSPECIFIED = 0;
+
+ // Quota allocation failed.
+ // Same as [google.rpc.Code.RESOURCE_EXHAUSTED][].
+ RESOURCE_EXHAUSTED = 8;
+
+ // Consumer cannot access the service because the service requires active
+ // billing.
+ BILLING_NOT_ACTIVE = 107;
+
+ // Consumer's project has been marked as deleted (soft deletion).
+ PROJECT_DELETED = 108;
+
+ // Specified API key is invalid.
+ API_KEY_INVALID = 105;
+
+ // Specified API Key has expired.
+ API_KEY_EXPIRED = 112;
+ }
+
+ // Error code.
+ Code code = 1;
+
+ // 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 subject = 2;
+
+ // Free-form text that provides details on the cause of the error.
+ string description = 3;
+}