Konfigurace transkódování JSON a HTTP pro gRPC JSON

Článek
11/18/2024

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Autor: James Newton-King

Transkódování json gRPC vytváří webová rozhraní RESTful JSON API z metod gRPC. Používá poznámky a možnosti pro přizpůsobení způsobu mapování rozhraní RESTful API na metody gRPC.

Pravidla HTTP

Metody gRPC musí být před podporou překódování opatřeny poznámkami s pravidlem HTTP. Pravidlo HTTP obsahuje informace o volání metody gRPC jako rozhraní RESTful API, jako je metoda HTTP a trasa.

import "google/api/annotations.proto";

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

Pravidlo HTTP je:

Poznámka k metodám gRPC.
Identifikovaný názvem google.api.http.
Importováno ze google/api/annotations.proto souboru. Soubory google/api/http.proto a google/api/annotations.proto soubory musí být v projektu.

Poznámka:

Odkazy na dokumentaci k referenčnímu zdroji .NET obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Metoda HTTP:

Metoda HTTP je určena nastavením trasy na odpovídající název pole metody HTTP:

get
put
post
delete
patch

Pole custom umožňuje jiné metody HTTP.

V následujícím příkladu CreateAddress se metoda mapuje na POST zadanou trasu:

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

Postup

Trasy transkódování json gRPC podporují parametry trasy. Například {name} ve směrování je svázané s name polem ve zprávě požadavku.

Pokud chcete svázat pole s vnořenou zprávou, zadejte cestu k poli. V následujícím příkladu {params.org} org vytvoří vazbu na pole ve IssueParams zprávě:

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;
}

Překódování tras a tras ASP.NET Core mají podobnou syntaxi a sadu funkcí. Některé funkce směrování jádra ASP.NET ale transkódování nepodporují. Tady jsou některé z nich:

Text požadavku

Překódování deserializuje základní kód JSON požadavku na zprávu požadavku. Pole body určuje, jak se tělo požadavku HTTP mapuje na zprávu požadavku. Hodnota je buď název pole požadavku, jehož hodnota je namapována na tělo požadavku HTTP, nebo * pro mapování všech polí požadavku.

V následujícím příkladu je tělo požadavku HTTP deserializováno address do pole:

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;
}

Parametry dotazů

Všechna pole ve zprávě požadavku, která nejsou vázána parametry trasy nebo text požadavku lze nastavit pomocí parametrů dotazu 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;
}

V předchozím příkladu:

org a repo pole jsou svázaná s parametry trasy.
Další pole, jako text jsou a vnořená pole z page, mohou být vázána z řetězce dotazu: ?text=value&page.index=0&page.size=10

Text odpovědi

Ve výchozím nastavení překódování serializuje celou zprávu odpovědi jako JSON. Pole response_body umožňuje serializaci podmnožinu zprávy odpovědi.

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;
}

V předchozím příkladu address je pole serializováno do textu odpovědi jako JSON.

Specifikace

Další informace o přizpůsobení transkódování gRPC naleznete ve specifikaci HttpRule.

Přizpůsobení FORMÁTU JSON

Zprávy se převedou do formátu JSON a z formátu JSON pomocí mapování JSON ve specifikaci Protobuf. Mapování JSON protobuf je standardizovaný způsob převodu mezi JSON a Protobufem a všechna serializace se řídí těmito pravidly.

Transkódování gRPC JSON však nabízí několik omezených možností pro přizpůsobení FORMÁTU JSON pomocí GrpcJsonSettings, jak je znázorněno v následující tabulce.

Možnost	Výchozí hodnota	Popis
IgnoreDefaultValues	`false`	Pokud je nastavena hodnota `true`, pole s výchozími hodnotami se během serializace ignorují.
WriteEnumsAsIntegers	`false`	Pokud je hodnota nastavena na `true`, hodnoty výčtu se zapisují jako celá čísla místo řetězců.
WriteInt64sAsStrings	`false`	Pokud je nastavena hodnota `true`a `Int64` `UInt64` hodnoty se zapisují jako řetězce místo čísel.
WriteIndented	`false`	Pokud je nastavená hodnota `true`, json se zapíše pomocí hezkého tisku. Tato možnost nemá vliv na metody streamování, které zapisují zprávy JSON s oddělovači řádků a nemůžou používat pěkný tisk.

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

Možnost pole v .proto souboru json_name přizpůsobí název pole při serializaci jako JSON, jak je znázorněno v následujícím příkladu:

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

Překódování nepodporuje pokročilé přizpůsobení JSON. Aplikace vyžadující přesné řízení struktury JSON by měly zvážit použití ASP.NET základního webového rozhraní API.

Sdílet prostřednictvím