| // 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; |
| } |