Configurare HTTP e JSON per la transcodifica JSON gRPC

Di James Newton-King

La transcodifica JSON gRPC crea API Web JSON RESTful dai metodi gRPC. Usa annotazioni e opzioni per personalizzare il mapping di un'API RESTful 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 API RESTful, 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.

HTTP method (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 JSON gRPC 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 org IssueParams 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:

• Vincoli di route
• Valori predefiniti
• Parametri facoltativi
• Segmenti complessi

Testo della richiesta

La transerializzazione deserializza il corpo della richiesta JSON 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 mapping JSON nella specifica Protobuf. Il mapping JSON di Protobuf è un modo standardizzato per eseguire la conversione tra JSON e Protobuf e tutta la serializzazione segue queste regole.

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

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 JSON avanzata. Le app che richiedono un controllo preciso della struttura JSON devono prendere in considerazione l'uso di ASP.NET'API Web core.

Risorse aggiuntive

• Transcodifica JSON gRPC nelle app gRPC core ASP.NET
• Specifica HttpRule