google-api-client 0.23.9 → 0.24.0

data/generated/google/apis/serviceusage_v1beta1.rb

@@ -27,7 +27,7 @@ module Google
     # @see https://cloud.google.com/service-usage/
     module ServiceusageV1beta1
       VERSION = 'V1beta1'
-      REVISION = '20180820'
+      REVISION = '20180908'
 
       # View and manage your data across Google Cloud Platform services
       AUTH_CLOUD_PLATFORM = 'https://www.googleapis.com/auth/cloud-platform'

data/generated/google/apis/serviceusage_v1beta1/classes.rb

@@ -1975,79 +1975,79 @@ module Google
         end
       end
       
-      # `HttpRule` defines the mapping of an RPC method to one or more HTTP
-      # REST API methods. The mapping specifies how different portions of the RPC
-      # request message are mapped to URL path, URL query parameters, and
-      # HTTP request body. The mapping is typically specified as an
-      # `google.api.http` annotation on the RPC method,
-      # see "google/api/annotations.proto" for details.
-      # The mapping consists of a field specifying the path template and
-      # method kind.  The path template can refer to fields in the request
-      # message, as in the example below which describes a REST GET
-      # operation on a resource collection of messages:
+      # # gRPC Transcoding
+      # gRPC Transcoding is a feature for mapping between a gRPC method and one or
+      # more HTTP REST endpoints. It allows developers to build a single API service
+      # that supports both gRPC APIs and REST APIs. Many systems, including [Google
+      # APIs](https://github.com/googleapis/googleapis),
+      # [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC
+      # Gateway](https://github.com/grpc-ecosystem/grpc-gateway),
+      # and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature
+      # and use it for large scale production services.
+      # `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies
+      # how different portions of the gRPC request message are mapped to the URL
+      # path, URL query parameters, and HTTP request body. It also controls how the
+      # gRPC response message is mapped to the HTTP response body. `HttpRule` is
+      # typically specified as an `google.api.http` annotation on the gRPC method.
+      # Each mapping specifies a URL path template and an HTTP method. The path
+      # template may refer to one or more fields in the gRPC request message, as long
+      # as each field is a non-repeated field with a primitive (non-message) type.
+      # The path template controls how fields of the request message are mapped to
+      # the URL path.
+      # Example:
       # service Messaging `
       # rpc GetMessage(GetMessageRequest) returns (Message) `
-      # option (google.api.http).get = "/v1/messages/`message_id`/`sub.
-      # subfield`";
+      # option (google.api.http) = `
+      # get: "/v1/`name=messages/*"`"
+      # `;
       # `
       # `
       # message GetMessageRequest `
-      # message SubMessage `
-      # string subfield = 1;
-      # `
-      # string message_id = 1; // mapped to the URL
-      # SubMessage sub = 2;    // `sub.subfield` is url-mapped
+      # string name = 1; // Mapped to URL path.
       # `
       # message Message `
-      # string text = 1; // content of the resource
+      # string text = 1; // The resource content.
       # `
-      # The same http annotation can alternatively be expressed inside the
-      # `GRPC API Configuration` YAML file.
-      # http:
-      # rules:
-      # - selector: <proto_package_name>.Messaging.GetMessage
-      # get: /v1/messages/`message_id`/`sub.subfield`
-      # This definition enables an automatic, bidrectional mapping of HTTP
-      # JSON to RPC. Example:
-      # HTTP | RPC
+      # This enables an HTTP REST to gRPC mapping as below:
+      # HTTP | gRPC
       # -----|-----
-      # `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
-      # repeated and must have a primitive (non-message) type.
-      # Any fields in the request message which are not bound by the path
-      # pattern automatically become (optional) HTTP query
-      # parameters. Assume the following definition of the request message:
+      # `GET /v1/messages/123456`  | `GetMessage(name: "messages/123456")`
+      # Any fields in the request message which are not bound by the path template
+      # automatically become HTTP query parameters if there is no HTTP request body.
+      # For example:
       # 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`"
+      # `;
       # `
       # `
       # 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
+      # string message_id = 1; // Mapped to URL path.
+      # int64 revision = 2;    // Mapped to URL query parameter `revision`.
+      # SubMessage sub = 3;    // Mapped to URL query parameter `sub.subfield`.
       # `
       # This enables a HTTP JSON to RPC mapping as below:
-      # HTTP | RPC
+      # HTTP | gRPC
       # -----|-----
       # `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
-      # allowed. In the case of a repeated type, the parameter can be
-      # repeated in the URL, as in `...?param=A&param=B`.
-      # For HTTP method kinds which allow a request body, the `body` field
+      # Note that fields which are mapped to URL query parameters must have a
+      # primitive type or a repeated primitive type or a non-repeated message type.
+      # In the case of a repeated type, the parameter can be repeated in the URL
+      # as `...?param=A&param=B`. In the case of a message type, each field of the
+      # message is mapped to a separate parameter, such as
+      # `...?foo.a=A&foo.b=B&foo.c=C`.
+      # For HTTP methods that allow a request body, the `body` field
       # specifies the mapping. Consider a REST update method on the
       # message resource collection:
       # service Messaging `
       # rpc UpdateMessage(UpdateMessageRequest) returns (Message) `
       # option (google.api.http) = `
-      # put: "/v1/messages/`message_id`"
+      # patch: "/v1/messages/`message_id`"
       # body: "message"
       # `;
       # `
@@ -2059,9 +2059,9 @@ module Google
       # The following HTTP JSON to RPC mapping is enabled, where the
       # representation of the JSON in the request body is determined by
       # protos JSON encoding:
-      # HTTP | RPC
+      # HTTP | gRPC
       # -----|-----
-      # `PUT /v1/messages/123456 ` "text": "Hi!" `` | `UpdateMessage(message_id: "
+      # `PATCH /v1/messages/123456 ` "text": "Hi!" `` | `UpdateMessage(message_id: "
       # 123456" message ` text: "Hi!" `)`
       # The special name `*` can be used in the body mapping to define that
       # every field not bound by the path template should be mapped to the
@@ -2070,7 +2070,7 @@ module Google
       # service Messaging `
       # rpc UpdateMessage(Message) returns (Message) `
       # option (google.api.http) = `
-      # put: "/v1/messages/`message_id`"
+      # patch: "/v1/messages/`message_id`"
       # body: "*"
       # `;
       # `
@@ -2080,13 +2080,13 @@ module Google
       # string text = 2;
       # `
       # The following HTTP JSON to RPC mapping is enabled:
-      # HTTP | RPC
+      # HTTP | gRPC
       # -----|-----
-      # `PUT /v1/messages/123456 ` "text": "Hi!" `` | `UpdateMessage(message_id: "
+      # `PATCH /v1/messages/123456 ` "text": "Hi!" `` | `UpdateMessage(message_id: "
       # 123456" text: "Hi!")`
       # Note that when using `*` in the body mapping, it is not possible to
       # have HTTP parameters, as all fields not bound by the path end in
-      # the body. This makes this option more rarely used in practice of
+      # the body. This makes this option more rarely used in practice when
       # defining REST APIs. The common usage of `*` is in custom methods
       # which don't use the URL at all for transferring data.
       # It is possible to define multiple HTTP methods for one RPC by using
@@ -2105,56 +2105,96 @@ module Google
       # string message_id = 1;
       # string user_id = 2;
       # `
-      # This enables the following two alternative HTTP JSON to RPC
-      # mappings:
-      # HTTP | RPC
+      # This enables the following two alternative HTTP JSON to RPC mappings:
+      # HTTP | gRPC
       # -----|-----
       # `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`
       # `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:
-      # 1. The `body` field specifies either `*` or a field path, or is
-      # omitted. If omitted, it indicates there is no HTTP request body.
-      # 2. Leaf fields (recursive expansion of nested messages in the
-      # request) can be classified into three types:
-      # (a) Matched in the URL template.
-      # (b) Covered by body (if body is `*`, everything except (a) fields;
-      # else everything under the body field)
-      # (c) All other fields.
-      # 3. URL query parameters found in the HTTP request are mapped to (c) fields.
-      # 4. Any body sent with an HTTP request can contain only (b) fields.
-      # The syntax of the path template is as follows:
+      # ## Rules for HTTP mapping
+      # 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. 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 is "*", there is no URL query parameter, all fields
+      # are passed via URL path and HTTP request body.
+      # 3. If HttpRule.body is omitted, there is no HTTP request body, all
+      # fields are passed via URL path and URL query parameters.
+      # ### Path template syntax
       # Template = "/" Segments [ Verb ] ;
       # Segments = Segment ` "/" Segment ` ;
       # Segment  = "*" | "**" | LITERAL | Variable ;
       # Variable = "`" FieldPath [ "=" Segments ] "`" ;
       # FieldPath = IDENT ` "." IDENT ` ;
       # Verb     = ":" LITERAL ;
-      # The syntax `*` matches a single path segment. The syntax `**` matches zero
-      # or more path segments, which must be the last part of the path except the
-      # `Verb`. The syntax `LITERAL` matches literal text in the path.
+      # The syntax `*` matches a single URL path segment. The syntax `**` matches
+      # zero or more URL path segments, which must be the last part of the URL path
+      # except the `Verb`.
       # The syntax `Variable` matches part of the URL path as specified by its
       # template. A variable template must not contain other variables. If a variable
       # matches a single path segment, its template may be omitted, e.g. ``var``
       # is equivalent to ``var=*``.
+      # The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`
+      # contains any reserved character, such characters should be percent-encoded
+      # before the matching.
       # If a variable contains exactly one path segment, such as `"`var`"` or
-      # `"`var=*`"`, when such a variable is expanded into a URL path, all characters
-      # except `[-_.~0-9a-zA-Z]` are percent-encoded. Such variables show up in the
-      # Discovery Document as ``var``.
-      # If a variable contains one or more path segments, such as `"`var=foo/*`"`
-      # or `"`var=**`"`, when such a variable is expanded into a URL path, all
-      # characters except `[-_.~/0-9a-zA-Z]` are percent-encoded. Such variables
-      # show up in the Discovery Document as ``+var``.
-      # NOTE: While the single segment variable matches the semantics of
-      # [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2
-      # Simple String Expansion, the multi segment variable **does not** match
-      # RFC 6570 Reserved Expansion. The reason is that the Reserved Expansion
+      # `"`var=*`"`, when such a variable is expanded into a URL path on the client
+      # side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The
+      # server side does the reverse decoding. Such variables show up in the
+      # [Discovery Document](https://developers.google.com/discovery/v1/reference/apis)
+      # as ``var``.
+      # If a variable contains multiple path segments, such as `"`var=foo/*`"`
+      # or `"`var=**`"`, when such a variable is expanded into a URL path on the
+      # client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.
+      # The server side does the reverse decoding, except "%2F" and "%2f" are left
+      # unchanged. Such variables show up in the
+      # [Discovery Document](https://developers.google.com/discovery/v1/reference/apis)
+      # as ``+var``.
+      # ## Using gRPC API Service Configuration
+      # gRPC API Service Configuration (service config) is a configuration language
+      # for configuring a gRPC service to become a user-facing product. The
+      # service config is simply the YAML representation of the `google.api.Service`
+      # proto message.
+      # As an alternative to annotating your proto file, you can configure gRPC
+      # transcoding in your service config YAML files. You do this by specifying a
+      # `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same
+      # effect as the proto annotation. This can be particularly useful if you
+      # have a proto that is reused in multiple services. Note that any transcoding
+      # specified in the service config will override any matching transcoding
+      # configuration in the proto.
+      # Example:
+      # http:
+      # rules:
+      # # Selects a gRPC method and applies HttpRule to it.
+      # - selector: example.v1.Messaging.GetMessage
+      # get: /v1/messages/`message_id`/`sub.subfield`
+      # ## Special notes
+      # When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the
+      # proto to JSON conversion must follow the [proto3
+      # specification](https://developers.google.com/protocol-buffers/docs/proto3#json)
+      # .
+      # While the single segment variable follows the semantics of
+      # [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String
+      # Expansion, the multi segment variable **does not** follow RFC 6570 Section
+      # 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion
       # does not expand special characters like `?` and `#`, which would lead
-      # to invalid URLs.
-      # NOTE: the field paths in variables and in the `body` must not refer to
-      # repeated fields or map fields.
+      # to invalid URLs. As the result, gRPC Transcoding uses a custom encoding
+      # for multi segment variables.
+      # The path variables **must not** refer to any repeated or mapped field,
+      # because client libraries are not capable of handling such variable expansion.
+      # The path variables **must not** capture the leading "/" character. The reason
+      # is that the most common use case "`var`" does not capture the leading "/"
+      # character. For consistency, all path variables must share the same behavior.
+      # Repeated message fields must not be mapped to URL query parameters, because
+      # no client library can support such complicated mapping.
+      # If an API needs to use a JSON array for request or response body, it can map
+      # the request or response body to a repeated field. However, some gRPC
+      # Transcoding implementations may not support this feature.
       class HttpRule
         include Google::Apis::Core::Hashable
       
@@ -2173,10 +2213,11 @@ module Google
         # @return [Array<Google::Apis::ServiceusageV1beta1::AuthorizationRule>]
         attr_accessor :authorizations
       
-        # The name of the request field whose value is mapped to the HTTP body, or
-        # `*` for mapping all fields not captured by the path pattern to the HTTP
-        # body. NOTE: the referred field must not be a repeated field and must be
-        # present at the top-level of request message type.
+        # The name of the request field whose value is mapped to the HTTP request
+        # body, or `*` for mapping all request fields not captured by the path
+        # pattern to the HTTP body, or omitted for not having any HTTP request body.
+        # NOTE: the referred field must be present at the top-level of the request
+        # message type.
         # Corresponds to the JSON property `body`
         # @return [String]
         attr_accessor :body
@@ -2186,12 +2227,13 @@ module Google
         # @return [Google::Apis::ServiceusageV1beta1::CustomHttpPattern]
         attr_accessor :custom
       
-        # Used for deleting a resource.
+        # Maps to HTTP DELETE. Used for deleting a resource.
         # Corresponds to the JSON property `delete`
         # @return [String]
         attr_accessor :delete
       
-        # Used for listing and getting information about resources.
+        # Maps to HTTP GET. Used for listing and getting information about
+        # resources.
         # Corresponds to the JSON property `get`
         # @return [String]
         attr_accessor :get
@@ -2212,24 +2254,26 @@ module Google
         # @return [Google::Apis::ServiceusageV1beta1::MediaUpload]
         attr_accessor :media_upload
       
-        # Used for updating a resource.
+        # Maps to HTTP PATCH. Used for updating a resource.
         # Corresponds to the JSON property `patch`
         # @return [String]
         attr_accessor :patch
       
-        # Used for creating a resource.
+        # Maps to HTTP POST. Used for creating a resource or performing an action.
         # Corresponds to the JSON property `post`
         # @return [String]
         attr_accessor :post
       
-        # Used for updating a resource.
+        # Maps to HTTP PUT. Used for replacing a resource.
         # Corresponds to the JSON property `put`
         # @return [String]
         attr_accessor :put
       
         # Optional. The name of the response field whose value is mapped to the HTTP
-        # body of response. Other response fields are ignored. When
-        # not set, the response message will be used as HTTP body of response.
+        # response body. When omitted, the entire response message will be used
+        # as the HTTP response body.
+        # NOTE: The referred field must be present at the top-level of the response
+        # message type.
         # Corresponds to the JSON property `responseBody`
         # @return [String]
         attr_accessor :response_body
@@ -2272,7 +2316,7 @@ module Google
         # @return [String]
         attr_accessor :rest_method_name
       
-        # Selects methods to which this rule applies.
+        # Selects a method to which this rule applies.
         # Refer to selector for syntax details.
         # Corresponds to the JSON property `selector`
         # @return [String]

data/generated/google/apis/serviceuser_v1.rb

@@ -27,7 +27,7 @@ module Google
     # @see https://cloud.google.com/service-management/
     module ServiceuserV1
       VERSION = 'V1'
-      REVISION = '20180824'
+      REVISION = '20180907'
 
       # View and manage your data across Google Cloud Platform services
       AUTH_CLOUD_PLATFORM = 'https://www.googleapis.com/auth/cloud-platform'

data/generated/google/apis/serviceuser_v1/classes.rb

@@ -1118,79 +1118,79 @@ module Google
         end
       end
       
-      # `HttpRule` defines the mapping of an RPC method to one or more HTTP
-      # REST API methods. The mapping specifies how different portions of the RPC
-      # request message are mapped to URL path, URL query parameters, and
-      # HTTP request body. The mapping is typically specified as an
-      # `google.api.http` annotation on the RPC method,
-      # see "google/api/annotations.proto" for details.
-      # The mapping consists of a field specifying the path template and
-      # method kind.  The path template can refer to fields in the request
-      # message, as in the example below which describes a REST GET
-      # operation on a resource collection of messages:
+      # # gRPC Transcoding
+      # gRPC Transcoding is a feature for mapping between a gRPC method and one or
+      # more HTTP REST endpoints. It allows developers to build a single API service
+      # that supports both gRPC APIs and REST APIs. Many systems, including [Google
+      # APIs](https://github.com/googleapis/googleapis),
+      # [Cloud Endpoints](https://cloud.google.com/endpoints), [gRPC
+      # Gateway](https://github.com/grpc-ecosystem/grpc-gateway),
+      # and [Envoy](https://github.com/envoyproxy/envoy) proxy support this feature
+      # and use it for large scale production services.
+      # `HttpRule` defines the schema of the gRPC/REST mapping. The mapping specifies
+      # how different portions of the gRPC request message are mapped to the URL
+      # path, URL query parameters, and HTTP request body. It also controls how the
+      # gRPC response message is mapped to the HTTP response body. `HttpRule` is
+      # typically specified as an `google.api.http` annotation on the gRPC method.
+      # Each mapping specifies a URL path template and an HTTP method. The path
+      # template may refer to one or more fields in the gRPC request message, as long
+      # as each field is a non-repeated field with a primitive (non-message) type.
+      # The path template controls how fields of the request message are mapped to
+      # the URL path.
+      # Example:
       # service Messaging `
       # rpc GetMessage(GetMessageRequest) returns (Message) `
-      # option (google.api.http).get = "/v1/messages/`message_id`/`sub.
-      # subfield`";
+      # option (google.api.http) = `
+      # get: "/v1/`name=messages/*"`"
+      # `;
       # `
       # `
       # message GetMessageRequest `
-      # message SubMessage `
-      # string subfield = 1;
-      # `
-      # string message_id = 1; // mapped to the URL
-      # SubMessage sub = 2;    // `sub.subfield` is url-mapped
+      # string name = 1; // Mapped to URL path.
       # `
       # message Message `
-      # string text = 1; // content of the resource
+      # string text = 1; // The resource content.
       # `
-      # The same http annotation can alternatively be expressed inside the
-      # `GRPC API Configuration` YAML file.
-      # http:
-      # rules:
-      # - selector: <proto_package_name>.Messaging.GetMessage
-      # get: /v1/messages/`message_id`/`sub.subfield`
-      # This definition enables an automatic, bidrectional mapping of HTTP
-      # JSON to RPC. Example:
-      # HTTP | RPC
+      # This enables an HTTP REST to gRPC mapping as below:
+      # HTTP | gRPC
       # -----|-----
-      # `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
-      # repeated and must have a primitive (non-message) type.
-      # Any fields in the request message which are not bound by the path
-      # pattern automatically become (optional) HTTP query
-      # parameters. Assume the following definition of the request message:
+      # `GET /v1/messages/123456`  | `GetMessage(name: "messages/123456")`
+      # Any fields in the request message which are not bound by the path template
+      # automatically become HTTP query parameters if there is no HTTP request body.
+      # For example:
       # 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`"
+      # `;
       # `
       # `
       # 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
+      # string message_id = 1; // Mapped to URL path.
+      # int64 revision = 2;    // Mapped to URL query parameter `revision`.
+      # SubMessage sub = 3;    // Mapped to URL query parameter `sub.subfield`.
       # `
       # This enables a HTTP JSON to RPC mapping as below:
-      # HTTP | RPC
+      # HTTP | gRPC
       # -----|-----
       # `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
-      # allowed. In the case of a repeated type, the parameter can be
-      # repeated in the URL, as in `...?param=A&param=B`.
-      # For HTTP method kinds which allow a request body, the `body` field
+      # Note that fields which are mapped to URL query parameters must have a
+      # primitive type or a repeated primitive type or a non-repeated message type.
+      # In the case of a repeated type, the parameter can be repeated in the URL
+      # as `...?param=A&param=B`. In the case of a message type, each field of the
+      # message is mapped to a separate parameter, such as
+      # `...?foo.a=A&foo.b=B&foo.c=C`.
+      # For HTTP methods that allow a request body, the `body` field
       # specifies the mapping. Consider a REST update method on the
       # message resource collection:
       # service Messaging `
       # rpc UpdateMessage(UpdateMessageRequest) returns (Message) `
       # option (google.api.http) = `
-      # put: "/v1/messages/`message_id`"
+      # patch: "/v1/messages/`message_id`"
       # body: "message"
       # `;
       # `
@@ -1202,9 +1202,9 @@ module Google
       # The following HTTP JSON to RPC mapping is enabled, where the
       # representation of the JSON in the request body is determined by
       # protos JSON encoding:
-      # HTTP | RPC
+      # HTTP | gRPC
       # -----|-----
-      # `PUT /v1/messages/123456 ` "text": "Hi!" `` | `UpdateMessage(message_id: "
+      # `PATCH /v1/messages/123456 ` "text": "Hi!" `` | `UpdateMessage(message_id: "
       # 123456" message ` text: "Hi!" `)`
       # The special name `*` can be used in the body mapping to define that
       # every field not bound by the path template should be mapped to the
@@ -1213,7 +1213,7 @@ module Google
       # service Messaging `
       # rpc UpdateMessage(Message) returns (Message) `
       # option (google.api.http) = `
-      # put: "/v1/messages/`message_id`"
+      # patch: "/v1/messages/`message_id`"
       # body: "*"
       # `;
       # `
@@ -1223,13 +1223,13 @@ module Google
       # string text = 2;
       # `
       # The following HTTP JSON to RPC mapping is enabled:
-      # HTTP | RPC
+      # HTTP | gRPC
       # -----|-----
-      # `PUT /v1/messages/123456 ` "text": "Hi!" `` | `UpdateMessage(message_id: "
+      # `PATCH /v1/messages/123456 ` "text": "Hi!" `` | `UpdateMessage(message_id: "
       # 123456" text: "Hi!")`
       # Note that when using `*` in the body mapping, it is not possible to
       # have HTTP parameters, as all fields not bound by the path end in
-      # the body. This makes this option more rarely used in practice of
+      # the body. This makes this option more rarely used in practice when
       # defining REST APIs. The common usage of `*` is in custom methods
       # which don't use the URL at all for transferring data.
       # It is possible to define multiple HTTP methods for one RPC by using
@@ -1248,56 +1248,96 @@ module Google
       # string message_id = 1;
       # string user_id = 2;
       # `
-      # This enables the following two alternative HTTP JSON to RPC
-      # mappings:
-      # HTTP | RPC
+      # This enables the following two alternative HTTP JSON to RPC mappings:
+      # HTTP | gRPC
       # -----|-----
       # `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`
       # `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:
-      # 1. The `body` field specifies either `*` or a field path, or is
-      # omitted. If omitted, it indicates there is no HTTP request body.
-      # 2. Leaf fields (recursive expansion of nested messages in the
-      # request) can be classified into three types:
-      # (a) Matched in the URL template.
-      # (b) Covered by body (if body is `*`, everything except (a) fields;
-      # else everything under the body field)
-      # (c) All other fields.
-      # 3. URL query parameters found in the HTTP request are mapped to (c) fields.
-      # 4. Any body sent with an HTTP request can contain only (b) fields.
-      # The syntax of the path template is as follows:
+      # ## Rules for HTTP mapping
+      # 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. 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 is "*", there is no URL query parameter, all fields
+      # are passed via URL path and HTTP request body.
+      # 3. If HttpRule.body is omitted, there is no HTTP request body, all
+      # fields are passed via URL path and URL query parameters.
+      # ### Path template syntax
       # Template = "/" Segments [ Verb ] ;
       # Segments = Segment ` "/" Segment ` ;
       # Segment  = "*" | "**" | LITERAL | Variable ;
       # Variable = "`" FieldPath [ "=" Segments ] "`" ;
       # FieldPath = IDENT ` "." IDENT ` ;
       # Verb     = ":" LITERAL ;
-      # The syntax `*` matches a single path segment. The syntax `**` matches zero
-      # or more path segments, which must be the last part of the path except the
-      # `Verb`. The syntax `LITERAL` matches literal text in the path.
+      # The syntax `*` matches a single URL path segment. The syntax `**` matches
+      # zero or more URL path segments, which must be the last part of the URL path
+      # except the `Verb`.
       # The syntax `Variable` matches part of the URL path as specified by its
       # template. A variable template must not contain other variables. If a variable
       # matches a single path segment, its template may be omitted, e.g. ``var``
       # is equivalent to ``var=*``.
+      # The syntax `LITERAL` matches literal text in the URL path. If the `LITERAL`
+      # contains any reserved character, such characters should be percent-encoded
+      # before the matching.
       # If a variable contains exactly one path segment, such as `"`var`"` or
-      # `"`var=*`"`, when such a variable is expanded into a URL path, all characters
-      # except `[-_.~0-9a-zA-Z]` are percent-encoded. Such variables show up in the
-      # Discovery Document as ``var``.
-      # If a variable contains one or more path segments, such as `"`var=foo/*`"`
-      # or `"`var=**`"`, when such a variable is expanded into a URL path, all
-      # characters except `[-_.~/0-9a-zA-Z]` are percent-encoded. Such variables
-      # show up in the Discovery Document as ``+var``.
-      # NOTE: While the single segment variable matches the semantics of
-      # [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2
-      # Simple String Expansion, the multi segment variable **does not** match
-      # RFC 6570 Reserved Expansion. The reason is that the Reserved Expansion
+      # `"`var=*`"`, when such a variable is expanded into a URL path on the client
+      # side, all characters except `[-_.~0-9a-zA-Z]` are percent-encoded. The
+      # server side does the reverse decoding. Such variables show up in the
+      # [Discovery Document](https://developers.google.com/discovery/v1/reference/apis)
+      # as ``var``.
+      # If a variable contains multiple path segments, such as `"`var=foo/*`"`
+      # or `"`var=**`"`, when such a variable is expanded into a URL path on the
+      # client side, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.
+      # The server side does the reverse decoding, except "%2F" and "%2f" are left
+      # unchanged. Such variables show up in the
+      # [Discovery Document](https://developers.google.com/discovery/v1/reference/apis)
+      # as ``+var``.
+      # ## Using gRPC API Service Configuration
+      # gRPC API Service Configuration (service config) is a configuration language
+      # for configuring a gRPC service to become a user-facing product. The
+      # service config is simply the YAML representation of the `google.api.Service`
+      # proto message.
+      # As an alternative to annotating your proto file, you can configure gRPC
+      # transcoding in your service config YAML files. You do this by specifying a
+      # `HttpRule` that maps the gRPC method to a REST endpoint, achieving the same
+      # effect as the proto annotation. This can be particularly useful if you
+      # have a proto that is reused in multiple services. Note that any transcoding
+      # specified in the service config will override any matching transcoding
+      # configuration in the proto.
+      # Example:
+      # http:
+      # rules:
+      # # Selects a gRPC method and applies HttpRule to it.
+      # - selector: example.v1.Messaging.GetMessage
+      # get: /v1/messages/`message_id`/`sub.subfield`
+      # ## Special notes
+      # When gRPC Transcoding is used to map a gRPC to JSON REST endpoints, the
+      # proto to JSON conversion must follow the [proto3
+      # specification](https://developers.google.com/protocol-buffers/docs/proto3#json)
+      # .
+      # While the single segment variable follows the semantics of
+      # [RFC 6570](https://tools.ietf.org/html/rfc6570) Section 3.2.2 Simple String
+      # Expansion, the multi segment variable **does not** follow RFC 6570 Section
+      # 3.2.3 Reserved Expansion. The reason is that the Reserved Expansion
       # does not expand special characters like `?` and `#`, which would lead
-      # to invalid URLs.
-      # NOTE: the field paths in variables and in the `body` must not refer to
-      # repeated fields or map fields.
+      # to invalid URLs. As the result, gRPC Transcoding uses a custom encoding
+      # for multi segment variables.
+      # The path variables **must not** refer to any repeated or mapped field,
+      # because client libraries are not capable of handling such variable expansion.
+      # The path variables **must not** capture the leading "/" character. The reason
+      # is that the most common use case "`var`" does not capture the leading "/"
+      # character. For consistency, all path variables must share the same behavior.
+      # Repeated message fields must not be mapped to URL query parameters, because
+      # no client library can support such complicated mapping.
+      # If an API needs to use a JSON array for request or response body, it can map
+      # the request or response body to a repeated field. However, some gRPC
+      # Transcoding implementations may not support this feature.
       class HttpRule
         include Google::Apis::Core::Hashable
       
@@ -1308,10 +1348,11 @@ module Google
         # @return [Array<Google::Apis::ServiceuserV1::HttpRule>]
         attr_accessor :additional_bindings
       
-        # The name of the request field whose value is mapped to the HTTP body, or
-        # `*` for mapping all fields not captured by the path pattern to the HTTP
-        # body. NOTE: the referred field must not be a repeated field and must be
-        # present at the top-level of request message type.
+        # The name of the request field whose value is mapped to the HTTP request
+        # body, or `*` for mapping all request fields not captured by the path
+        # pattern to the HTTP body, or omitted for not having any HTTP request body.
+        # NOTE: the referred field must be present at the top-level of the request
+        # message type.
         # Corresponds to the JSON property `body`
         # @return [String]
         attr_accessor :body
@@ -1321,12 +1362,13 @@ module Google
         # @return [Google::Apis::ServiceuserV1::CustomHttpPattern]
         attr_accessor :custom
       
-        # Used for deleting a resource.
+        # Maps to HTTP DELETE. Used for deleting a resource.
         # Corresponds to the JSON property `delete`
         # @return [String]
         attr_accessor :delete
       
-        # Used for listing and getting information about resources.
+        # Maps to HTTP GET. Used for listing and getting information about
+        # resources.
         # Corresponds to the JSON property `get`
         # @return [String]
         attr_accessor :get
@@ -1347,29 +1389,31 @@ module Google
         # @return [Google::Apis::ServiceuserV1::MediaUpload]
         attr_accessor :media_upload
       
-        # Used for updating a resource.
+        # Maps to HTTP PATCH. Used for updating a resource.
         # Corresponds to the JSON property `patch`
         # @return [String]
         attr_accessor :patch
       
-        # Used for creating a resource.
+        # Maps to HTTP POST. Used for creating a resource or performing an action.
         # Corresponds to the JSON property `post`
         # @return [String]
         attr_accessor :post
       
-        # Used for updating a resource.
+        # Maps to HTTP PUT. Used for replacing a resource.
         # Corresponds to the JSON property `put`
         # @return [String]
         attr_accessor :put
       
         # Optional. The name of the response field whose value is mapped to the HTTP
-        # body of response. Other response fields are ignored. When
-        # not set, the response message will be used as HTTP body of response.
+        # response body. When omitted, the entire response message will be used
+        # as the HTTP response body.
+        # NOTE: The referred field must be present at the top-level of the response
+        # message type.
         # Corresponds to the JSON property `responseBody`
         # @return [String]
         attr_accessor :response_body
       
-        # Selects methods to which this rule applies.
+        # Selects a method to which this rule applies.
         # Refer to selector for syntax details.
         # Corresponds to the JSON property `selector`
         # @return [String]