From b111fa6996b4e6bf6455f3d7a7bb54f63b47d0c2 Mon Sep 17 00:00:00 2001 From: Sunny Gupta Date: Thu, 12 May 2016 14:42:02 -0700 Subject: [PATCH] Update core protos for Google APIs service config. --- google/api/http.proto | 60 +++++++++++++++++++----- google/api/label.proto | 2 +- google/api/monitored_resource.proto | 71 +++++++++++++++++++---------- 3 files changed, 95 insertions(+), 38 deletions(-) diff --git a/google/api/http.proto b/google/api/http.proto index 4bbadbb7..67173ab6 100644 --- a/google/api/http.proto +++ b/google/api/http.proto @@ -1,4 +1,4 @@ -// Copyright (c) 2015, Google Inc. +// Copyright 2016 Google Inc. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -16,11 +16,20 @@ syntax = "proto3"; package google.api; +option cc_enable_arenas = true; option java_multiple_files = true; option java_outer_classname = "HttpProto"; option java_package = "com.google.api"; +// Defines the HTTP configuration for a service. It contains a list of +// [HttpRule][google.api.HttpRule], each specifying the mapping of an RPC method +// to one or more HTTP REST API methods. +message Http { + // A list of HTTP rules for configuring the HTTP REST API methods. + repeated HttpRule rules = 1; +} + // `HttpRule` defines the mapping of an RPC method to one or more HTTP // REST APIs. The mapping determines what portions of the request // message are populated from the path, query parameters, or body of @@ -36,11 +45,15 @@ option java_package = "com.google.api"; // ```proto // service Messaging { // rpc GetMessage(GetMessageRequest) returns (Message) { -// option (google.api.http).get = "/v1/messages/{message_id}"; +// option (google.api.http).get = "/v1/messages/{message_id}/{sub.subfield}"; // } // } // message GetMessageRequest { +// message SubMessage { +// string subfield = 1; +// } // string message_id = 1; // mapped to the URL +// SubMessage sub = 2; // `sub.subfield` is url-mapped // } // message Message { // string text = 1; // content of the resource @@ -52,7 +65,7 @@ option java_package = "com.google.api"; // // HTTP | RPC // -----|----- -// `GET /v1/messages/123456` | `GetMessage(message_id: "123456")` +// `GET /v1/messages/123456/foo` | `GetMessage(message_id: "123456" sub: SubMessage(subfield: "foo"))` // // In general, not only fields but also field paths can be referenced // from a path pattern. Fields mapped to the path pattern cannot be @@ -64,8 +77,12 @@ option java_package = "com.google.api"; // // ```proto // message GetMessageRequest { +// message SubMessage { +// string subfield = 1; +// } // string message_id = 1; // mapped to the URL // int64 revision = 2; // becomes a parameter +// SubMessage sub = 3; // `sub.subfield` becomes a parameter // } // ``` // @@ -73,7 +90,7 @@ option java_package = "com.google.api"; // // HTTP | RPC // -----|----- -// `GET /v1/messages/123456?revision=2` | `GetMessage(message_id: "123456" revision: 2)` +// `GET /v1/messages/123456?revision=2&sub.subfield=foo` | `GetMessage(message_id: "123456" revision: 2 sub: SubMessage(subfield: "foo"))` // // Note that fields which are mapped to HTTP parameters must have a // primitive type or a repeated primitive type. Message types are not @@ -90,6 +107,7 @@ option java_package = "com.google.api"; // option (google.api.http) = { // put: "/v1/messages/{message_id}" // body: "message" +// }; // } // } // message UpdateMessageRequest { @@ -117,10 +135,11 @@ option java_package = "com.google.api"; // option (google.api.http) = { // put: "/v1/messages/{message_id}" // body: "*" +// }; // } // } // message Message { -// string message_id = 2; +// string message_id = 1; // string text = 2; // } // ``` @@ -148,6 +167,7 @@ option java_package = "com.google.api"; // additional_bindings { // get: "/v1/users/{user_id}/messages/{message_id}" // } +// }; // } // } // message GetMessageRequest { @@ -165,6 +185,7 @@ option java_package = "com.google.api"; // `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")` // // # Rules for HTTP mapping +// // The rules for mapping HTTP path, query parameters, and body fields // to the request message are as follows: // @@ -188,18 +209,33 @@ option java_package = "com.google.api"; // FieldPath = IDENT { "." IDENT } ; // Verb = ":" LITERAL ; // -// `*` matches a single path component, `**` zero or more path components, and -// `LITERAL` a constant. A `Variable` can match an entire path as specified -// again by a template; this nested template must not contain further variables. -// If no template is given with a variable, it matches a single path component. -// The notation `{var}` is henceforth equivalent to `{var=*}`. NOTE: the field -// paths in variables and in the `body` must not refer to repeated fields. +// The syntax `*` matches a single path segment. It follows the semantics of +// [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String +// Expansion. +// +// The syntax `**` matches zero or more path segments. It follows the semantics +// of [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.3 Reserved +// Expansion. +// +// The syntax `LITERAL` matches literal text in the URL path. +// +// The syntax `Variable` matches the entire path as specified by its template; +// this nested template must not contain further variables. If a variable +// matches a single path segment, its template may be omitted, e.g. `{var}` +// is equivalent to `{var=*}`. +// +// NOTE: the field paths in variables and in the `body` must not refer to +// repeated fields or map fields. // // Use CustomHttpPattern to specify any HTTP method that is not included in the -// pattern field, such as HEAD, or "*" to leave the HTTP method unspecified for +// `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for // a given URL path rule. The wild-card rule is useful for services that provide // content to Web (HTML) clients. message HttpRule { + // Selects methods to which this rule applies. + // + // 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 // used with any of the {get|put|post|delete|patch} methods. A custom method diff --git a/google/api/label.proto b/google/api/label.proto index 680bf119..b3c8807e 100644 --- a/google/api/label.proto +++ b/google/api/label.proto @@ -1,4 +1,4 @@ -// Copyright (c) 2015, Google Inc. +// Copyright 2016 Google Inc. // // 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/monitored_resource.proto b/google/api/monitored_resource.proto index 16ac9fad..0b7513f3 100644 --- a/google/api/monitored_resource.proto +++ b/google/api/monitored_resource.proto @@ -1,4 +1,4 @@ -// Copyright (c) 2015, Google Inc. +// Copyright 2016 Google Inc. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -23,42 +23,63 @@ option java_outer_classname = "MonitoredResourceProto"; option java_package = "com.google.api"; -// A descriptor that describes the schema of [MonitoredResource][google.api.MonitoredResource]. +// 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. +// +// Different APIs can support different monitored resource types. APIs generally +// provide a `list` method that returns the monitored resource descriptors used +// by the API. message MonitoredResourceDescriptor { - // The monitored resource type. For example, the type `"cloudsql_database"` - // represents databases in Google Cloud SQL. + // Optional. The resource name of the monitored resource descriptor: + // `"projects/{project_id}/monitoredResourceDescriptors/{type}"` where + // {type} is the value of the `type` field in this object and + // {project_id} is a project ID that provides API-specific context for + // accessing the type. APIs that do not use project information can use the + // resource name format `"monitoredResourceDescriptors/{type}"`. + string name = 5; + + // Required. The monitored resource type. For example, the type + // `"cloudsql_database"` represents databases in Google Cloud SQL. string type = 1; - // A concise name for the monitored resource type that can be displayed in - // user interfaces. For example, `"Google Cloud SQL Database"`. + // Optional. A concise name for the monitored resource type that might be + // displayed in user interfaces. For example, `"Google Cloud SQL Database"`. string display_name = 2; - // A detailed description of the monitored resource type that can be used in - // documentation. + // Optional. A detailed description of the monitored resource type that might + // be used in documentation. string description = 3; - // A set of labels that can be used to describe instances of this monitored - // resource type. For example, Google Cloud SQL databases can be labeled with - // their `"database_id"` and their `"zone"`. + // Required. A set of labels used to describe instances of this monitored + // resource type. For example, an individual Google Cloud SQL database is + // identified by values for the labels `"database_id"` and `"zone"`. repeated LabelDescriptor labels = 4; } -// A monitored resource describes a resource that can be used for monitoring -// purpose. It can also be used for logging, billing, and other purposes. Each -// resource has a `type` and a set of `labels`. The labels contain information -// that identifies the resource and describes attributes of it. For example, -// you can use monitored resource to describe a normal file, where the resource -// has `type` as `"file"`, the label `path` identifies the file, and the label -// `size` describes the file size. The monitoring system can use a set of -// monitored resources of files to generate file size distribution. +// 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 +// `"instance_id"` and `"zone"`: +// +// { "type": "gce_instance", +// "labels": { "instance_id": "my-instance", +// "zone": "us-central1-a" }} message MonitoredResource { - // The monitored resource type. This field must match the corresponding - // [MonitoredResourceDescriptor.type][google.api.MonitoredResourceDescriptor.type] to this resource.. For example, - // `"cloudsql_database"` represents Cloud SQL databases. + // 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 Cloud SQL database is `"cloudsql_database"`. string type = 1; - // Values for some or all of the labels listed in the associated monitored - // resource descriptor. For example, you specify a specific Cloud SQL database - // by supplying values for both the `"database_id"` and `"zone"` labels. + // Required. Values for all of the labels listed in the associated monitored + // resource descriptor. For example, Cloud SQL databases use the labels + // `"database_id"` and `"zone"`. map labels = 2; }