Настройка транскодирования HTTP и JSON для gRPC JSON

Статья
11/06/2024

Примечание.

Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 9 этой статьи.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 9 этой статьи.

Внимание

Эта информация относится к предварительному выпуску продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

В текущем выпуске см . версию .NET 9 этой статьи.

Автор: Джеймс Ньютон-Кинг (James Newton-King)

Транскодирование JSON gRPC создает веб-API JSON RESTful из методов gRPC. В нем используются заметки и параметры настройки сопоставления API RESTful с методами gRPC.

Правила HTTP

Методы gRPC должны быть аннотированы с помощью правила HTTP, прежде чем они поддерживают перекодирование. Правило HTTP содержит сведения о вызове метода gRPC в качестве API RESTful, например метода HTTP и маршрута.

import "google/api/annotations.proto";

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {
    option (google.api.http) = {
      get: "/v1/greeter/{name}"
    };
  }
}

Правило HTTP:

Заметка о методах gRPC.
Определяется именем google.api.http.
Импортирован из google/api/annotations.proto файла. google/api/annotations.proto Файлы google/api/http.proto должны находиться в проекте.

Примечание.

По ссылкам в документации на справочные материалы по .NET обычно загружается ветвь репозитория по умолчанию, которая представляет текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для определенного выпуска, используйте раскрывающийся список Switch branches or tags (Переключение ветвей или тегов). Дополнительные сведения см. в статье Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Метод HTTP

Метод HTTP определяется путем задания маршрута к имени соответствующего поля метода HTTP:

get
put
post
delete
patch

Поле custom позволяет использовать другие методы HTTP.

В следующем примере CreateAddress метод сопоставляется с POST указанным маршрутом:

service Address {
  rpc CreateAddress (CreateAddressRequest) returns (CreateAddressReply) {
    option (google.api.http) = {
      post: "/v1/address",
      body: "*"
    };
  }
}

Маршрут

Перекодирование маршрутов JSON gRPC поддерживает параметры маршрута. Например, {name} в маршруте выполняется привязка к name полю в сообщении запроса.

Чтобы привязать поле к вложенном сообщении, укажите путь к полю. В следующем примере {params.org} привязывается к org полю IssueParams сообщения:

service Repository {
  rpc GetIssue (GetIssueRequest) returns (GetIssueReply) {
    option (google.api.http) = {
      get: "/{apiVersion}/{params.org}/{params.repo}/issue/{params.issueId}"
    };
  }
}

message GetIssueRequest {
  int32 api_version = 1;
  IssueParams params = 2;
}
message IssueParams {
  string org = 1;
  string repo = 2;
  int32 issueId = 3;
}

Маршруты транскодирования и ASP.NET Core имеют аналогичный синтаксис и набор функций. Однако некоторые функции маршрутизации ядра ASP.NET не поддерживаются транскодированием. Например:

Текст запроса

Перекодирование десериализирует текст запроса JSON в сообщение запроса. Поле body указывает, как текст HTTP-запроса сопоставляется с сообщением запроса. Значение — это имя поля запроса, значение которого сопоставляется с текстом HTTP-запроса или * для сопоставления всех полей запроса.

В следующем примере текст HTTP-запроса десериализируется в address поле:

service Address {
  rpc AddAddress (AddAddressRequest) returns (AddAddressReply) {
    option (google.api.http) = {
      post: "/{apiVersion}/address",
      body: "address"
    };
  }
}

message AddAddressRequest {
  int32 api_version = 1;
  Address address = 2;
}
message Address {
  string street = 1;
  string city = 2;
  string country = 3;
}

Параметры запроса

Все поля в сообщении запроса, которые не привязаны параметрами маршрута или текст запроса, можно задать с помощью параметров HTTP-запроса.

service Repository {
  rpc GetIssues (GetIssuesRequest) returns (GetIssuesReply) {
    option (google.api.http) = {
      get: "/v1/{org}/{repo}/issue"
    };
  }
}

message GetIssuesRequest {
  string org = 1;
  string repo = 2;
  string text = 3;
  PageParams page = 4;
}
message PageParams {
  int32 index = 1;
  int32 size = 2;
}

В предыдущем примере:

org и repo поля привязаны из параметров маршрута.
Другие поля, такие как text и вложенные поля page, могут быть привязаны из строки запроса: ?text=value&page.index=0&page.size=10

Текст ответа

По умолчанию транскодирование сериализует весь ответный сообщение как JSON. Поле response_body позволяет сериализовать подмножество сообщения ответа.

service Address {
  rpc GetAddress (GetAddressRequest) returns (GetAddressReply) {
    option (google.api.http) = {
      get: "/v1/address/{id}",
      response_body: "address"
    };
  }
}

message GetAddressReply {
  int32 version = 1;
  Address address = 2;
}
message Address {
  string street = 1;
  string city = 2;
  string country = 3;
}

В предыдущем примере address поле сериализуется в текст ответа в формате JSON.

Спецификация

Дополнительные сведения о настройке транскодирования gRPC см. в спецификации HttpRule.

Настройка JSON

Сообщения преобразуются в JSON и из них с помощью сопоставления JSON в спецификации Protobuf. Сопоставление JSON Protobuf является стандартизированным способом преобразования между JSON и Protobuf, и все сериализация следует этим правилам.

Однако транскодирование JSON gRPC предлагает некоторые ограниченные варианты настройки JSON с GrpcJsonSettingsпомощью, как показано в следующей таблице.

Вариант	Значение по умолчанию	Description
IgnoreDefaultValues	`false`	Если задано значение `true`, поля со значениями по умолчанию игнорируются во время сериализации.
WriteEnumsAsIntegers	`false`	Если задано значение `true`, значения перечисления записываются как целые числа вместо строк.
WriteInt64sAsStrings	`false`	Если задано значение `true`, `Int64` а `UInt64` значения записываются как строки вместо чисел.
WriteIndented	`false`	Если задано значение `true`, JSON записывается с помощью довольно печати. Этот параметр не влияет на методы потоковой передачи, которые записывают сообщения JSON с разделителями строк и не могут использовать довольно печать.

builder.Services.AddGrpc().AddJsonTranscoding(o =>
{
    o.JsonSettings.WriteIndented = true;
});

.proto В файле json_name параметр поля настраивает имя поля при сериализации в формате JSON, как показано в следующем примере:

message TestMessage {
  string my_field = 1 [json_name="customFieldName"];
}

Транскодирование не поддерживает расширенную настройку JSON. Приложения, требующие точного элемента управления структурой JSON, должны рассмотреть возможность использования ASP.NET Core Web API.

Поделиться через