.. _envoy_api_file_envoy/config/filter/http/transcoder/v2/transcoder.proto: gRPC-JSON transcoder ==================== .. _extension_envoy.filters.http.grpc_json_transcoder: This extension may be referenced by the qualified name *envoy.filters.http.grpc_json_transcoder* .. note:: This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted. gRPC-JSON transcoder :ref:`configuration overview `. .. _envoy_api_msg_config.filter.http.transcoder.v2.GrpcJsonTranscoder: config.filter.http.transcoder.v2.GrpcJsonTranscoder --------------------------------------------------- `[config.filter.http.transcoder.v2.GrpcJsonTranscoder proto] `_ .. code-block:: json { "proto_descriptor": "...", "proto_descriptor_bin": "...", "services": [], "print_options": "{...}", "match_incoming_request_route": "...", "ignored_query_parameters": [], "auto_mapping": "...", "ignore_unknown_query_parameters": "...", "convert_grpc_status": "..." } .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.proto_descriptor: proto_descriptor (`string `_) Supplies the filename of :ref:`the proto descriptor set ` for the gRPC services. Precisely one of :ref:`proto_descriptor `, :ref:`proto_descriptor_bin ` must be set. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.proto_descriptor_bin: proto_descriptor_bin (`bytes `_) Supplies the binary content of :ref:`the proto descriptor set ` for the gRPC services. Precisely one of :ref:`proto_descriptor `, :ref:`proto_descriptor_bin ` must be set. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.services: services (**repeated** `string `_, *REQUIRED*) A list of strings that supplies the fully qualified service names (i.e. "package_name.service_name") that the transcoder will translate. If the service name doesn't exist in ``proto_descriptor``, Envoy will fail at startup. The ``proto_descriptor`` may contain more services than the service names specified here, but they won't be translated. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.print_options: print_options (:ref:`config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions `) Control options for response JSON. These options are passed directly to `JsonPrintOptions `_. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.match_incoming_request_route: match_incoming_request_route (`bool `_) Whether to keep the incoming request route after the outgoing headers have been transformed to the match the upstream gRPC service. Note: This means that routes for gRPC services that are not transcoded cannot be used in combination with *match_incoming_request_route*. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.ignored_query_parameters: ignored_query_parameters (**repeated** `string `_) A list of query parameters to be ignored for transcoding method mapping. By default, the transcoder filter will not transcode a request if there are any unknown/invalid query parameters. Example : .. code-block:: proto service Bookstore { rpc GetShelf(GetShelfRequest) returns (Shelf) { option (google.api.http) = { get: "/shelves/{shelf}" }; } } message GetShelfRequest { int64 shelf = 1; } message Shelf {} The request ``/shelves/100?foo=bar`` will not be mapped to ``GetShelf``` because variable binding for ``foo`` is not defined. Adding ``foo`` to ``ignored_query_parameters`` will allow the same request to be mapped to ``GetShelf``. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.auto_mapping: auto_mapping (`bool `_) Whether to route methods without the ``google.api.http`` option. Example : .. code-block:: proto package bookstore; service Bookstore { rpc GetShelf(GetShelfRequest) returns (Shelf) {} } message GetShelfRequest { int64 shelf = 1; } message Shelf {} The client could ``post`` a json body ``{"shelf": 1234}`` with the path of ``/bookstore.Bookstore/GetShelfRequest`` to call ``GetShelfRequest``. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.ignore_unknown_query_parameters: ignore_unknown_query_parameters (`bool `_) Whether to ignore query parameters that cannot be mapped to a corresponding protobuf field. Use this if you cannot control the query parameters and do not know them beforehand. Otherwise use ``ignored_query_parameters``. Defaults to false. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.convert_grpc_status: convert_grpc_status (`bool `_) Whether to convert gRPC status headers to JSON. When trailer indicates a gRPC error and there was no HTTP body, take ``google.rpc.Status`` from the ``grpc-status-details-bin`` header and use it as JSON body. If there was no such header, make ``google.rpc.Status`` out of the ``grpc-status`` and ``grpc-message`` headers. The error details types must be present in the ``proto_descriptor``. For example, if an upstream server replies with headers: .. code-block:: none grpc-status: 5 grpc-status-details-bin: CAUaMwoqdHlwZS5nb29nbGVhcGlzLmNvbS9nb29nbGUucnBjLlJlcXVlc3RJbmZvEgUKA3ItMQ The ``grpc-status-details-bin`` header contains a base64-encoded protobuf message ``google.rpc.Status``. It will be transcoded into: .. code-block:: none HTTP/1.1 404 Not Found content-type: application/json {"code":5,"details":[{"@type":"type.googleapis.com/google.rpc.RequestInfo","requestId":"r-1"}]} In order to transcode the message, the ``google.rpc.RequestInfo`` type from the ``google/rpc/error_details.proto`` should be included in the configured :ref:`proto descriptor set `. .. _envoy_api_msg_config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions: config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions ---------------------------------------------------------------- `[config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions proto] `_ .. code-block:: json { "add_whitespace": "...", "always_print_primitive_fields": "...", "always_print_enums_as_ints": "...", "preserve_proto_field_names": "..." } .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions.add_whitespace: add_whitespace (`bool `_) Whether to add spaces, line breaks and indentation to make the JSON output easy to read. Defaults to false. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions.always_print_primitive_fields: always_print_primitive_fields (`bool `_) Whether to always print primitive fields. By default primitive fields with default values will be omitted in JSON output. For example, an int32 field set to 0 will be omitted. Setting this flag to true will override the default behavior and print primitive fields regardless of their values. Defaults to false. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions.always_print_enums_as_ints: always_print_enums_as_ints (`bool `_) Whether to always print enums as ints. By default they are rendered as strings. Defaults to false. .. _envoy_api_field_config.filter.http.transcoder.v2.GrpcJsonTranscoder.PrintOptions.preserve_proto_field_names: preserve_proto_field_names (`bool `_) Whether to preserve proto field names. By default protobuf will generate JSON field names using the ``json_name`` option, or lower camel case, in that order. Setting this flag will preserve the original field names. Defaults to false.