HTTP en JSON configureren voor gRPC JSON-transcodering

Opmerking

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 10-versie van dit artikel voor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie het .NET- en .NET Core-ondersteuningsbeleid voor meer informatie. Zie de .NET 10-versie van dit artikel voor de huidige release.

Door James Newton-King

gRPC JSON-transcodering maakt RESTful JSON-web-API's op basis van gRPC-methoden. Er worden aantekeningen en opties gebruikt om aan te passen hoe een RESTful-API wordt toegewezen aan de gRPC-methoden.

HTTP-regels

gRPC-methoden moeten worden geannoteerd met een HTTP-regel voordat ze transcodering ondersteunen. De HTTP-regel bevat informatie over het aanroepen van de gRPC-methode als een RESTful-API, zoals de HTTP-methode en route.

import "google/api/annotations.proto";

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

Een HTTP-regel is:

Een aantekening op gRPC-methoden.
Geïdentificeerd door de naam google.api.http.
Geïmporteerd uit het google/api/annotations.proto bestand. De google/api/http.proto bestanden en google/api/annotations.proto bestanden moeten zich in het project bevinden.

Opmerking

Documentatiekoppelingen naar .NET-referentiebron laden meestal de standaardbranch van de opslagplaats, die de huidige ontwikkeling vertegenwoordigt voor de volgende release van .NET. Als u een tag voor een specifieke release wilt selecteren, gebruikt u de Switch branches of tags vervolgkeuzelijst. Zie Een versietag selecteren van ASP.NET Core-broncode (dotnet/AspNetCore.Docs #26205)voor meer informatie.

HTTP-methode

De HTTP-methode wordt opgegeven door de route in te stellen op de overeenkomende veldnaam van de HTTP-methode:

get
put
post
delete
patch

In het custom veld zijn andere HTTP-methoden toegestaan.

In het volgende voorbeeld wordt de CreateAddress methode toegewezen aan de opgegeven route van POST.

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

Route

gRPC JSON-transcoderingsroutes ondersteunen routeparameters. In een route wordt bijvoorbeeld {name} gekoppeld aan het name veld in het aanvraagbericht.

Als u een veld aan een genest bericht wilt binden, geeft u het pad naar het veld op. In het volgende voorbeeld wordt {params.org} gekoppeld aan het org veld van het IssueParams bericht.

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

Transcoderingsroutes en ASP.NET Core-routes hebben een vergelijkbare syntaxis en functieset. Sommige ASP.NET Kernrouteringsfuncties worden echter niet ondersteund door transcodering. Deze omvatten:

Inhoud van het verzoek

Door transcodering wordt de JSON van de aanvraagbody gedeserialiseerd naar het aanvraagbericht. Het body veld specificeert hoe de hoofdtekst van het HTTP-verzoek overeenkomt met het verzoekbericht. De waarde is of de naam van het verzoekveld waarvan de waarde is toegewezen aan de body van het HTTP-verzoek, of * om alle verzoekvelden toe te wijzen.

In het volgende voorbeeld wordt de hoofdtekst van de HTTP-aanvraag gedeserialiseerd naar het address veld:

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

Parameters voor zoekopdrachten

Velden in het aanvraagbericht die niet afhankelijk zijn van routeparameters of de aanvraagbody kunnen worden ingesteld met behulp van HTTP-queryparameters.

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

In het voorgaande voorbeeld:

org en repo velden zijn afhankelijk van routeparameters.
Andere velden, zoals text en de geneste velden van page, kunnen worden verbonden met de querytekenreeks: ?text=value&page.index=0&page.size=10

Antwoordlichaam

Standaard serialiseert transcodering het volledige antwoordbericht als JSON. Het response_body veld staat serialisatie toe van een subset van het antwoordbericht.

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

In het voorgaande voorbeeld wordt het address veld geserialiseerd naar de hoofdtekst van het antwoord als JSON.

Specification

Zie de HttpRule-specificatie voor meer informatie over het aanpassen van gRPC-transcodering.

JSON aanpassen

Berichten worden geconverteerd naar en van JSON met behulp van de JSON-toewijzing in de Protobuf-specificatie. De JSON-toewijzing van Protobuf is een gestandaardiseerde manier om te converteren tussen JSON en Protobuf, en alle serialisatie volgt deze regels.

GRPC JSON-transcodering biedt echter een aantal beperkte opties voor het aanpassen van JSON met GrpcJsonSettings, zoals wordt weergegeven in de volgende tabel.

Optie	Standaardwaarde	Description
IgnoreDefaultValues	`false`	Als deze optie is ingesteld `true`, worden velden met standaardwaarden genegeerd tijdens serialisatie.
WriteEnumsAsIntegers	`false`	Wanneer deze optie is ingesteld op `true`, worden opsommingswaarden geschreven als gehele getallen in plaats van tekenreeksen.
WriteInt64sAsStrings	`false`	Als deze optie is ingesteld op `true`en `Int64UInt64` waarden worden geschreven als tekenreeksen in plaats van getallen.
WriteIndented	`false`	Als dit is ingesteld op `true`, wordt JSON geschreven met mooie opmaak. Deze optie heeft geen invloed op streamingmethoden, die door regels gescheiden JSON-berichten schrijven en geen mooi afdrukken kunnen gebruiken.

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

In het .proto bestand past de veldoptie de json_name naam van een veld aan wanneer het wordt geserialiseerd als JSON, zoals in het volgende voorbeeld:

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

Transcodering biedt geen ondersteuning voor geavanceerde JSON-aanpassing. Apps waarvoor nauwkeurige JSON-structuurbeheer is vereist, moeten overwegen om ASP.NET Core Web-API te gebruiken.

Aanvullende bronnen

Feedback

Is deze pagina nuttig?

Last updated on 2025-11-19