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

Мақала
11/30/2023

Примечание.

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

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

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

Внимание

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

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

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

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

Правила HTTP

Методы gRPC должны быть аннотированы с помощью правила HTTP, прежде чем они поддерживают перекодирование. Правило HTTP содержит сведения о вызове метода gRPC в качестве RESTful API, например метода 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: "*"
    };
  }
}

Маршрут

Маршруты перекодирования gRPC JSON поддерживают параметры маршрута. Например, {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 не поддерживаются транскодированием. Например:

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

Перекодирование десериализирует текст JSзапроса ON в сообщение запроса. Поле 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 с помощью JSсопоставления ON в спецификации Protobuf. Сопоставление ON Protobuf является стандартизированным способом преобразования между JSON и ProtobufJS, и все сериализация следует этим правилам.

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

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

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

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

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

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

Бөлісу құралы: