• Home
• com.google.apis
• google-api-services-servicemanagement
• v1-rev20240823-2.0.0
• source code
• HttpRule.html

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

target.apidocs.com.google.api.services.servicemanagement.model.HttpRule.html Maven / Gradle / Ivy

Skip navigation links




Overview
Package
Class
Use
Tree
Deprecated
Index
Help




Prev Class
Next Class


Frames
No Frames


All Classes






Summary: 
Nested | 
Field | 
Constr | 
Method


Detail: 
Field | 
Constr | 
Method








com.google.api.services.servicemanagement.model
Class HttpRule



java.lang.Object


java.util.AbstractMap<String,Object>


com.google.api.client.util.GenericData


com.google.api.client.json.GenericJson


com.google.api.services.servicemanagement.model.HttpRule













All Implemented Interfaces:
Cloneable, Map<String,Object>




public final class HttpRule
extends com.google.api.client.json.GenericJson
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/{name=messages}" }; } } message GetMessageRequest { string name =
 1; // Mapped to URL path. } message Message { string text = 1; // The resource content. } This
 enables an HTTP REST to gRPC mapping as below: - HTTP: `GET /v1/messages/123456` - gRPC:
 `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}" }; } } message GetMessageRequest { message
 SubMessage { string subfield = 1; } 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: `GET
 /v1/messages/123456?revision=2&sub.subfield=foo` - gRPC: `GetMessage(message_id: "123456"
 revision: 2 sub: SubMessage(subfield: "foo"))` 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¶m=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) = { patch: "/v1/messages/{message_id}" body: "message" }; }
 } message UpdateMessageRequest { string message_id = 1; // mapped to the URL Message message = 2;
 // mapped to the body } 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:
 `PATCH /v1/messages/123456 { "text": "Hi!" }` - gRPC: `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 request body. This enables the following
 alternative definition of the update method: service Messaging { rpc UpdateMessage(Message)
 returns (Message) { option (google.api.http) = { patch: "/v1/messages/{message_id}" body: "*" };
 } } message Message { string message_id = 1; string text = 2; } The following HTTP JSON to RPC
 mapping is enabled: - HTTP: `PATCH /v1/messages/123456 { "text": "Hi!" }` - gRPC:
 `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 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 the `additional_bindings` option. Example:
 service Messaging { rpc GetMessage(GetMessageRequest) returns (Message) { option
 (google.api.http) = { get: "/v1/messages/{message_id}" additional_bindings { get:
 "/v1/users/{user_id}/messages/{message_id}" } }; } } message GetMessageRequest { string
 message_id = 1; string user_id = 2; } This enables the following two alternative HTTP JSON to RPC
 mappings: - HTTP: `GET /v1/messages/123456` - gRPC: `GetMessage(message_id: "123456")` - HTTP:
 `GET /v1/users/me/messages/123456` - gRPC: `GetMessage(user_id: "me" message_id: "123456")` 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 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 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. The following example selects a
 gRPC method and applies an `HttpRule` to it: http: rules: - 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. 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.

 
 This is the Java data model class that specifies how to parse/serialize into the JSON that is
 transmitted over HTTP when working with the Service Management API. For a detailed explanation
 see:
 https://developers.google.com/api-client-library/java/google-http-java-client/json
 

Author:
Google, Inc.












Nested Class Summary




Nested classes/interfaces inherited from class com.google.api.client.util.GenericData
com.google.api.client.util.GenericData.Flags





Nested classes/interfaces inherited from class java.util.AbstractMap
AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>





Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>








Constructor Summary

Constructors 

Constructor and Description


HttpRule() 









Method Summary

All Methods Instance Methods Concrete Methods 

Modifier and Type
Method and Description


HttpRule
clone() 


List<HttpRule>
getAdditionalBindings()
Additional HTTP bindings for the selector.



String
getBody()
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.



CustomHttpPattern
getCustom()
The custom pattern is used for specifying an HTTP method that is not included in the `pattern`
 field, such as HEAD, or "*" to leave the HTTP method unspecified for this rule.



String
getDelete()
Maps to HTTP DELETE.



String
getGet()
Maps to HTTP GET.



String
getPatch()
Maps to HTTP PATCH.



String
getPost()
Maps to HTTP POST.



String
getPut()
Maps to HTTP PUT.



String
getResponseBody()
Optional.



String
getSelector()
Selects a method to which this rule applies.



HttpRule
set(String fieldName,
   Object value) 


HttpRule
setAdditionalBindings(List<HttpRule> additionalBindings)
Additional HTTP bindings for the selector.



HttpRule
setBody(String body)
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.



HttpRule
setCustom(CustomHttpPattern custom)
The custom pattern is used for specifying an HTTP method that is not included in the `pattern`
 field, such as HEAD, or "*" to leave the HTTP method unspecified for this rule.



HttpRule
setDelete(String delete)
Maps to HTTP DELETE.



HttpRule
setGet(String get)
Maps to HTTP GET.



HttpRule
setPatch(String patch)
Maps to HTTP PATCH.



HttpRule
setPost(String post)
Maps to HTTP POST.



HttpRule
setPut(String put)
Maps to HTTP PUT.



HttpRule
setResponseBody(String responseBody)
Optional.



HttpRule
setSelector(String selector)
Selects a method to which this rule applies.







Methods inherited from class com.google.api.client.json.GenericJson
getFactory, setFactory, toPrettyString, toString





Methods inherited from class com.google.api.client.util.GenericData
entrySet, equals, get, getClassInfo, getUnknownKeys, hashCode, put, putAll, remove, setUnknownKeys





Methods inherited from class java.util.AbstractMap
clear, containsKey, containsValue, isEmpty, keySet, size, values





Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait





Methods inherited from interface java.util.Map
compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll














Constructor Detail





HttpRule
public HttpRule()









Method Detail





getAdditionalBindings
public List<HttpRule> getAdditionalBindings()
Additional HTTP bindings for the selector. Nested bindings must not contain an
 `additional_bindings` field themselves (that is, the nesting may only be one level deep).

Returns:
value or null for none








setAdditionalBindings
public HttpRule setAdditionalBindings(List<HttpRule> additionalBindings)
Additional HTTP bindings for the selector. Nested bindings must not contain an
 `additional_bindings` field themselves (that is, the nesting may only be one level deep).

Parameters:
additionalBindings - additionalBindings or null for none








getBody
public String getBody()
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.

Returns:
value or null for none








setBody
public HttpRule setBody(String body)
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.

Parameters:
body - body or null for none








getCustom
public CustomHttpPattern getCustom()
The custom pattern is used for specifying an HTTP method that is not included in the `pattern`
 field, such as HEAD, or "*" to leave the HTTP method unspecified for this rule. The wild-card
 rule is useful for services that provide content to Web (HTML) clients.

Returns:
value or null for none








setCustom
public HttpRule setCustom(CustomHttpPattern custom)
The custom pattern is used for specifying an HTTP method that is not included in the `pattern`
 field, such as HEAD, or "*" to leave the HTTP method unspecified for this rule. The wild-card
 rule is useful for services that provide content to Web (HTML) clients.

Parameters:
custom - custom or null for none








getDelete
public String getDelete()
Maps to HTTP DELETE. Used for deleting a resource.

Returns:
value or null for none








setDelete
public HttpRule setDelete(String delete)
Maps to HTTP DELETE. Used for deleting a resource.

Parameters:
delete - delete or null for none








getGet
public String getGet()
Maps to HTTP GET. Used for listing and getting information about resources.

Returns:
value or null for none








setGet
public HttpRule setGet(String get)
Maps to HTTP GET. Used for listing and getting information about resources.

Parameters:
get - get or null for none








getPatch
public String getPatch()
Maps to HTTP PATCH. Used for updating a resource.

Returns:
value or null for none








setPatch
public HttpRule setPatch(String patch)
Maps to HTTP PATCH. Used for updating a resource.

Parameters:
patch - patch or null for none








getPost
public String getPost()
Maps to HTTP POST. Used for creating a resource or performing an action.

Returns:
value or null for none








setPost
public HttpRule setPost(String post)
Maps to HTTP POST. Used for creating a resource or performing an action.

Parameters:
post - post or null for none








getPut
public String getPut()
Maps to HTTP PUT. Used for replacing a resource.

Returns:
value or null for none








setPut
public HttpRule setPut(String put)
Maps to HTTP PUT. Used for replacing a resource.

Parameters:
put - put or null for none








getResponseBody
public String getResponseBody()
Optional. The name of the response field whose value is mapped to the HTTP 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.

Returns:
value or null for none








setResponseBody
public HttpRule setResponseBody(String responseBody)
Optional. The name of the response field whose value is mapped to the HTTP 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.

Parameters:
responseBody - responseBody or null for none








getSelector
public String getSelector()
Selects a method to which this rule applies. Refer to selector for syntax details.

Returns:
value or null for none








setSelector
public HttpRule setSelector(String selector)
Selects a method to which this rule applies. Refer to selector for syntax details.

Parameters:
selector - selector or null for none








set
public HttpRule set(String fieldName,
                    Object value)

Overrides:
set in class com.google.api.client.json.GenericJson








clone
public HttpRule clone()

Overrides:
clone in class com.google.api.client.json.GenericJson














Skip navigation links




Overview
Package
Class
Use
Tree
Deprecated
Index
Help




Prev Class
Next Class


Frames
No Frames


All Classes






Summary: 
Nested | 
Field | 
Constr | 
Method


Detail: 
Field | 
Constr | 
Method






Copyright © 2011–2024 Google. All rights reserved.