payne8/masonry
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix templates

Browse Source
This commit is contained in:
Mason Payne
2025-02-22 22:21:51 -07:00
parent 9fe376d3ea
commit 60d7e07114
99 changed files with 31 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
cmd/cli/proto_include/google/api/servicecontrol/BUILD.bazel Normal file
View File

126
cmd/cli/proto_include/google/api/servicecontrol/README.md Normal file
View File

@ -0,0 +1,126 @@
Google Service Control provides control plane functionality to managed services,
such as logging, monitoring, and status checks. This page provides an overview
of what it does and how it works.
## Why use Service Control?
When you develop a cloud service, you typically start with the business
requirements and the architecture design, then proceed with API definition
and implementation. Before you put your service into production, you
need to deal with many control plane issues:
* How to control access to your service.
* How to send logging and monitoring data to both consumers and producers.
* How to create and manage dashboards to visualize this data.
* How to automatically scale the control plane components with your service.
Service Control is a mature and feature-rich control plane provider
that addresses these needs with high efficiency, high scalability,
and high availability. It provides a simple public API that can be accessed
from anywhere using JSON REST and gRPC clients, so when you move your service
from on-premise to a cloud provider, or from one cloud provider to another,
you don't need to change the control plane provider.
Services built using Google Cloud Endpoints already take advantage of
Service Control. Cloud Endpoints sends logging and monitoring data
through Google Service Control for every request arriving at its
proxy. If you need to report any additional logging and monitoring data for
your Cloud Endpoints service, you can call the Service Control API directly
from your service.
The Service Control API definition is open sourced and available on
[GitHub](https://github.com/googleapis/googleapis/tree/master/google/api/servicecontrol).
By changing the DNS name, you can easily use alternative implementations of
the Service Control API.
## Architecture
Google Service Control works with a set of *managed services* and their
*operations* (activities), *checks* whether an operation is allowed to proceed,
and *reports* completed operations. Behind the scenes, it leverages other
Google Cloud services, such as
[Google Service Management](/service-management),
[Stackdriver Logging](/logging), and [Stackdriver Monitoring](/monitoring),
while hiding their complexity from service producers. It enables service
producers to send telemetry data to their consumers. It uses caching,
batching, aggregation, and retries to deliver higher performance and
availability than the individual backend systems it encapsulates.
<figure id="fig-arch" class="center">
<div style="width: 70%;margin: auto">
<img src="/service-control/images/arch.svg"
alt="The overall architecture of a service that uses Google Service Control.">
</div>
<figcaption><b>Figure 1</b>: Using Google Service Control.</figcaption>
</figure>
The Service Control API provides two methods:
* [`services.check`](/service-control/reference/rest/v1/services/check), used for:
* Ensuring valid consumer status
* Validating API keys
* [`services.report`](/service-control/reference/rest/v1/services/report), used for:
* Sending logs to Stackdriver Logging
* Sending metrics to Stackdriver Monitoring
We’ll look at these in more detail in the rest of this overview.
## Managed services
A [managed service](/service-management/reference/rest/v1/services) is
a network service managed by
[Google Service Management](/service-management). Each managed service has a
unique name, such as `example.googleapis.com`, which must be a valid
fully-qualified DNS name, as per RFC 1035.
For example:
* Google Cloud Pub/Sub (`pubsub.googleapis.com`)
* Google Cloud Vision (`vision.googleapis.com`)
* Google Cloud Bigtable (`bigtable.googleapis.com`)
* Google Cloud Datastore (`datastore.googleapis.com`)
Google Service Management manages the lifecycle of each service’s
configuration, which is used to customize Google Service Control's behavior.
Service configurations are also used by Google Cloud Console
for displaying APIs and their settings, enabling/disabling APIs, and more.
## Operations
Google Service Control uses the generic concept of an *operation*
to represent the
activities of a managed service, such as API calls and resource usage. Each
operation is associated with a managed service and a specific service
consumer, and has a set of properties that describe the operation, such as
the API method name and resource usage amount. For more information, see the
[Operation definition](/service-control/rest/v1/Operation).
## Check
The [`services.check`](/service-control/reference/rest/v1/services/check)
method determines whether an operation should be allowed to proceed
for a managed service.
For example:
* Check if the consumer is still active.
* Check if the consumer has enabled the service.
* Check if the API key is still valid.
By performing multiple checks within a single method call, it provides
better performance, higher reliability, and reduced development cost to
service producers compared to checking with multiple backend systems.
## Report
The [`services.report`](/service-control/reference/rest/v1/services/report)
method reports completed operations for
a managed service to backend systems, such as logging and monitoring. The
reported data can be seen in Google API Console and Google Cloud Console,
and retrieved with appropriate APIs, such as the Stackdriver Logging and
Stackdriver Monitoring APIs.
## Next steps
* Read our [Getting Started guide](/service-control/getting-started) to find out
how to set up and use the Google Service Control API.

362
cmd/cli/proto_include/google/api/servicecontrol/v1/BUILD.bazel Normal file
View File

@ -0,0 +1,362 @@
# This file was automatically generated by BuildFileGenerator
# https://github.com/googleapis/rules_gapic/tree/master/bazel
# Most of the manual changes to this file will be overwritten.
# It's **only** allowed to change the following rule attribute values:
# - names of *_gapic_assembly_* rules
# - certain parameters of *_gapic_library rules, including but not limited to:
# * extra_protoc_parameters
# * extra_protoc_file_parameters
# The complete list of preserved parameters can be found in the source code.
# This is an API workspace, having public visibility by default makes perfect sense.
package(default_visibility = ["//visibility:public"])
##############################################################################
# Common
##############################################################################
load("@rules_proto//proto:defs.bzl", "proto_library")
load("@com_google_googleapis_imports//:imports.bzl", "proto_library_with_info")
proto_library(
name = "servicecontrol_proto",
srcs = [
"check_error.proto",
"distribution.proto",
"http_request.proto",
"log_entry.proto",
"metric_value.proto",
"operation.proto",
"quota_controller.proto",
"service_controller.proto",
],
deps = [
"//google/api:annotations_proto",
"//google/api:client_proto",
"//google/api:distribution_proto",
"//google/logging/type:type_proto",
"//google/rpc:status_proto",
"@com_google_protobuf//:any_proto",
"@com_google_protobuf//:duration_proto",
"@com_google_protobuf//:struct_proto",
"@com_google_protobuf//:timestamp_proto",
],
)
proto_library_with_info(
name = "servicecontrol_proto_with_info",
deps = [
":servicecontrol_proto",
"//google/cloud:common_resources_proto",
],
)
##############################################################################
# Java
##############################################################################
load(
"@com_google_googleapis_imports//:imports.bzl",
"java_gapic_assembly_gradle_pkg",
"java_gapic_library",
"java_gapic_test",
"java_grpc_library",
"java_proto_library",
)
java_proto_library(
name = "servicecontrol_java_proto",
deps = [":servicecontrol_proto"],
)
java_grpc_library(
name = "servicecontrol_java_grpc",
srcs = [":servicecontrol_proto"],
deps = [":servicecontrol_java_proto"],
)
java_gapic_library(
name = "servicecontrol_java_gapic",
srcs = [":servicecontrol_proto_with_info"],
grpc_service_config = "servicecontrol_grpc_service_config.json",
test_deps = [
":servicecontrol_java_grpc",
],
deps = [
":servicecontrol_java_proto",
],
)
java_gapic_test(
name = "servicecontrol_java_gapic_test_suite",
test_classes = [
"com.google.api.servicecontrol.v1.QuotaControllerClientTest",
"com.google.api.servicecontrol.v1.ServiceControllerClientTest",
],
runtime_deps = [":servicecontrol_java_gapic_test"],
)
# Open Source Packages
java_gapic_assembly_gradle_pkg(
name = "google-cloud-api-servicecontrol-v1-java",
deps = [
":servicecontrol_java_gapic",
":servicecontrol_java_grpc",
":servicecontrol_java_proto",
":servicecontrol_proto",
],
)
##############################################################################
# Go
##############################################################################
load(
"@com_google_googleapis_imports//:imports.bzl",
"go_gapic_assembly_pkg",
"go_gapic_library",
"go_proto_library",
"go_test",
)
go_proto_library(
name = "servicecontrol_go_proto",
compilers = ["@io_bazel_rules_go//proto:go_grpc"],
importpath = "google.golang.org/genproto/googleapis/api/servicecontrol/v1",
protos = [":servicecontrol_proto"],
deps = [
"//google/api:annotations_go_proto",
"//google/api:distribution_go_proto",
"//google/logging/type:type_go_proto",
"//google/rpc:status_go_proto",
],
)
go_gapic_library(
name = "servicecontrol_go_gapic",
srcs = [":servicecontrol_proto_with_info"],
grpc_service_config = "servicecontrol_grpc_service_config.json",
importpath = "cloud.google.com/go/api/servicecontrol/apiv1;servicecontrol",
metadata = True,
service_yaml = "servicecontrol.yaml",
deps = [
":servicecontrol_go_proto",
"@io_bazel_rules_go//proto/wkt:duration_go_proto",
],
)
go_test(
name = "servicecontrol_go_gapic_test",
srcs = [":servicecontrol_go_gapic_srcjar_test"],
embed = [":servicecontrol_go_gapic"],
importpath = "cloud.google.com/go/api/servicecontrol/apiv1",
)
# Open Source Packages
go_gapic_assembly_pkg(
name = "gapi-cloud-api-servicecontrol-v1-go",
deps = [
":servicecontrol_go_gapic",
":servicecontrol_go_gapic_srcjar-metadata.srcjar",
":servicecontrol_go_gapic_srcjar-test.srcjar",
":servicecontrol_go_proto",
],
)
##############################################################################
# Python
##############################################################################
load(
"@com_google_googleapis_imports//:imports.bzl",
"py_gapic_assembly_pkg",
"py_gapic_library",
)
py_gapic_library(
name = "servicecontrol_py_gapic",
srcs = [":servicecontrol_proto"],
grpc_service_config = "servicecontrol_grpc_service_config.json",
opt_args = [
"python-gapic-name=servicecontrol",
"python-gapic-namespace=google.cloud",
"warehouse-package-name=google-cloud-service-control",
],
)
# Open Source Packages
py_gapic_assembly_pkg(
name = "google-cloud-servicecontrol-v1-py",
deps = [
":servicecontrol_py_gapic",
],
)
##############################################################################
# PHP
##############################################################################
load(
"@com_google_googleapis_imports//:imports.bzl",
"php_gapic_assembly_pkg",
"php_gapic_library",
"php_grpc_library",
"php_proto_library",
)
php_proto_library(
name = "servicecontrol_php_proto",
deps = [":servicecontrol_proto"],
)
php_grpc_library(
name = "servicecontrol_php_grpc",
srcs = [":servicecontrol_proto"],
deps = [":servicecontrol_php_proto"],
)
php_gapic_library(
name = "servicecontrol_php_gapic",
srcs = [":servicecontrol_proto_with_info"],
grpc_service_config = "servicecontrol_grpc_service_config.json",
service_yaml = "servicecontrol.yaml",
deps = [
":servicecontrol_php_grpc",
":servicecontrol_php_proto",
],
)
# Open Source Packages
php_gapic_assembly_pkg(
name = "google-cloud-api-servicecontrol-v1-php",
deps = [
":servicecontrol_php_gapic",
":servicecontrol_php_grpc",
":servicecontrol_php_proto",
],
)
##############################################################################
# Node.js
##############################################################################
load(
"@com_google_googleapis_imports//:imports.bzl",
"nodejs_gapic_assembly_pkg",
"nodejs_gapic_library",
)
nodejs_gapic_library(
name = "servicecontrol_nodejs_gapic",
package_name = "@google-cloud/service-control",
src = ":servicecontrol_proto_with_info",
extra_protoc_parameters = ["metadata"],
grpc_service_config = "servicecontrol_grpc_service_config.json",
package = "google.api.servicecontrol.v1",
service_yaml = "servicecontrol.yaml",
deps = [],
)
nodejs_gapic_assembly_pkg(
name = "api-servicecontrol-v1-nodejs",
deps = [
":servicecontrol_nodejs_gapic",
":servicecontrol_proto",
## DO NOT CHANGE: Owlbot add dependency logging type protos.
"//google/logging/type:type_proto",
],
)
##############################################################################
# Ruby
##############################################################################
load(
"@com_google_googleapis_imports//:imports.bzl",
"ruby_cloud_gapic_library",
"ruby_gapic_assembly_pkg",
"ruby_grpc_library",
"ruby_proto_library",
)
ruby_proto_library(
name = "servicecontrol_ruby_proto",
deps = [":servicecontrol_proto"],
)
ruby_grpc_library(
name = "servicecontrol_ruby_grpc",
srcs = [":servicecontrol_proto"],
deps = [":servicecontrol_ruby_proto"],
)
ruby_cloud_gapic_library(
name = "servicecontrol_ruby_gapic",
srcs = [":servicecontrol_proto_with_info"],
extra_protoc_parameters = [
"ruby-cloud-api-id=servicecontrol.googleapis.com",
"ruby-cloud-api-shortname=servicecontrol",
"ruby-cloud-env-prefix=SERVICE_CONTROL",
"ruby-cloud-gem-name=google-cloud-service_control-v1",
"ruby-cloud-product-url=https://cloud.google.com/service-infrastructure/docs/overview/",
],
grpc_service_config = "servicecontrol_grpc_service_config.json",
ruby_cloud_description = "The Service Control API provides control plane functionality to managed services, such as logging, monitoring, and status checks.",
ruby_cloud_title = "Service Control API V1",
deps = [
":servicecontrol_ruby_grpc",
":servicecontrol_ruby_proto",
],
)
# Open Source Packages
ruby_gapic_assembly_pkg(
name = "google-cloud-api-servicecontrol-v1-ruby",
deps = [
":servicecontrol_ruby_gapic",
":servicecontrol_ruby_grpc",
":servicecontrol_ruby_proto",
],
)
##############################################################################
# C#
##############################################################################
load(
"@com_google_googleapis_imports//:imports.bzl",
"csharp_gapic_assembly_pkg",
"csharp_gapic_library",
"csharp_grpc_library",
"csharp_proto_library",
)
csharp_proto_library(
name = "servicecontrol_csharp_proto",
deps = [":servicecontrol_proto"],
)
csharp_grpc_library(
name = "servicecontrol_csharp_grpc",
srcs = [":servicecontrol_proto"],
deps = [":servicecontrol_csharp_proto"],
)
csharp_gapic_library(
name = "servicecontrol_csharp_gapic",
srcs = [":servicecontrol_proto_with_info"],
common_resources_config = "@gax_dotnet//:Google.Api.Gax/ResourceNames/CommonResourcesConfig.json",
grpc_service_config = "servicecontrol_grpc_service_config.json",
deps = [
":servicecontrol_csharp_grpc",
":servicecontrol_csharp_proto",
],
)
# Open Source Packages
csharp_gapic_assembly_pkg(
name = "google-cloud-api-servicecontrol-v1-csharp",
deps = [
":servicecontrol_csharp_gapic",
":servicecontrol_csharp_grpc",
":servicecontrol_csharp_proto",
],
)
##############################################################################
# C++
##############################################################################
# Put your C++ rules here

124
cmd/cli/proto_include/google/api/servicecontrol/v1/check_error.proto Normal file
View File

@ -0,0 +1,124 @@
// Copyright 2021 Google LLC
//
// 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/rpc/status.proto";
option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.ServiceControl.V1";
option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
option java_multiple_files = true;
option java_outer_classname = "CheckErrorProto";
option java_package = "com.google.api.servicecontrol.v1";
option php_namespace = "Google\\Cloud\\ServiceControl\\V1";
option ruby_package = "Google::Cloud::ServiceControl::V1";
// Defines the errors to be returned in
// [google.api.servicecontrol.v1.CheckResponse.check_errors][google.api.servicecontrol.v1.CheckResponse.check_errors].
message CheckError {
// Error codes for Check responses.
enum Code {
// This is never used in `CheckResponse`.
ERROR_CODE_UNSPECIFIED = 0;
// The consumer's project id, network container, or resource container was
// not found. Same as [google.rpc.Code.NOT_FOUND][google.rpc.Code.NOT_FOUND].
NOT_FOUND = 5;
// The consumer doesn't have access to the specified resource.
// Same as [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED].
PERMISSION_DENIED = 7;
// Quota check failed. Same as [google.rpc.Code.RESOURCE_EXHAUSTED][google.rpc.Code.RESOURCE_EXHAUSTED].
RESOURCE_EXHAUSTED = 8;
// The consumer hasn't activated the service.
SERVICE_NOT_ACTIVATED = 104;
// The consumer cannot access the service because billing is disabled.
BILLING_DISABLED = 107;
// The consumer's project has been marked as deleted (soft deletion).
PROJECT_DELETED = 108;
// The consumer's project number or id does not represent a valid project.
PROJECT_INVALID = 114;
// The input consumer info does not represent a valid consumer folder or
// organization.
CONSUMER_INVALID = 125;
// The IP address of the consumer is invalid for the specific consumer
// project.
IP_ADDRESS_BLOCKED = 109;
// The referer address of the consumer request is invalid for the specific
// consumer project.
REFERER_BLOCKED = 110;
// The client application of the consumer request is invalid for the
// specific consumer project.
CLIENT_APP_BLOCKED = 111;
// The API targeted by this request is invalid for the specified consumer
// project.
API_TARGET_BLOCKED = 122;
// The consumer's API key is invalid.
API_KEY_INVALID = 105;
// The consumer's API Key has expired.
API_KEY_EXPIRED = 112;
// The consumer's API Key was not found in config record.
API_KEY_NOT_FOUND = 113;
// The credential in the request can not be verified.
INVALID_CREDENTIAL = 123;
// The backend server for looking up project id/number is unavailable.
NAMESPACE_LOOKUP_UNAVAILABLE = 300;
// The backend server for checking service status is unavailable.
SERVICE_STATUS_UNAVAILABLE = 301;
// The backend server for checking billing status is unavailable.
BILLING_STATUS_UNAVAILABLE = 302;
// Cloud Resource Manager backend server is unavailable.
CLOUD_RESOURCE_MANAGER_BACKEND_UNAVAILABLE = 305;
}
// The error code.
Code code = 1;
// Subject to whom this error applies. See the specific code enum for more
// details on this field. For example:
//
// - "project:<project-id or project-number>"
// - "folder:<folder-id>"
// - "organization:<organization-id>"
string subject = 4;
// Free-form text providing details on the error cause of the error.
string detail = 2;
// Contains public information about the check error. If available,
// `status.code` will be non zero and client can propagate it out as public
// error.
google.rpc.Status status = 3;
}

166
cmd/cli/proto_include/google/api/servicecontrol/v1/distribution.proto Normal file
View File

@ -0,0 +1,166 @@
// Copyright 2021 Google LLC
//
// 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/distribution.proto";
option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.ServiceControl.V1";
option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
option java_multiple_files = true;
option java_outer_classname = "DistributionProto";
option java_package = "com.google.api.servicecontrol.v1";
option php_namespace = "Google\\Cloud\\ServiceControl\\V1";
option ruby_package = "Google::Cloud::ServiceControl::V1";
// 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
message Distribution {
// Describing buckets with constant width.
message LinearBuckets {
// 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.
int32 num_finite_buckets = 1;
// 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 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.
double offset = 3;
}
// Describing buckets with exponentially growing width.
message ExponentialBuckets {
// 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.
int32 num_finite_buckets = 1;
// 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 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 > 0.
double scale = 3;
}
// Describing buckets with arbitrary user-provided width.
message ExplicitBuckets {
// '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
repeated double bounds = 1;
}
// The total number of samples in the distribution. Must be >= 0.
int64 count = 1;
// The arithmetic mean of the samples in the distribution. If `count` is
// zero then this field must be zero.
double mean = 2;
// The minimum of the population of values. Ignored if `count` is zero.
double minimum = 3;
// The maximum of the population of values. Ignored if `count` is zero.
double maximum = 4;
// 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.
double sum_of_squared_deviation = 5;
// 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.
repeated int64 bucket_counts = 6;
// 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.
oneof bucket_option {
// Buckets with constant width.
LinearBuckets linear_buckets = 7;
// Buckets with exponentially growing width.
ExponentialBuckets exponential_buckets = 8;
// Buckets with arbitrary user-provided width.
ExplicitBuckets explicit_buckets = 9;
}
// Example points. Must be in increasing order of `value` field.
repeated google.api.Distribution.Exemplar exemplars = 10;
}

93
cmd/cli/proto_include/google/api/servicecontrol/v1/http_request.proto Normal file
View File

@ -0,0 +1,93 @@
// Copyright 2021 Google LLC
//
// 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/protobuf/duration.proto";
option csharp_namespace = "Google.Cloud.ServiceControl.V1";
option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
option java_multiple_files = true;
option java_outer_classname = "HttpRequestProto";
option java_package = "com.google.api.servicecontrol.v1";
option php_namespace = "Google\\Cloud\\ServiceControl\\V1";
option ruby_package = "Google::Cloud::ServiceControl::V1";
// A common proto for logging HTTP requests. Only contains semantics
// defined by the HTTP specification. Product-specific logging
// information MUST be defined in a separate message.
message HttpRequest {
// The request method. Examples: `"GET"`, `"HEAD"`, `"PUT"`, `"POST"`.
string request_method = 1;
// The scheme (http, https), the host name, the path, and the query
// portion of the URL that was requested.
// Example: `"http://example.com/some/info?color=red"`.
string request_url = 2;
// The size of the HTTP request message in bytes, including the request
// headers and the request body.
int64 request_size = 3;
// The response code indicating the status of the response.
// Examples: 200, 404.
int32 status = 4;
// The size of the HTTP response message sent back to the client, in bytes,
// including the response headers and the response body.
int64 response_size = 5;
// The user agent sent by the client. Example:
// `"Mozilla/4.0 (compatible; MSIE 6.0; Windows 98; Q312461; .NET
// CLR 1.0.3705)"`.
string user_agent = 6;
// The IP address (IPv4 or IPv6) of the client that issued the HTTP
// request. Examples: `"192.168.1.1"`, `"FE80::0202:B3FF:FE1E:8329"`.
string remote_ip = 7;
// The IP address (IPv4 or IPv6) of the origin server that the request was
// sent to.
string server_ip = 13;
// The referer URL of the request, as defined in
// [HTTP/1.1 Header Field
// Definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).
string referer = 8;
// The request processing latency on the server, from the time the request was
// received until the response was sent.
google.protobuf.Duration latency = 14;
// Whether or not a cache lookup was attempted.
bool cache_lookup = 11;
// Whether or not an entity was served from cache
// (with or without validation).
bool cache_hit = 9;
// Whether or not the response was validated with the origin server before
// being served from cache. This field is only meaningful if `cache_hit` is
// True.
bool cache_validated_with_origin_server = 10;
// The number of HTTP response bytes inserted into cache. Set only when a
// cache fill was attempted.
int64 cache_fill_bytes = 12;
// Protocol used for the request. Examples: "HTTP/1.1", "HTTP/2", "websocket"
string protocol = 15;
}

126
cmd/cli/proto_include/google/api/servicecontrol/v1/log_entry.proto Normal file
View File

@ -0,0 +1,126 @@
// Copyright 2021 Google LLC
//
// 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/servicecontrol/v1/http_request.proto";
import "google/logging/type/log_severity.proto";
import "google/protobuf/any.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
option csharp_namespace = "Google.Cloud.ServiceControl.V1";
option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
option java_multiple_files = true;
option java_outer_classname = "LogEntryProto";
option java_package = "com.google.api.servicecontrol.v1";
option php_namespace = "Google\\Cloud\\ServiceControl\\V1";
option ruby_package = "Google::Cloud::ServiceControl::V1";
// An individual log entry.
message LogEntry {
// Required. The log to which this log entry belongs. Examples: `"syslog"`,
// `"book_log"`.
string name = 10;
// The time the event described by the log entry occurred. If
// omitted, defaults to operation start time.
google.protobuf.Timestamp timestamp = 11;
// The severity of the log entry. The default value is
// `LogSeverity.DEFAULT`.
google.logging.type.LogSeverity severity = 12;
// Optional. Information about the HTTP request associated with this
// log entry, if applicable.
HttpRequest http_request = 14;
// Optional. Resource name of the trace associated with the log entry, if any.
// If this field contains a relative resource name, you can assume the name is
// relative to `//tracing.googleapis.com`. Example:
// `projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824`
string trace = 15;
// A unique ID for the log entry used for deduplication. If omitted,
// the implementation will generate one based on operation_id.
string insert_id = 4;
// A set of user-defined (key, value) data that provides additional
// information about the log entry.
map<string, string> labels = 13;
// The log entry payload, which can be one of multiple types.
oneof payload {
// 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].
google.protobuf.Any proto_payload = 2;
// The log entry payload, represented as a Unicode string (UTF-8).
string text_payload = 3;
// The log entry payload, represented as a structure that
// is expressed as a JSON object.
google.protobuf.Struct struct_payload = 6;
}
// Optional. Information about an operation associated with the log entry, if
// applicable.
LogEntryOperation operation = 16;
// Optional. Source code location information associated with the log entry,
// if any.
LogEntrySourceLocation source_location = 17;
}
// Additional information about a potentially long-running operation with which
// a log entry is associated.
message LogEntryOperation {
// Optional. An arbitrary operation identifier. Log entries with the
// same identifier are assumed to be part of the same operation.
string id = 1;
// Optional. An arbitrary producer identifier. The combination of
// `id` and `producer` must be globally unique. Examples for `producer`:
// `"MyDivision.MyBigCompany.com"`, `"github.com/MyProject/MyApplication"`.
string producer = 2;
// Optional. Set this to True if this is the first log entry in the operation.
bool first = 3;
// Optional. Set this to True if this is the last log entry in the operation.
bool last = 4;
}
// Additional information about the source code location that produced the log
// entry.
message LogEntrySourceLocation {
// Optional. Source file name. Depending on the runtime environment, this
// might be a simple name or a fully-qualified name.
string file = 1;
// Optional. Line within the source file. 1-based; 0 indicates no line number
// available.
int64 line = 2;
// Optional. Human-readable name of the function or method being invoked, with
// optional context such as the class or package name. This information may be
// used in contexts such as the logs viewer, where a file and line number are
// less meaningful. The format can vary by language. For example:
// `qual.if.ied.Class.method` (Java), `dir/package.func` (Go), `function`
// (Python).
string function = 3;
}

81
cmd/cli/proto_include/google/api/servicecontrol/v1/metric_value.proto Normal file
View File

@ -0,0 +1,81 @@
// Copyright 2021 Google LLC
//
// 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/servicecontrol/v1/distribution.proto";
import "google/protobuf/timestamp.proto";
option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.ServiceControl.V1";
option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
option java_multiple_files = true;
option java_outer_classname = "MetricValueSetProto";
option java_package = "com.google.api.servicecontrol.v1";
option php_namespace = "Google\\Cloud\\ServiceControl\\V1";
option ruby_package = "Google::Cloud::ServiceControl::V1";
// Represents a single metric value.
message MetricValue {
// 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.
// Note that this map must not contain monitored resource labels.
map<string, string> labels = 1;
// 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. If not specified,
// [google.api.servicecontrol.v1.Operation.start_time][google.api.servicecontrol.v1.Operation.start_time] will be used.
google.protobuf.Timestamp start_time = 2;
// The end of the time period over which this metric value's measurement
// applies. If not specified,
// [google.api.servicecontrol.v1.Operation.end_time][google.api.servicecontrol.v1.Operation.end_time] will be used.
google.protobuf.Timestamp end_time = 3;
// 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.
oneof value {
// A boolean value.
bool bool_value = 4;
// A signed 64-bit integer value.
int64 int64_value = 5;
// A double precision floating point value.
double double_value = 6;
// A text string value.
string string_value = 7;
// A distribution value.
Distribution distribution_value = 8;
}
}
// 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.
message MetricValueSet {
// The metric name defined in the service configuration.
string metric_name = 1;
// The values in this metric.
repeated MetricValue metric_values = 2;
}

123
cmd/cli/proto_include/google/api/servicecontrol/v1/operation.proto Normal file
View File

@ -0,0 +1,123 @@
// Copyright 2021 Google LLC
//
// 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/servicecontrol/v1/log_entry.proto";
import "google/api/servicecontrol/v1/metric_value.proto";
import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";
option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.ServiceControl.V1";
option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
option java_multiple_files = true;
option java_outer_classname = "OperationProto";
option java_package = "com.google.api.servicecontrol.v1";
option php_namespace = "Google\\Cloud\\ServiceControl\\V1";
option ruby_package = "Google::Cloud::ServiceControl::V1";
// Represents information regarding an operation.
message Operation {
// Defines the importance of the data contained in the operation.
enum Importance {
// Allows data caching, batching, and aggregation. It provides
// higher performance with higher data loss risk.
LOW = 0;
// Disables data aggregation to minimize data loss. It is for operations
// that contains significant monetary value or audit trail. This feature
// only applies to the client libraries.
HIGH = 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_id = 1;
// Fully qualified name of the operation. Reserved for future use.
string operation_name = 2;
// 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,
// - projects/PROJECT_ID or PROJECT_NUMBER,
// - folders/FOLDER_NUMBER,
// - organizations/ORGANIZATION_NUMBER,
// - api`_`key:API_KEY.
string consumer_id = 3;
// Required. Start time of the operation.
google.protobuf.Timestamp start_time = 4;
// 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].
google.protobuf.Timestamp end_time = 5;
// 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, such as App Engine, Compute Engine, or
// Kubernetes Engine.
map<string, string> labels = 6;
// 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 metric_value_sets = 7;
// Represents information to be logged.
repeated LogEntry log_entries = 8;
// DO NOT USE. This is an experimental field.
Importance importance = 11;
// Unimplemented.
repeated google.protobuf.Any extensions = 16;
}

245
cmd/cli/proto_include/google/api/servicecontrol/v1/quota_controller.proto Normal file
View File

@ -0,0 +1,245 @@
// Copyright 2021 Google LLC
//
// 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";
import "google/rpc/status.proto";
import "google/api/client.proto";
option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.ServiceControl.V1";
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";
option php_namespace = "Google\\Cloud\\ServiceControl\\V1";
option ruby_package = "Google::Cloud::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 {
option (google.api.default_host) = "servicecontrol.googleapis.com";
option (google.api.oauth_scopes) =
"https://www.googleapis.com/auth/cloud-platform,"
"https://www.googleapis.com/auth/servicecontrol";
// 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.
// If multiple quotas are part of the request, and one fails, none of the
// quotas are allocated or released.
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.
// For rate quota, BEST_EFFORT will continue to deduct from other groups
// even if one does not have enough quota. For allocation, it will find the
// minimum available amount across all groups and deduct that amount from
// all the affected groups.
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;
// Unimplemented. When used in AllocateQuotaRequest, this returns the
// effective quota limit(s) in the response, and no quota check will be
// performed. Not supported for other requests, and even for
// AllocateQuotaRequest, this is currently supported only for allowlisted
// services.
QUERY_ONLY = 4;
// The operation allocates quota for the amount specified in the service
// configuration or specified using the quota metrics. If the requested
// amount is higher than the available quota, request does not fail and
// remaining quota would become negative (going over the limit).
// Not supported for Rate Quota.
ADJUST_ONLY = 5;
}
// 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.
//
// In order to ensure best performance and latency in the Quota backends,
// operation_ids are optimally associated with time, so that related
// operations can be accessed fast in storage. For this reason, the
// recommended token for services that intend to operate at a high QPS is
// Unix time in nanos + UUID
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 should not be set if any of the following is true:
// (1) the quota operation is performed on non-API resources.
// (2) quota_metrics is set because the caller is doing quota override.
//
//
// 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.
//
// This field is mutually exclusive with method_name.
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][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;
// Contains additional information about the quota error.
// If available, `status.code` will be non zero.
google.rpc.Status status = 4;
}

256
cmd/cli/proto_include/google/api/servicecontrol/v1/service_controller.proto Normal file
View File

@ -0,0 +1,256 @@
// Copyright 2021 Google LLC
//
// 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/client.proto";
import "google/api/servicecontrol/v1/check_error.proto";
import "google/api/servicecontrol/v1/operation.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";
option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.ServiceControl.V1";
option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
option java_multiple_files = true;
option java_outer_classname = "ServiceControllerProto";
option java_package = "com.google.api.servicecontrol.v1";
option objc_class_prefix = "GASC";
option php_namespace = "Google\\Cloud\\ServiceControl\\V1";
option ruby_package = "Google::Cloud::ServiceControl::V1";
// [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).
service ServiceController {
option (google.api.default_host) = "servicecontrol.googleapis.com";
option (google.api.oauth_scopes) =
"https://www.googleapis.com/auth/cloud-platform,"
"https://www.googleapis.com/auth/servicecontrol";
// Checks whether an operation on a service should be allowed to proceed
// based on the configuration of the service and related policies. It must 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 any server errors, the client should rely on the
// cached results for much longer time to avoid outage.
// WARNING: There is general 60s delay for the configuration and policy
// propagation, therefore callers MUST NOT depend on the `Check` method having
// the latest policy information.
//
// NOTE: the [CheckRequest][google.api.servicecontrol.v1.CheckRequest] has
// the size limit (wire-format byte size) of 1MB.
//
// This method requires the `servicemanagement.services.check` permission
// on the specified service. For more information, see
// [Cloud IAM](https://cloud.google.com/iam).
rpc Check(CheckRequest) returns (CheckResponse) {
option (google.api.http) = {
post: "/v1/services/{service_name}:check"
body: "*"
};
}
// 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 (wire-format byte size) 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).
rpc Report(ReportRequest) returns (ReportResponse) {
option (google.api.http) = {
post: "/v1/services/{service_name}:report"
body: "*"
};
}
}
// Request message for the Check method.
message CheckRequest {
// 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.
string service_name = 1;
// The operation to be checked.
Operation 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;
}
// Response message for the Check method.
message CheckResponse {
// Contains additional information about the check operation.
message CheckInfo {
// A list of fields and label keys that are ignored by the server.
// The client doesn't need to send them for following requests to improve
// performance and allow better aggregation.
repeated string unused_arguments = 1;
// Consumer info of this check.
ConsumerInfo consumer_info = 2;
}
// `ConsumerInfo` provides information about the consumer.
message ConsumerInfo {
// The type of the consumer as defined in
// [Google Resource Manager](https://cloud.google.com/resource-manager/).
enum ConsumerType {
// This is never used.
CONSUMER_TYPE_UNSPECIFIED = 0;
// The consumer is a Google Cloud Project.
PROJECT = 1;
// The consumer is a Google Cloud Folder.
FOLDER = 2;
// The consumer is a Google Cloud Organization.
ORGANIZATION = 3;
// Service-specific resource container which is defined by the service
// producer to offer their users the ability to manage service control
// functionalities at a finer level of granularity than the PROJECT.
SERVICE_SPECIFIC = 4;
}
// The Google cloud project number, e.g. 1234567890. A value of 0 indicates
// no project number is found.
//
// NOTE: This field is deprecated after we support flexible consumer
// id. New code should not depend on this field anymore.
int64 project_number = 1;
// The type of the consumer which should have been defined in
// [Google Resource Manager](https://cloud.google.com/resource-manager/).
ConsumerType type = 2;
// The consumer identity number, can be Google cloud project number, folder
// number or organization number e.g. 1234567890. A value of 0 indicates no
// consumer number is found.
int64 consumer_number = 3;
}
// The same operation_id value used in the
// [CheckRequest][google.api.servicecontrol.v1.CheckRequest]. Used for logging
// and diagnostics purposes.
string operation_id = 1;
// 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.
repeated CheckError check_errors = 2;
// The actual config id used to process the request.
string service_config_id = 5;
// The current service rollout id used to process the request.
string service_rollout_id = 11;
// Feedback data returned from the server during processing a Check request.
CheckInfo check_info = 6;
}
// Request message for the Report method.
message ReportRequest {
// 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.
string service_name = 1;
// 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.
//
// There is no limit on the number of operations in the same ReportRequest,
// however the ReportRequest size should be no larger than 1MB. See
// [ReportResponse.report_errors][google.api.servicecontrol.v1.ReportResponse.report_errors]
// for partial failure behavior.
repeated Operation operations = 2;
// 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.
string service_config_id = 3;
}
// Response message for the Report method.
message ReportResponse {
// Represents the processing error of one
// [Operation][google.api.servicecontrol.v1.Operation] in the request.
message ReportError {
// The
// [Operation.operation_id][google.api.servicecontrol.v1.Operation.operation_id]
// value from the request.
string operation_id = 1;
// Details of the error when processing the
// [Operation][google.api.servicecontrol.v1.Operation].
google.rpc.Status status = 2;
}
// 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.
repeated ReportError report_errors = 1;
// The actual config id used to process the request.
string service_config_id = 2;
// The current service rollout id used to process the request.
string service_rollout_id = 4;
}

178
cmd/cli/proto_include/google/api/servicecontrol/v1/servicecontrol.yaml Normal file
View File

@ -0,0 +1,178 @@
type: google.api.Service
config_version: 3
name: servicecontrol.googleapis.com
title: Service Control API
apis:
- name: google.api.servicecontrol.v1.QuotaController
- name: google.api.servicecontrol.v1.ServiceController
documentation:
summary: |-
Provides admission control and telemetry reporting for services integrated
with Service Infrastructure.
overview: |-
Google Service Control provides control plane functionality to managed
services, such as logging, monitoring, and status checks. This page
provides an overview of what it does and how it works.
## Why use Service Control?
When you develop a cloud service, you typically start with the business
requirements and the architecture design, then proceed with API definition
and implementation. Before you put your service into production, you
need to deal with many control plane issues:
* How to control access to your service.
* How to send logging and monitoring data to both consumers and producers.
* How to create and manage dashboards to visualize this data.
* How to automatically scale the control plane components with your
service.
Service Control is a mature and feature-rich control plane provider
that addresses these needs with high efficiency, high scalability,
and high availability. It provides a simple public API that can be
accessed from anywhere using JSON REST and gRPC clients, so when you move
your service from on-premise to a cloud provider, or from one cloud
provider to another, you don't need to change the control plane provider.
Services built using Google Cloud Endpoints already take advantage of
Service Control. Cloud Endpoints sends logging and monitoring data
through Google Service Control for every request arriving at its
proxy. If you need to report any additional logging and monitoring data
for your Cloud Endpoints service, you can call the Service Control API
directly from your service.
The Service Control API definition is open sourced and available on
[GitHub](https://github.com/googleapis/googleapis/tree/master/google/api/servicecontrol). By
changing the DNS name, you can easily use alternative implementations
of the Service Control API.
## Architecture
Google Service Control works with a set of *managed services* and their
*operations* (activities), *checks* whether an operation is allowed to
proceed, and *reports* completed operations. Behind the scenes, it
leverages other
Google Cloud services, such as
[Google Service
Management](/service-infrastructure/docs/service-management/getting-started), [Stackdriver
Logging](/logging), and [Stackdriver Monitoring](/monitoring), while
hiding their complexity from service producers. It enables service
producers to send telemetry data to their consumers. It uses caching,
batching, aggregation, and retries to deliver higher performance and
availability than the individual backend systems it encapsulates.
<figure id="fig-arch" class="center">
<div style="width: 70%;margin: auto">
<img src="/service-infrastructure/docs/service-control/images/arch.svg"
alt="The overall architecture of a service that uses Google Service
Control."> </div> <figcaption><b>Figure 1</b>: Using Google Service
Control.</figcaption> </figure>
The Service Control API provides two methods:
*
[`services.check`](/service-infrastructure/docs/service-control/reference/rest/v1/services/check),
used for:
* Ensuring valid consumer status
* Validating API keys
*
[`services.report`](/service-infrastructure/docs/service-control/reference/rest/v1/services/report),
used for:
* Sending logs to Stackdriver Logging
* Sending metrics to Stackdriver Monitoring
We'll look at these in more detail in the rest of this overview.
## Managed services
A [managed
service](/service-infrastructure/docs/service-management/reference/rest/v1/services) is
a network service managed by
[Google Service
Management](/service-infrastructure/docs/service-management/getting-started). Each
managed service has a unique name, such as `example.googleapis.com`,
which must be a valid fully-qualified DNS name, as per RFC 1035.
For example:
* Google Cloud Pub/Sub (`pubsub.googleapis.com`)
* Google Cloud Vision (`vision.googleapis.com`)
* Google Cloud Bigtable (`bigtable.googleapis.com`)
* Google Cloud Datastore (`datastore.googleapis.com`)
Google Service Management manages the lifecycle of each service's
configuration, which is used to customize Google Service Control's
behavior. Service configurations are also used by Google Cloud Console for
displaying APIs and their settings, enabling/disabling APIs, and more.
## Operations
Google Service Control uses the generic concept of an *operation*
to represent the activities of a managed service, such as API calls and
resource usage. Each operation is associated with a managed service and a
specific service consumer, and has a set of properties that describe the
operation, such as the API method name and resource usage amount. For more
information, see the
[Operation
definition](/service-infrastructure/docs/service-control/reference/rest/v1/Operation). ##
Check
The
[`services.check`](/service-infrastructure/docs/service-control/reference/rest/v1/services/check) method
determines whether an operation should be allowed to proceed for a
managed service.
For example:
* Check if the consumer is still active.
* Check if the consumer has enabled the service.
* Check if the API key is still valid.
By performing multiple checks within a single method call, it provides
better performance, higher reliability, and reduced development cost to
service producers compared to checking with multiple backend systems.
## Report
The
[`services.report`](/service-infrastructure/docs/service-control/reference/rest/v1/services/report) method
reports completed operations for a managed service to backend
systems, such as logging and monitoring. The reported data can be seen in
Google API Console and Google Cloud Console, and retrieved with
appropriate APIs, such as the Stackdriver Logging and Stackdriver
Monitoring APIs.
## Next steps
* Read our [Getting Started
guide](/service-infrastructure/docs/service-control/getting-started) to
find out how to set up and use the Google Service Control API.
backend:
rules:
- selector: google.api.servicecontrol.v1.QuotaController.AllocateQuota
deadline: 10.0
- selector: google.api.servicecontrol.v1.ServiceController.Check
deadline: 5.0
- selector: google.api.servicecontrol.v1.ServiceController.Report
deadline: 16.0
authentication:
rules:
- selector: google.api.servicecontrol.v1.QuotaController.AllocateQuota
oauth:
canonical_scopes: |-
https://www.googleapis.com/auth/cloud-platform,
https://www.googleapis.com/auth/servicecontrol
- selector: google.api.servicecontrol.v1.ServiceController.Check
oauth:
canonical_scopes: |-
https://www.googleapis.com/auth/cloud-platform,
https://www.googleapis.com/auth/servicecontrol
- selector: google.api.servicecontrol.v1.ServiceController.Report
oauth:
canonical_scopes: |-
https://www.googleapis.com/auth/cloud-platform,
https://www.googleapis.com/auth/servicecontrol

29
cmd/cli/proto_include/google/api/servicecontrol/v1/servicecontrol_grpc_service_config.json Normal file
View File

@ -0,0 +1,29 @@
{
"methodConfig": [
{
"name": [
{
"service": "google.api.servicecontrol.v1.ServiceController",
"method": "Check"
}
],
"timeout": "5s",
"retryPolicy": {
"maxAttempts": 5,
"initialBackoff": "1s",
"maxBackoff": "10s",
"backoffMultiplier": 1.3,
"retryableStatusCodes": ["UNAVAILABLE"]
}
},
{
"name": [
{
"service": "google.api.servicecontrol.v1.ServiceController",
"method": "Report"
}
],
"timeout": "16s"
}
]
}