HTTP és JSON konfigurálása gRPC JSON-átkódoláshoz

Megjegyzés:

Ez nem a cikk legújabb verziója. Az aktuális kiadásról a cikk .NET 10-es verziójában olvashat.

Figyelmeztetés

A ASP.NET Core ezen verziója már nem támogatott. További információt a .NET és a .NET Core támogatási szabályzatában talál. A jelen cikk .NET 9-es verzióját lásd az aktuális kiadásért .

Írta: James Newton-King

A gRPC JSON-transzkódolás reSTful JSON webes API-kat hoz létre a gRPC-metódusokból. Széljegyzeteket és beállításokat használ a RESTful API gRPC-metódusokhoz való leképezésének testreszabásához.

HTTP-szabályok

A gRPC-metódusokat HTTP-szabvánnyal kell széljegyzetekkel elbírálni, mielőtt támogatják a transzkódolást. A HTTP-szabály információkat tartalmaz a gRPC metódus RESTful API-ként való meghívásáról, például a HTTP-metódusról és az útvonalról.

import "google/api/annotations.proto";

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

A HTTP-szabály a következő:

• Megjegyzés a gRPC-metódusokra.
• A név google.api.httpazonosítja.
• A fájlból google/api/annotations.proto importálva. A google/api/http.proto fájloknak a google/api/annotations.proto projektben kell lenniük.

Megjegyzés:

A .NET referenciaforrásra mutató dokumentációs hivatkozások általában betöltik az adattár alapértelmezett ágát, amely a .NET következő kiadásának aktuális fejlesztését jelöli. Egy adott kiadás címkéjének kiválasztásához használja az Ágak vagy címkék közötti váltás legördülő listát. További információ: A ASP.NET Core-forráskód (dotnet/AspNetCore.Docs #26205) verziócímkéjének kiválasztása.

HTTP-metódus

A HTTP-metódus a megfelelő HTTP-metódus mezőnévre való beállításával adható meg:

• get
• put
• post
• delete
• patch

A custom mező más HTTP-metódusokat is lehetővé tesz.

A következő példában a metódus a CreateAddress megadott útvonalra POST van leképezve:

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

Útvonal

A gRPC JSON-átkódolási útvonalak támogatják az útvonalparamétereket. Egy útvonalon például {name} a kérelemüzenet mezője köti name össze.

Ha egy mezőt beágyazott üzenethez szeretne kötni, adja meg a mező elérési útját. Az alábbi példában {params.org} az üzenet mezőjéhez orgIssueParams kapcsolódik:

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

Az útvonalak és ASP.NET alapvonalak hasonló szintaxissal és funkciókészlettel rendelkeznek. A transzkódolás azonban nem támogatja az ASP.NET Core útválasztási funkcióit. Ezek a következők:

• Útvonalkorlátozások
• Alapértelmezett értékek
• Választható paraméterek
• Összetett szegmensek

A kérés tartalma

Az átkódolás deszerializálja a kérelem törzsét A JSON a kérelemüzenethez. A body mező azt határozza meg, hogy a HTTP-kérelem törzse hogyan képezze le a kérelemüzenetet. Az érték annak a kérelemmezőnek a neve, amelynek az értéke a HTTP-kérelem törzséhez van rendelve, vagy * az összes kérelemmező leképezéséhez.

Az alábbi példában a HTTP-kérelem törzse deszerializálva van a address mezőre:

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

Lekérdezési paraméterek

A kérelemüzenet azon mezői, amelyeket nem kötnek útvonalparaméterek vagy a kérelem törzse, HTTP-lekérdezési paraméterekkel állíthatók be.

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

Az előző példában:

• org és repo a mezők az útvonalparaméterekből vannak kötve.
• Más mezők, például text a beágyazott mezők pagea lekérdezési sztringből köthetők össze: ?text=value&page.index=0&page.size=10

Válasz tartalma

Az átkódolás alapértelmezés szerint JSON-ként szerializálja a teljes válaszüzenetet. A response_body mező lehetővé teszi a válaszüzenet egy részhalmazának szerializálását.

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

Az előző példában a address mező JSON-ként szerializálva lesz a válasz törzsében.

Specification

A gRPC-transzkódolás testreszabásával kapcsolatos további információkért tekintse meg a HttpRule specifikációját.

JSON testreszabása

Az üzenetek JSON-ra és JSON-ról való konvertálása a Protobuf specifikáció JSON-leképezésével történik. A Protobuf JSON-leképezése szabványosított módja a JSON és a Protobuf közötti konvertálásnak, és minden szerializálás követi ezeket a szabályokat.

A gRPC JSON-átkódolása azonban korlátozott lehetőségeket kínál a JSON GrpcJsonSettingstestreszabására az alábbi táblázatban látható módon.

Lehetőség	Alapértelmezett érték	Description
IgnoreDefaultValues	false	Ha be van állítva, trueaz alapértelmezett értékeket tartalmazó mezők figyelmen kívül lesznek hagyva a szerializálás során.
WriteEnumsAsIntegers	false	Ha be van állítva, a trueszámértékek sztringek helyett egész számként lesznek megírva.
WriteInt64sAsStrings	false	Ha be van állítva, trueInt64 és UInt64 az értékek számok helyett sztringekként vannak megírva.
WriteIndented	false	Ha be van állítva, a trueJSON írása szép nyomtatással történik. Ez a beállítás nem befolyásolja a streamelési módszereket, amelyek sorhatárolt JSON-üzeneteket írnak, és nem használhatnak szép nyomtatást.

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

A fájlban a .protojson_name mezőbeállítás testre szabja egy mező nevét, amikor JSON-ként szerializálják, ahogyan az alábbi példában is látható:

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

A transzkódolás nem támogatja a speciális JSON-testreszabást. A pontos JSON-struktúra-vezérlést igénylő alkalmazásoknak érdemes megfontolni a ASP.NET Core Web API használatát.

További erőforrások

• gRPC JSON-átkódolás ASP.NET Core gRPC-alkalmazásokban
• HttpRule specifikáció