Configurare HTTP e JSON per la transcodifica gRPC JSON

Articolo
11/30/2023

la transcodifica gRPC JSON crea RESTAPI Web on con ful JSda metodi gRPC. Usa annotazioni e opzioni per personalizzare il mapping di un'API RESTcon nome ai metodi gRPC.

Regole HTTP

I metodi gRPC devono essere annotati con una regola HTTP prima di supportare la transcodifica. La regola HTTP include informazioni sulla chiamata al metodo gRPC come RESTAPIful, ad esempio il metodo HTTP e la route.

import "google/api/annotations.proto";

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

Una regola HTTP è:

Annotazione sui metodi gRPC.
Identificato dal nome google.api.http.
Importato dal google/api/annotations.proto file. I google/api/http.proto file e google/api/annotations.proto devono trovarsi nel progetto.

Nota

I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).

Metodo HTTP

Il metodo HTTP viene specificato impostando la route sul nome del campo del metodo HTTP corrispondente:

get
put
post
delete
patch

Il custom campo consente altri metodi HTTP.

Nell'esempio seguente viene eseguito il mapping del CreateAddress metodo a POST con la route specificata:

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

Itinerario

Le route di transcodifica gRPC JSON supportano i parametri di route. Ad esempio, {name} in una route viene associata al campo nel name messaggio di richiesta.

Per associare un campo in un messaggio annidato, specificare il percorso del campo. Nell'esempio seguente viene {params.org} eseguito il binding al campo del orgIssueParams messaggio:

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

Le route di transcodifica e le route ASP.NET Core hanno una sintassi e un set di funzionalità simili. Tuttavia, alcune funzionalità di routing core ASP.NET non sono supportate dalla transcodifica. tra cui:

Corpo della richiesta

La transcodifica deserializza il corpo JSdella richiesta ON al messaggio di richiesta. Il body campo specifica il mapping del corpo della richiesta HTTP al messaggio di richiesta. Il valore è il nome del campo della richiesta il cui valore è mappato al corpo della richiesta HTTP o * per il mapping di tutti i campi della richiesta.

Nell'esempio seguente il corpo della richiesta HTTP viene deserializzato nel address campo :

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

Parametri di query

Tutti i campi nel messaggio di richiesta non associati ai parametri di route o al corpo della richiesta possono essere impostati usando i parametri di query 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;
}

Nell'esempio precedente:

org i campi e repo sono associati dai parametri di route.
Altri campi, ad esempio text e i campi annidati da page, possono essere associati dalla stringa di query: ?text=value&page.index=0&page.size=10

Corpo della risposta

Per impostazione predefinita, la transcodifica serializza l'intero messaggio di risposta come JSON. Il response_body campo consente la serializzazione di un subset del messaggio di risposta.

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

Nell'esempio precedente, il address campo viene serializzato nel corpo della risposta come JSON.

Specifica

Per altre informazioni sulla personalizzazione della transcodifica gRPC, vedere la specifica HttpRule.

Personalizzare JSON

I messaggi vengono convertiti in e da JSON usando il JSmapping ON nella specifica Protobuf. Il mapping ON di JSProtobuf è un modo standardizzato per eseguire la conversione tra JSON e Protobuf e tutte le serializzazioni seguono queste regole.

Tuttavia, la transcodifica gRPC JSON offre alcune opzioni limitate per la JSpersonalizzazione di ON con GrpcJsonSettings, come illustrato nella tabella seguente.

Opzione	Valore predefinito	Descrizione
IgnoreDefaultValues	`false`	Se impostato su `true`, i campi con valori predefiniti vengono ignorati durante la serializzazione.
WriteEnumsAsIntegers	`false`	Se impostato su `true`, i valori enumerazione vengono scritti come numeri interi anziché come stringhe.
WriteInt64sAsStrings	`false`	Se è impostato su `true`e `UInt64Int64` i valori vengono scritti come stringhe anziché come numeri.
WriteIndented	`false`	Se è impostata `true`su , JSON viene scritto utilizzando una stampa piuttosto semplice. Questa opzione non influisce sui metodi di streaming, che scrivono messaggi ON delimitati da JSrighe e non possono usare la stampa.

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

.proto Nel file l'opzione json_name campo personalizza il nome di un campo quando viene serializzato come JSON, come nell'esempio seguente:

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

La transcodifica non supporta la personalizzazione ON avanzata JS. Le app che richiedono un controllo preciso JSdella struttura ON devono prendere in considerazione l'uso di ASP.NET'API Web core.

Condividi tramite