From fc37c47e70b83c1cc5cc1616c9a307c4303fe789 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 24 Apr 2019 13:45:28 -0700 Subject: [PATCH] Synchronize new proto/yaml changes. PiperOrigin-RevId: 245108285 --- google/api/auth.proto | 9 +- google/api/backend.proto | 5 +- google/api/billing.proto | 9 +- google/api/config_change.proto | 5 +- google/api/context.proto | 5 +- google/api/control.proto | 2 +- google/api/distribution.proto | 4 +- google/api/documentation.proto | 8 +- google/api/endpoint.proto | 8 +- google/api/http.proto | 16 +- google/api/httpbody.proto | 2 +- google/api/label.proto | 2 +- google/api/launch_stage.proto | 2 +- google/api/log.proto | 2 +- google/api/logging.proto | 13 +- google/api/metric.proto | 7 +- google/api/monitored_resource.proto | 39 ++--- google/api/monitoring.proto | 10 +- google/api/quota.proto | 11 +- google/api/resource.proto | 196 +++++++++++++++++------- google/api/service.proto | 13 +- google/api/serviceconfig.yaml | 7 +- google/api/source_info.proto | 2 +- google/api/system_parameter.proto | 5 +- google/api/usage.proto | 7 +- google/example/library/v1/library.proto | 32 ++-- 26 files changed, 241 insertions(+), 180 deletions(-) diff --git a/google/api/auth.proto b/google/api/auth.proto index 1440465e..7c5d6166 100644 --- a/google/api/auth.proto +++ b/google/api/auth.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,8 +17,6 @@ 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 = "AuthProto"; @@ -61,8 +59,7 @@ message Authentication { message AuthenticationRule { // Selects the methods to which this rule applies. // - // Refer to [selector][google.api.DocumentationRule.selector] for syntax - // details. + // Refer to [selector][google.api.DocumentationRule.selector] for syntax details. string selector = 1; // The requirements for OAuth credentials. @@ -75,7 +72,7 @@ message AuthenticationRule { repeated AuthRequirement requirements = 7; } -// Configuration for an anthentication provider, including support for +// Configuration for an authentication provider, including support for // [JSON Web Token // (JWT)](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32). message AuthProvider { diff --git a/google/api/backend.proto b/google/api/backend.proto index 1bb30839..26a16ef4 100644 --- a/google/api/backend.proto +++ b/google/api/backend.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -92,8 +92,7 @@ message BackendRule { // Selects the methods to which this rule applies. // - // Refer to [selector][google.api.DocumentationRule.selector] for syntax - // details. + // Refer to [selector][google.api.DocumentationRule.selector] for syntax details. string selector = 1; // The address of the API backend. diff --git a/google/api/billing.proto b/google/api/billing.proto index 9a50ec42..87c11e7f 100644 --- a/google/api/billing.proto +++ b/google/api/billing.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,7 +17,6 @@ syntax = "proto3"; package google.api; -import "google/api/annotations.proto"; import "google/api/metric.proto"; option go_package = "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig"; @@ -52,13 +51,11 @@ message Billing { // bill against consumer project). message BillingDestination { // The monitored resource type. The type must be defined in - // [Service.monitored_resources][google.api.Service.monitored_resources] - // section. + // [Service.monitored_resources][google.api.Service.monitored_resources] section. string monitored_resource = 1; // Names of the metrics to report to this billing destination. - // Each name must be defined in - // [Service.metrics][google.api.Service.metrics] section. + // Each name must be defined in [Service.metrics][google.api.Service.metrics] section. repeated string metrics = 2; } diff --git a/google/api/config_change.proto b/google/api/config_change.proto index 03f5c629..c36764a5 100644 --- a/google/api/config_change.proto +++ b/google/api/config_change.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -36,8 +36,7 @@ message ConfigChange { // 'key' is used. If the field has no unique identifier, the numeric index // is used. // Examples: - // - - // visibility.rules[selector=="google.LibraryService.CreateBook"].restriction + // - visibility.rules[selector=="google.LibraryService.ListBooks"].restriction // - quota.metric_rules[selector=="google"].metric_costs[key=="reads"].value // - logging.producer_destinations[0] string element = 1; diff --git a/google/api/context.proto b/google/api/context.proto index c342e654..2d330f6f 100644 --- a/google/api/context.proto +++ b/google/api/context.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -71,8 +71,7 @@ message Context { message ContextRule { // Selects the methods to which this rule applies. // - // Refer to [selector][google.api.DocumentationRule.selector] for syntax - // details. + // Refer to [selector][google.api.DocumentationRule.selector] for syntax details. string selector = 1; // A list of full type names of requested contexts. diff --git a/google/api/control.proto b/google/api/control.proto index a19954e2..e769f978 100644 --- a/google/api/control.proto +++ b/google/api/control.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/distribution.proto b/google/api/distribution.proto index 173b0f9f..ee45d9dc 100644 --- a/google/api/distribution.proto +++ b/google/api/distribution.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -150,7 +150,7 @@ message Distribution { // Contextual information about the example value. Examples are: // - // Trace ID: type.googleapis.com/google.devtools.cloudtrace.v1.Trace + // Trace: type.googleapis.com/google.monitoring.v3.SpanContext // // Literal string: type.googleapis.com/google.protobuf.StringValue // diff --git a/google/api/documentation.proto b/google/api/documentation.proto index 7271bffc..74cbf67e 100644 --- a/google/api/documentation.proto +++ b/google/api/documentation.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -115,9 +115,9 @@ message DocumentationRule { // The selector is a comma-separated list of patterns. Each pattern is a // qualified name of the element which may end in "*", indicating a wildcard. // Wildcards are only allowed at the end and for a whole component of the - // qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". To - // specify a default for all applicable elements, the whole pattern "*" - // is used. + // qualified name, i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A + // wildcard will match one or more components. To specify a default for all + // applicable elements, the whole pattern "*" is used. string selector = 1; // Description of the selected API(s). diff --git a/google/api/endpoint.proto b/google/api/endpoint.proto index d7aa1dcf..2077334d 100644 --- a/google/api/endpoint.proto +++ b/google/api/endpoint.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,8 +17,6 @@ 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 = "EndpointProto"; @@ -46,8 +44,8 @@ message Endpoint { string name = 1; // DEPRECATED: This field is no longer supported. Instead of using aliases, - // please specify multiple [google.api.Endpoint][google.api.Endpoint] for each - // of the intended aliases. + // please specify multiple [google.api.Endpoint][google.api.Endpoint] for each of the intended + // aliases. // // Additional names that this endpoint will be hosted on. repeated string aliases = 2 [deprecated = true]; diff --git a/google/api/http.proto b/google/api/http.proto index 673adc06..b2977f51 100644 --- a/google/api/http.proto +++ b/google/api/http.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -33,7 +33,7 @@ message Http { // **NOTE:** All service configuration rules follow "last one wins" order. repeated HttpRule rules = 1; - // When set to true, URL path parmeters will be fully URI-decoded except in + // When set to true, URL path parameters will be fully URI-decoded except in // cases of single segment matches in reserved expansion, where "%2F" will be // left encoded. // @@ -211,18 +211,15 @@ message Http { // 1. Leaf request fields (recursive expansion nested messages in the request // message) are classified into three categories: // - Fields referred by the path template. They are passed via the URL path. -// - Fields referred by the [HttpRule.body][google.api.HttpRule.body]. They -// are passed via the HTTP +// - Fields referred by the [HttpRule.body][google.api.HttpRule.body]. They are passed via the HTTP // request body. // - All other fields are passed via the URL query parameters, and the // parameter name is the field path in the request message. A repeated // field can be represented as multiple query parameters under the same // name. -// 2. If [HttpRule.body][google.api.HttpRule.body] is "*", there is no URL -// query parameter, all fields +// 2. If [HttpRule.body][google.api.HttpRule.body] is "*", there is no URL query parameter, all fields // are passed via URL path and HTTP request body. -// 3. If [HttpRule.body][google.api.HttpRule.body] is omitted, there is no HTTP -// request body, all +// 3. If [HttpRule.body][google.api.HttpRule.body] is omitted, there is no HTTP request body, all // fields are passed via URL path and URL query parameters. // // ### Path template syntax @@ -317,8 +314,7 @@ message Http { message HttpRule { // Selects a method to which this rule applies. // - // Refer to [selector][google.api.DocumentationRule.selector] for syntax - // details. + // Refer to [selector][google.api.DocumentationRule.selector] for syntax details. string selector = 1; // Determines the URL pattern is matched by this rules. This pattern can be diff --git a/google/api/httpbody.proto b/google/api/httpbody.proto index 96c82b99..45c1e76b 100644 --- a/google/api/httpbody.proto +++ b/google/api/httpbody.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/label.proto b/google/api/label.proto index 77972ddf..668efd1c 100644 --- a/google/api/label.proto +++ b/google/api/label.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/launch_stage.proto b/google/api/launch_stage.proto index 42ac5ec1..55fd9142 100644 --- a/google/api/launch_stage.proto +++ b/google/api/launch_stage.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/log.proto b/google/api/log.proto index 9930242c..1125e1fe 100644 --- a/google/api/log.proto +++ b/google/api/log.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/logging.proto b/google/api/logging.proto index 9a2eb3cc..9090b2a1 100644 --- a/google/api/logging.proto +++ b/google/api/logging.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,8 +17,6 @@ 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 = "LoggingProto"; @@ -59,14 +57,13 @@ message Logging { // or the consumer project). message LoggingDestination { // The monitored resource type. The type must be defined in the - // [Service.monitored_resources][google.api.Service.monitored_resources] - // section. + // [Service.monitored_resources][google.api.Service.monitored_resources] section. string monitored_resource = 3; // Names of the logs to be sent to this destination. Each name must - // be defined in the [Service.logs][google.api.Service.logs] section. If the - // log name is not a domain scoped name, it will be automatically prefixed - // with the service name followed by "/". + // be defined in the [Service.logs][google.api.Service.logs] section. If the log name is + // not a domain scoped name, it will be automatically prefixed with + // the service name followed by "/". repeated string logs = 1; } diff --git a/google/api/metric.proto b/google/api/metric.proto index b29d4fb8..4d3c488f 100644 --- a/google/api/metric.proto +++ b/google/api/metric.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -205,9 +205,8 @@ message MetricDescriptor { // A specific metric, identified by specifying values for all of the // labels of a [`MetricDescriptor`][google.api.MetricDescriptor]. message Metric { - // An existing metric type, see - // [google.api.MetricDescriptor][google.api.MetricDescriptor]. For example, - // `custom.googleapis.com/invoice/paid/amount`. + // An existing metric type, see [google.api.MetricDescriptor][google.api.MetricDescriptor]. + // For example, `custom.googleapis.com/invoice/paid/amount`. string type = 3; // The set of label values that uniquely identify this metric. All diff --git a/google/api/monitored_resource.proto b/google/api/monitored_resource.proto index 9fefb5cc..a2c4525b 100644 --- a/google/api/monitored_resource.proto +++ b/google/api/monitored_resource.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -27,10 +27,9 @@ option java_outer_classname = "MonitoredResourceProto"; option java_package = "com.google.api"; option objc_class_prefix = "GAPI"; -// An object that describes the schema of a -// [MonitoredResource][google.api.MonitoredResource] object using a type name -// and a set of labels. For example, the monitored resource descriptor for -// Google Compute Engine VM instances has a type of +// An object that describes the schema of a [MonitoredResource][google.api.MonitoredResource] object using a +// type name and a set of labels. For example, the monitored resource +// descriptor for Google Compute Engine VM instances has a type of // `"gce_instance"` and specifies the use of the labels `"instance_id"` and // `"zone"` to identify particular VM instances. // @@ -70,13 +69,11 @@ message MonitoredResourceDescriptor { // An object representing a resource that can be used for monitoring, logging, // billing, or other purposes. Examples include virtual machine instances, // databases, and storage devices such as disks. The `type` field identifies a -// [MonitoredResourceDescriptor][google.api.MonitoredResourceDescriptor] object -// that describes the resource's schema. Information in the `labels` field -// identifies the actual resource and its attributes according to the schema. -// For example, a particular Compute Engine VM instance could be represented by -// the following object, because the -// [MonitoredResourceDescriptor][google.api.MonitoredResourceDescriptor] for -// `"gce_instance"` has labels +// [MonitoredResourceDescriptor][google.api.MonitoredResourceDescriptor] object that describes the resource's +// schema. Information in the `labels` field identifies the actual resource and +// its attributes according to the schema. For example, a particular Compute +// Engine VM instance could be represented by the following object, because the +// [MonitoredResourceDescriptor][google.api.MonitoredResourceDescriptor] for `"gce_instance"` has labels // `"instance_id"` and `"zone"`: // // { "type": "gce_instance", @@ -84,10 +81,8 @@ message MonitoredResourceDescriptor { // "zone": "us-central1-a" }} message MonitoredResource { // Required. The monitored resource type. This field must match - // the `type` field of a - // [MonitoredResourceDescriptor][google.api.MonitoredResourceDescriptor] - // object. For example, the type of a Compute Engine VM instance is - // `gce_instance`. + // the `type` field of a [MonitoredResourceDescriptor][google.api.MonitoredResourceDescriptor] object. For + // example, the type of a Compute Engine VM instance is `gce_instance`. string type = 1; // Required. Values for all of the labels listed in the associated monitored @@ -96,12 +91,12 @@ message MonitoredResource { map labels = 2; } -// Auxiliary metadata for a [MonitoredResource][google.api.MonitoredResource] -// object. [MonitoredResource][google.api.MonitoredResource] objects contain the -// minimum set of information to uniquely identify a monitored resource -// instance. There is some other useful auxiliary metadata. Monitoring and -// Logging use an ingestion pipeline to extract metadata for cloud resources of -// all types, and store the metadata in this message. +// Auxiliary metadata for a [MonitoredResource][google.api.MonitoredResource] object. +// [MonitoredResource][google.api.MonitoredResource] objects contain the minimum set of information to +// uniquely identify a monitored resource instance. There is some other useful +// auxiliary metadata. Monitoring and Logging use an ingestion +// pipeline to extract metadata for cloud resources of all types, and store +// the metadata in this message. message MonitoredResourceMetadata { // Output only. Values for predefined system metadata labels. // System labels are a kind of metadata extracted by Google, including diff --git a/google/api/monitoring.proto b/google/api/monitoring.proto index 44ce64c6..07e962d1 100644 --- a/google/api/monitoring.proto +++ b/google/api/monitoring.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,8 +17,6 @@ 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 = "MonitoringProto"; @@ -67,13 +65,11 @@ message Monitoring { // or the consumer project). message MonitoringDestination { // The monitored resource type. The type must be defined in - // [Service.monitored_resources][google.api.Service.monitored_resources] - // section. + // [Service.monitored_resources][google.api.Service.monitored_resources] section. string monitored_resource = 1; // Types of the metrics to report to this monitoring destination. - // Each type must be defined in - // [Service.metrics][google.api.Service.metrics] section. + // Each type must be defined in [Service.metrics][google.api.Service.metrics] section. repeated string metrics = 2; } diff --git a/google/api/quota.proto b/google/api/quota.proto index 5ae7720e..2e6e52b6 100644 --- a/google/api/quota.proto +++ b/google/api/quota.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,8 +17,6 @@ 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"; @@ -28,7 +26,7 @@ option objc_class_prefix = "GAPI"; // Quota configuration helps to achieve fairness and budgeting in service // usage. // -// The quota configuration works this way: +// The metric based 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. @@ -74,6 +72,8 @@ option objc_class_prefix = "GAPI"; // display_name: Write requests // metric_kind: DELTA // value_type: INT64 +// +// message Quota { // List of `QuotaLimit` definitions for the service. repeated QuotaLimit limits = 3; @@ -88,8 +88,7 @@ message Quota { message MetricRule { // Selects the methods to which this rule applies. // - // Refer to [selector][google.api.DocumentationRule.selector] for syntax - // details. + // 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 diff --git a/google/api/resource.proto b/google/api/resource.proto index 3ab666db..54f8aeb7 100644 --- a/google/api/resource.proto +++ b/google/api/resource.proto @@ -19,46 +19,23 @@ package google.api; import "google/protobuf/descriptor.proto"; +option cc_enable_arenas = true; option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations"; option java_multiple_files = true; option java_outer_classname = "ResourceProto"; option java_package = "com.google.api"; option objc_class_prefix = "GAPI"; -option (google.api.resource_definition) = { - pattern: "projects/{project}" - symbol: "Project" -}; - -option (google.api.resource_definition) = { - pattern: "organizations/{organization}" - symbol: "Organization" -}; - extend google.protobuf.FieldOptions { - // A representation of the resource. - // This is generally intended to be attached to the "name" field of - // the message representing the resource. - // - // Example: - // - // message Topic { - // string name = 1 [(google.api.resource) = { - // pattern: "projects/{project}/topics/{topic}" - // }]; - // } - // - // Only one of {`resource`, `resource_reference`} may be set. - google.api.Resource resource = 1053; - // The fully qualified message name of the type that this field references. // Marks this as a field referring to a resource in another message. // // Example: // // message Subscription { - // string topic = 2 - // [(google.api.resource_reference) = "google.pubsub.v1.Topic"]; + // string topic = 2 [(google.api.resource_reference) = { + // type: "pubsub.googleapis.com/Topic" + // }]; // } // // If the referenced message is in the same proto package, the package @@ -66,52 +43,157 @@ extend google.protobuf.FieldOptions { // // message Subscription { // string topic = 2 - // [(google.api.resource_reference) = "Topic"]; + // [(google.api.resource_reference).type = "Topic"]; // } // // Only one of {`resource`, `resource_reference`} may be set. - string resource_reference = 1055; + google.api.ResourceReference resource_reference = 1055; } -extend google.protobuf.FileOptions { - // A representation of a resource. - // At a file level, this is generally used to define information for a - // resource from another API, or for a resource that does not have an - // associated proto message. +extend google.protobuf.MessageOptions { + // An annotation describing a resource. // - // See the example of `google.api.Project` and `google.api.Organization` - // at the bottom of this file. - repeated google.api.Resource resource_definition = 1053; + // Example: + // + // message Topic { + // option (google.api.resource) = { + // type: "pubsub.googleapis.com/Topic" + // pattern: "projects/{project}/topics/{topic}" + // }; + // } + // + // Only one of {`resource`, `resource_reference`} may be set. + google.api.ResourceDescriptor resource = 1053; } -// An annotation designating that this field designates a resource. +// A simple descriptor of a resource type. +// +// ResourceDescriptor annotates a resource message (either by means of a +// protobuf annotation or use in the service config), and associates the +// resource's schema, the resource type, and the pattern of the resource name. // // Example: // -// message Topic { -// string name = 1 [(google.api.resource) = { -// name: "projects/{project}/topics/{topic}" -// }]; -// } -message Resource { - // Required. The resource's name template. +// message Topic { +// // Indicates this message defines a resource schema. +// // Declares the resource type in the format of {service}/{kind}. +// // For Kubernetes resources, the format is {api group}/{kind}. +// option (google.api.resource) = { +// type: "pubsub.googleapis.com/Topic" +// pattern: "projects/{project}/topics/{topic}" +// }; +// } +// +// Sometimes, resources have multiple patterns, typically because they can +// live under multiple parents. +// +// Example: +// +// message LogEntry { +// option (google.api.resource) = { +// type: "logging.googleapis.com/LogEntry" +// pattern: "projects/{project}/logs/{log}" +// pattern: "organizations/{organization}/logs/{log}" +// pattern: "folders/{folder}/logs/{log}" +// pattern: "billingAccounts/{billing_account}/logs/{log}" +// }; +// } +message ResourceDescriptor { + // A description of the historical or future-looking state of the + // resource pattern. + enum History { + // The "unset" value. + HISTORY_UNSPECIFIED = 0; + + // The resource originally had one pattern and launched as such, and + // additional patterns were added later. + ORIGINALLY_SINGLE_PATTERN = 1; + + // The resource has one pattern, but the API owner expects to add more + // later. (This is the inverse of ORIGINALLY_SINGLE_PATTERN, and prevents + // that from being necessary once there are multiple patterns.) + FUTURE_MULTI_PATTERN = 2; + } + + // The full name of the resource type. It must be in the format of + // {service_name}/{resource_type_kind}. The resource type names are + // singular and do not contain version numbers. + // + // For example: `storage.googleapis.com/Bucket` + // + // The value of the resource_type_kind must follow the regular expression + // /[A-Z][a-zA-Z0-9]+/. It must start with upper case character and + // recommended to use PascalCase (UpperCamelCase). The maximum number of + // characters allowed for the resource_type_kind is 100. + string type = 1; + + // Required. The valid pattern or patterns for this resource's names. // // Examples: // - "projects/{project}/topics/{topic}" // - "projects/{project}/knowledgeBases/{knowledge_base}" - string pattern = 1; - - // The name that should be used in code to describe the resource, - // in PascalCase. // - // If omitted, this is inferred from the name of the message. - // This is required if the resource is being defined without the context - // of a message (see `resource_definition`, below). + // The components in braces correspond to the IDs for each resource in the + // hierarchy. It is expected that, if multiple patterns are provided, + // the same component name (e.g. "project") refers to IDs of the same + // type of resource. + repeated string pattern = 2; + + // Optional. The field on the resource that designates the resource name + // field. If omitted, this is assumed to be "name". + string name_field = 3; + + // Optional. The historical or future-looking state of the resource pattern. // // Example: - // option (google.api.resource_definition) = { - // pattern: "projects/{project}" - // symbol: "Project" - // }; - string symbol = 2; + // // The InspectTemplate message originally only supported resource + // // names with organization, and project was added later. + // message InspectTemplate { + // option (google.api.resource) = { + // type: "dlp.googleapis.com/InspectTemplate" + // pattern: "organizations/{organization}/inspectTemplates/{inspect_template}" + // pattern: "projects/{project}/inspectTemplates/{inspect_template}" + // history: ORIGINALLY_SINGLE_PATTERN + // }; + // } + History history = 4; +} + +// An annotation designating that this field is a reference to a resource +// defined by another message. +message ResourceReference { + // The unified resource type name of the type that this field references. + // Marks this as a field referring to a resource in another message. + // + // Example: + // + // message Subscription { + // string topic = 2 [(google.api.resource_reference) = { + // type = "pubsub.googleapis.com/Topic" + // }]; + // } + string type = 1; + + // The fully-qualified message name of a child of the type that this field + // references. + // + // This is useful for `parent` fields where a resource has more than one + // possible type of parent. + // + // Example: + // + // message ListLogEntriesRequest { + // string parent = 1 [(google.api.resource_reference) = { + // child_type: "logging.googleapis.com/LogEntry" + // }; + // } + // + // If the referenced message is in the same proto package, the service name + // may be omitted: + // + // message ListLogEntriesRequest { + // string parent = 1 + // [(google.api.resource_reference).child_type = "LogEntry"]; + // } + string child_type = 2; } diff --git a/google/api/service.proto b/google/api/service.proto index 7f99fa9a..33b69682 100644 --- a/google/api/service.proto +++ b/google/api/service.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -96,10 +96,10 @@ message Service { string producer_project_id = 22; // A list of API interfaces exported by this service. Only the `name` field - // of the [google.protobuf.Api][google.protobuf.Api] needs to be provided by - // the configuration author, as the remaining fields will be derived from the - // IDL during the normalization process. It is an error to specify an API - // interface here which cannot be resolved against the associated IDL files. + // of the [google.protobuf.Api][google.protobuf.Api] needs to be provided by the configuration + // author, as the remaining fields will be derived from the IDL during the + // normalization process. It is an error to specify an API interface here + // which cannot be resolved against the associated IDL files. repeated google.protobuf.Api apis = 3; // A list of all proto message types included in this API service. @@ -157,8 +157,7 @@ message Service { repeated MetricDescriptor metrics = 24; // Defines the monitored resources used by this service. This is required - // by the [Service.monitoring][google.api.Service.monitoring] and - // [Service.logging][google.api.Service.logging] configurations. + // by the [Service.monitoring][google.api.Service.monitoring] and [Service.logging][google.api.Service.logging] configurations. repeated MonitoredResourceDescriptor monitored_resources = 25; // Billing configuration. diff --git a/google/api/serviceconfig.yaml b/google/api/serviceconfig.yaml index bc899dce..6d883d42 100644 --- a/google/api/serviceconfig.yaml +++ b/google/api/serviceconfig.yaml @@ -6,14 +6,19 @@ title: Service Config API types: - name: google.api.ConfigChange - name: google.api.Distribution +- name: google.api.DocumentationRule - name: google.api.HttpBody - name: google.api.LabelDescriptor - name: google.api.Metric - name: google.api.MonitoredResource - name: google.api.MonitoredResourceDescriptor - name: google.api.MonitoredResourceMetadata +- name: google.api.ResourceDescriptor +- name: google.api.ResourceReference - name: google.api.Service -- name: google.api.DocumentationRule + +enums: +- name: google.api.FieldBehavior documentation: summary: Lets you define and config your API service. diff --git a/google/api/source_info.proto b/google/api/source_info.proto index b72f0baa..5954143d 100644 --- a/google/api/source_info.proto +++ b/google/api/source_info.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/system_parameter.proto b/google/api/system_parameter.proto index 9da17098..740a5538 100644 --- a/google/api/system_parameter.proto +++ b/google/api/system_parameter.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -68,8 +68,7 @@ message SystemParameterRule { // Selects the methods to which this rule applies. Use '*' to indicate all // methods in all APIs. // - // Refer to [selector][google.api.DocumentationRule.selector] for syntax - // details. + // Refer to [selector][google.api.DocumentationRule.selector] for syntax details. string selector = 1; // Define parameters. Multiple names may be defined for a parameter. diff --git a/google/api/usage.proto b/google/api/usage.proto index f12519b9..6ab4e408 100644 --- a/google/api/usage.proto +++ b/google/api/usage.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,8 +17,6 @@ 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 = "UsageProto"; @@ -77,8 +75,7 @@ message UsageRule { // Selects the methods to which this rule applies. Use '*' to indicate all // methods in all APIs. // - // Refer to [selector][google.api.DocumentationRule.selector] for syntax - // details. + // Refer to [selector][google.api.DocumentationRule.selector] for syntax details. string selector = 1; // If true, the selected method allows unregistered calls, e.g. calls diff --git a/google/example/library/v1/library.proto b/google/example/library/v1/library.proto index fd15ccd7..bc36c31d 100644 --- a/google/example/library/v1/library.proto +++ b/google/example/library/v1/library.proto @@ -143,12 +143,16 @@ service LibraryService { // A single book in the library. message Book { + option (google.api.resource) = { + type: "library-example.googleapis.com/Book", + pattern: "shelves/{shelf_id}/books/{book_id}" + }; // The resource name of the book. // Book names have the form `shelves/{shelf_id}/books/{book_id}`. // The name is ignored when creating a book. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource) = { pattern: "shelves/{shelf_id}/books/{book_id}" } + (google.api.resource_reference).type = "library-example.googleapis.com/Book" ]; // The name of the book author. @@ -163,12 +167,16 @@ message Book { // A Shelf contains a collection of books with a theme. message Shelf { + option (google.api.resource) = { + type: "library-example.googleapis.com/Shelf", + pattern: "shelves/{shelf_id}" + }; // The resource name of the shelf. // Shelf names have the form `shelves/{shelf_id}`. // The name is ignored when creating a shelf. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource) = { pattern: "shelves/{shelf_id}" } + (google.api.resource_reference).type = "library-example.googleapis.com/Shelf" ]; // The theme of the shelf @@ -186,7 +194,7 @@ message GetShelfRequest { // The name of the shelf to retrieve. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Shelf" + (google.api.resource_reference).type = "Shelf" ]; } @@ -221,7 +229,7 @@ message DeleteShelfRequest { // The name of the shelf to delete. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Shelf" + (google.api.resource_reference).type = "Shelf" ]; } @@ -231,13 +239,13 @@ message MergeShelvesRequest { // The name of the shelf we're adding books to. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Shelf" + (google.api.resource_reference).type = "Shelf" ]; // The name of the shelf we're removing books from and deleting. string other_shelf_name = 2 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Shelf" + (google.api.resource_reference).type = "Shelf" ]; } @@ -246,7 +254,7 @@ message CreateBookRequest { // The name of the shelf in which the book is created. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Shelf" + (google.api.resource_reference).type = "Shelf" ]; // The book to create. @@ -258,7 +266,7 @@ message GetBookRequest { // The name of the book to retrieve. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Book" + (google.api.resource_reference).type = "Book" ]; } @@ -267,7 +275,7 @@ message ListBooksRequest { // The name of the shelf whose books we'd like to list. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Shelf" + (google.api.resource_reference).type = "Shelf" ]; // Requested page size. Server may return fewer books than requested. @@ -308,7 +316,7 @@ message DeleteBookRequest { // The name of the book to delete. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Book" + (google.api.resource_reference).type = "Book" ]; } @@ -318,12 +326,12 @@ message MoveBookRequest { // The name of the book to move. string name = 1 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Book" + (google.api.resource_reference).type = "Book" ]; // The name of the destination shelf. string other_shelf_name = 2 [ (google.api.field_behavior) = REQUIRED, - (google.api.resource_reference) = "Shelf" + (google.api.resource_reference).type = "Shelf" ]; }