diff options
Diffstat (limited to 'third_party/googleapis/google/api/quota.proto')
| -rw-r--r-- | third_party/googleapis/google/api/quota.proto | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/third_party/googleapis/google/api/quota.proto b/third_party/googleapis/google/api/quota.proto new file mode 100644 index 0000000000..aa327a1969 --- /dev/null +++ b/third_party/googleapis/google/api/quota.proto @@ -0,0 +1,259 @@ +// 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; + +import "google/api/annotations.proto"; + +option go_package = "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig"; +option java_multiple_files = true; +option java_outer_classname = "QuotaProto"; +option java_package = "com.google.api"; +option objc_class_prefix = "GAPI"; + + +// Quota configuration helps to achieve fairness and budgeting in service +// usage. +// +// The quota configuration works this way: +// - The service configuration defines a set of metrics. +// - For API calls, the quota.metric_rules maps methods to metrics with +// corresponding costs. +// - The quota.limits defines limits on the metrics, which will be used for +// quota checks at runtime. +// +// An example quota configuration in yaml format: +// +// quota: +// limits: +// +// - name: apiWriteQpsPerProject +// metric: library.googleapis.com/write_calls +// unit: "1/min/{project}" # rate limit for consumer projects +// values: +// STANDARD: 10000 +// +// # The metric rules bind all methods to the read_calls metric, +// # except for the UpdateBook and DeleteBook methods. These two methods +// # are mapped to the write_calls metric, with the UpdateBook method +// # consuming at twice rate as the DeleteBook method. +// metric_rules: +// - selector: "*" +// metric_costs: +// library.googleapis.com/read_calls: 1 +// - selector: google.example.library.v1.LibraryService.UpdateBook +// metric_costs: +// library.googleapis.com/write_calls: 2 +// - selector: google.example.library.v1.LibraryService.DeleteBook +// metric_costs: +// library.googleapis.com/write_calls: 1 +// +// Corresponding Metric definition: +// +// metrics: +// - name: library.googleapis.com/read_calls +// display_name: Read requests +// metric_kind: DELTA +// value_type: INT64 +// +// - name: library.googleapis.com/write_calls +// display_name: Write requests +// metric_kind: DELTA +// value_type: INT64 +// +message Quota { + // List of `QuotaLimit` definitions for the service. + // + // Used by metric-based quotas only. + repeated QuotaLimit limits = 3; + + // List of `MetricRule` definitions, each one mapping a selected method to one + // or more metrics. + // + // Used by metric-based quotas only. + repeated MetricRule metric_rules = 4; +} + +// Bind API methods to metrics. Binding a method to a metric causes that +// metric's configured quota, billing, and monitoring behaviors to apply to the +// method call. +// +// Used by metric-based quotas only. +message MetricRule { + // Selects the methods to which this rule applies. + // + // Refer to [selector][google.api.DocumentationRule.selector] for syntax details. + string selector = 1; + + // Metrics to update when the selected methods are called, and the associated + // cost applied to each metric. + // + // The key of the map is the metric name, and the values are the amount + // increased for the metric against which the quota limits are defined. + // The value must not be negative. + map<string, int64> metric_costs = 2; +} + +// `QuotaLimit` defines a specific limit that applies over a specified duration +// for a limit type. There can be at most one limit for a duration and limit +// type combination defined within a `QuotaGroup`. +message QuotaLimit { + // Name of the quota limit. The name is used to refer to the limit when + // overriding the default limit on per-consumer basis. + // + // For group-based quota limits, the name must be unique within the quota + // group. If a name is not provided, it will be generated from the limit_by + // and duration fields. + // + // For metric-based quota limits, the name must be provided, and it must be + // unique within the service. The name can only include alphanumeric + // characters as well as '-'. + // + // The maximum length of the limit name is 64 characters. + // + // The name of a limit is used as a unique identifier for this limit. + // Therefore, once a limit has been put into use, its name should be + // immutable. You can use the display_name field to provide a user-friendly + // name for the limit. The display name can be evolved over time without + // affecting the identity of the limit. + string name = 6; + + // Optional. User-visible, extended description for this quota limit. + // Should be used only when more context is needed to understand this limit + // than provided by the limit's display name (see: `display_name`). + string description = 2; + + // Default number of tokens that can be consumed during the specified + // duration. This is the number of tokens assigned when a client + // application developer activates the service for his/her project. + // + // Specifying a value of 0 will block all requests. This can be used if you + // are provisioning quota to selected consumers and blocking others. + // Similarly, a value of -1 will indicate an unlimited quota. No other + // negative values are allowed. + // + // Used by group-based quotas only. + int64 default_limit = 3; + + // Maximum number of tokens that can be consumed during the specified + // duration. Client application developers can override the default limit up + // to this maximum. If specified, this value cannot be set to a value less + // than the default limit. If not specified, it is set to the default limit. + // + // To allow clients to apply overrides with no upper bound, set this to -1, + // indicating unlimited maximum quota. + // + // Used by group-based quotas only. + int64 max_limit = 4; + + // Free tier value displayed in the Developers Console for this limit. + // The free tier is the number of tokens that will be subtracted from the + // billed amount when billing is enabled. + // This field can only be set on a limit with duration "1d", in a billable + // group; it is invalid on any other limit. If this field is not set, it + // defaults to 0, indicating that there is no free tier for this service. + // + // Used by group-based quotas only. + int64 free_tier = 7; + + // Duration of this limit in textual notation. Example: "100s", "24h", "1d". + // For duration longer than a day, only multiple of days is supported. We + // support only "100s" and "1d" for now. Additional support will be added in + // the future. "0" indicates indefinite duration. + // + // Used by group-based quotas only. + string duration = 5; + + // The name of the metric this quota limit applies to. The quota limits with + // the same metric will be checked together during runtime. The metric must be + // defined within the service config. + // + // Used by metric-based quotas only. + string metric = 8; + + // Specify the unit of the quota limit. It uses the same syntax as + // [Metric.unit][]. The supported unit kinds are determined by the quota + // backend system. + // + // The [Google Service Control](https://cloud.google.com/service-control) + // supports the following unit components: + // * One of the time intevals: + // * "/min" for quota every minute. + // * "/d" for quota every 24 hours, starting 00:00 US Pacific Time. + // * Otherwise the quota won't be reset by time, such as storage limit. + // * One and only one of the granted containers: + // * "/{organization}" quota for an organization. + // * "/{project}" quota for a project. + // * "/{folder}" quota for a folder. + // * "/{resource}" quota for a universal resource. + // * Zero or more quota segmentation dimension. Not all combos are valid. + // * "/{region}" quota for every region. Not to be used with time intervals. + // * Otherwise the resources granted on the target is not segmented. + // * "/{zone}" quota for every zone. Not to be used with time intervals. + // * Otherwise the resources granted on the target is not segmented. + // * "/{resource}" quota for a resource associated with a project or org. + // + // Here are some examples: + // * "1/min/{project}" for quota per minute per project. + // * "1/min/{user}" for quota per minute per user. + // * "1/min/{organization}" for quota per minute per organization. + // + // Note: the order of unit components is insignificant. + // The "1" at the beginning is required to follow the metric unit syntax. + // + // Used by metric-based quotas only. + string unit = 9; + + // Tiered limit values. Also allows for regional or zone overrides for these + // values if "/{region}" or "/{zone}" is specified in the unit field. + // + // Currently supported tiers from low to high: + // VERY_LOW, LOW, STANDARD, HIGH, VERY_HIGH + // + // To apply different limit values for users according to their tiers, specify + // the values for the tiers you want to differentiate. For example: + // {LOW:100, STANDARD:500, HIGH:1000, VERY_HIGH:5000} + // + // The limit value for each tier is optional except for the tier STANDARD. + // The limit value for an unspecified tier falls to the value of its next + // tier towards tier STANDARD. For the above example, the limit value for tier + // STANDARD is 500. + // + // To apply the same limit value for all users, just specify limit value for + // tier STANDARD. For example: {STANDARD:500}. + // + // To apply a regional overide for a tier, add a map entry with key + // "<TIER>/<region>", where <region> is a region name. Similarly, for a zone + // override, add a map entry with key "<TIER>/{zone}". + // Further, a wildcard can be used at the end of a zone name in order to + // specify zone level overrides. For example: + // LOW: 10, STANDARD: 50, HIGH: 100, + // LOW/us-central1: 20, STANDARD/us-central1: 60, HIGH/us-central1: 200, + // LOW/us-central1-*: 10, STANDARD/us-central1-*: 20, HIGH/us-central1-*: 80 + // + // The regional overrides tier set for each region must be the same as + // the tier set for default limit values. Same rule applies for zone overrides + // tier as well. + // + // Used by metric-based quotas only. + map<string, int64> values = 10; + + // User-visible display name for this limit. + // Optional. If not set, the UI will provide a default display name based on + // the quota configuration. This field can be used to override the default + // display name generated from the configuration. + string display_name = 12; +} |