Configuración de HTTP y JSON para la transcodificación de JSON de gRPC

Artículo
11/18/2024

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión de .NET 9 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulte la directiva de compatibilidad de .NET y .NET Core. Para la versión actual, consulte la versión de .NET 9 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulte la versión de .NET 9 de este artículo.

Por James Newton-King

La transcodificación JSON de gRPC crea API web RESTful JSON a partir de métodos gRPC. Usa anotaciones y opciones para personalizar cómo se asigna una API RESTful a los métodos gRPC.

Reglas HTTP

Los métodos gRPC deben anotarse con una regla HTTP antes de admitir la transcodificación. La regla HTTP incluye información sobre cómo llamar al método gRPC como una API RESTful, como el método HTTP y la ruta.

import "google/api/annotations.proto";

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

Una regla HTTP es:

Una anotación en métodos gRPC.
Se identifica por el nombre google.api.http.
Se Importa desde el archivo google/api/annotations.proto. Los archivos google/api/http.proto y google/api/annotations.proto deben estar en el proyecto.

Nota

Los vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta de una versión específica, usa la lista desplegable Cambiar ramas o etiquetas. Para obtener más información, vea Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).

HTTP method

El método HTTP se especifica estableciendo la ruta en el nombre del campo del método HTTP coincidente:

get
put
post
delete
patch

El campo custom permite otros métodos HTTP.

En el ejemplo siguiente, el método CreateAddress se asigna a POST con la ruta especificada:

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

Enrutar

Las rutas de transcodificación JSON de gRPC admiten parámetros de ruta. Por ejemplo, {name} en una ruta se enlaza al campo name en el mensaje de solicitud.

Para enlazar un campo en un mensaje anidado, especifique la ruta de acceso al campo. En el ejemplo siguiente, {params.org} se enlaza al campo org del mensaje 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;
}

Las rutas de transcodificación y las rutas de ASP.NET Core tienen una sintaxis y un conjunto de características similares. Sin embargo, algunas características de enrutamiento de ASP.NET Core no son compatibles con la transcodificación. Entre ellas se incluyen las siguientes:

Cuerpo de la solicitud

La transcodificación deserializa el JSON del cuerpo de la solicitud en el mensaje de solicitud. El campo body especifica cómo se asigna el cuerpo de la solicitud HTTP al mensaje de solicitud. El valor es el nombre del campo de solicitud cuyo valor se asigna al cuerpo de la solicitud HTTP o * para asignar todos los campos de solicitud.

En el ejemplo siguiente, el cuerpo de la solicitud HTTP se deserializa en el campo address:

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

Parámetros de consulta

Los campos del mensaje de solicitud que no están enlazados por parámetros de ruta o el cuerpo de la solicitud se pueden establecer mediante parámetros de consulta 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;
}

En el ejemplo anterior:

Los campos org y repo se enlazan a partir de parámetros de ruta.
Otros campos, como text y los campos anidados de page, se pueden enlazar desde la cadena de consulta: ?text=value&page.index=0&page.size=10

Response body

De forma predeterminada, la transcodificación serializa todo el mensaje de respuesta como JSON. El campo response_body permite la serialización de un subconjunto del mensaje de respuesta.

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

En el ejemplo anterior, el campo address se serializa en el cuerpo de la respuesta como JSON.

Especificación

Para obtener más información sobre cómo personalizar la transcodificación de gRPC, consulte la especificación HttpRule.

Personalización de JSON

Los mensajes se convierten en y desde JSON mediante la asignación JSON en la especificación Protobuf. La asignación JSON de Protobuf es una manera estandarizada de convertir entre JSON y Protobuf, y toda la serialización sigue estas reglas.

Sin embargo, la transcodificación JSON de gRPC ofrece algunas opciones limitadas para personalizar JSON con GrpcJsonSettings, como se muestra en la tabla siguiente.

Opción	Valor predeterminado	Descripción
IgnoreDefaultValues	`false`	Si se establece en `true`, los campos con valores predeterminados se omiten durante la serialización.
WriteEnumsAsIntegers	`false`	Si se establece en `true`, los valores de enumeración se escriben como enteros en lugar de cadenas.
WriteInt64sAsStrings	`false`	Si se establece en `true`, los valores `Int64` y `UInt64` se escriben como cadenas en lugar de números.
WriteIndented	`false`	Si se establece en `true`, JSON se escribe con una impresión con sangría. Esta opción no afecta a los métodos de streaming, que escriben mensajes JSON delimitados por líneas y no pueden usar una impresión con sangría.

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

En el archivo .proto, la opción del campo json_name personaliza el nombre de un campo cuando se serializa como JSON, como en el ejemplo siguiente:

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

La transcodificación no admite la personalización avanzada de JSON. Las aplicaciones que requieren un control preciso de la estructura JSON deben considerar el uso de la API web de ASP.NET Core.

Compartir a través de