Dela via

Konfigurera HTTP och JSON för gRPC JSON-transkodning

Anmärkning

Det här är inte den senaste versionen av den här artikeln. Den aktuella versionen finns i .NET 10-versionen av den här artikeln.

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i supportpolicyn för .NET och .NET Core. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Av James Newton-King

gRPC JSON-transkodning skapar RESTful JSON-webb-API:er från gRPC-metoder. Den använder anteckningar och alternativ för att anpassa hur ett RESTful API mappar till gRPC-metoderna.

HTTP-regler

gRPC-metoder måste kommenteras med en HTTP-regel innan de stöder transkodning. HTTP-regeln innehåller information om hur du anropar gRPC-metoden som ett RESTful-API, till exempel HTTP-metoden och vägen.

import "google/api/annotations.proto";

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

En HTTP-regel är:

Anmärkning

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Välj bland grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

HTTP-metod

HTTP-metoden anges genom att ange vägen till det matchande HTTP-metodfältets namn:

  • get
  • put
  • post
  • delete
  • patch

Fältet custom tillåter andra HTTP-metoder.

I följande exempel CreateAddress mappas metoden till POST med den angivna vägen:

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

Väg

gRPC JSON-omkodningsvägar stöder routningsparametrar. Till exempel, {name} i en rutt binds till fältet name i förfrågningsmeddelandet.

Om du vill binda ett fält i ett kapslat meddelande anger du sökvägen till fältet. I följande exempel {params.org} binder till fältet org i meddelandet 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;
}

Omkodningsvägar och ASP.NET Core-vägar har en liknande syntax och funktionsuppsättning. Vissa ASP.NET Core-routningsfunktioner stöds dock inte av omkodning. Dessa inkluderar:

begäranens innehåll

Omkodning deserialiserar begärandetexten JSON till begärandemeddelandet. Fältet body anger hur HTTP-begärandetexten mappar till begärandemeddelandet. Värdet är antingen namnet på det begärandefält vars värde mappas till HTTP-begärandetexten eller * för att mappa alla begärandefält.

I följande exempel deserialiseras HTTP-begärandetexten address till fältet:

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

Frågeparametrar

Alla fält i begärandemeddelandet som inte är bundna av routningsparametrar eller begärandetexten kan anges med http-frågeparametrar.

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

I föregående exempel:

  • org och repo fälten är bundna från vägparametrar.
  • Andra fält, till exempel text och kapslade fält från page, kan bindas från frågesträngen: ?text=value&page.index=0&page.size=10

Svarsdel

Som standard serialiserar omkodning hela svarsmeddelandet som JSON. Fältet response_body tillåter serialisering av en delmängd av svarsmeddelandet.

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

I föregående exempel serialiseras fältet address till svarstexten som JSON.

Specification

Mer information om hur du anpassar gRPC-omkodning finns i HttpRule-specifikationen.

Anpassa JSON

Meddelanden konverteras till och från JSON med JSON-mappningen i Protobuf-specifikationen. Protobufs JSON-mappning är ett standardiserat sätt att konvertera mellan JSON och Protobuf, och all serialisering följer dessa regler.

GRPC JSON-omkodning erbjuder dock vissa begränsade alternativ för att anpassa JSON med GrpcJsonSettings, som visas i följande tabell.

Option Standardvärde Description
IgnoreDefaultValues false Om värdet är inställt truepå ignoreras fält med standardvärden under serialiseringen.
WriteEnumsAsIntegers false Om värdet är inställt på trueskrivs uppräkningsvärden som heltal i stället för strängar.
WriteInt64sAsStrings false Om värdet är inställt på true, Int64UInt64 skrivs värdena som strängar i stället för tal.
WriteIndented false Om det är inställt på true skrivs JSON med snygg formatering. Det här alternativet påverkar inte strömningsmetoder, som skriver radavgränsade JSON-meddelanden och inte kan använda snygga utskrifter. 
builder.Services.AddGrpc().AddJsonTranscoding(o =>
{
    o.JsonSettings.WriteIndented = true;
});

.proto I filen anpassar fältalternativet json_name ett fälts namn när det serialiseras som JSON, som i följande exempel:

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

Omkodning stöder inte avancerad JSON-anpassning. Appar som kräver exakt JSON-strukturkontroll bör överväga att använda ASP.NET Core Web API.

Ytterligare resurser

  • Last updated on