gRPC JSON 코드 변환을 위한 HTTP 및 JSON 구성

아티클
11/06/2024

참고 항목

이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 8 버전을 참조 하세요.

Warning

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조 하세요. 현재 릴리스는 이 문서의 .NET 8 버전을 참조 하세요.

Important

이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

현재 릴리스는 이 문서의 .NET 8 버전을 참조 하세요.

작성자: James Newton-King

gRPC JSON 트랜스코딩은 gRPC 메서드에서 RESTful JSON 웹 API를 만듭니다. RESTful API가 gRPC 메서드에 매핑되는 방법을 사용자 지정하기 위해 주석 및 옵션을 사용합니다.

HTTP 규칙

gRPC 메서드는 코드 변환을 지원하기 전에 HTTP 규칙으로 주석을 추가해야 합니다. HTTP 규칙에는 gRPC 메서드를 RESTful API로 호출하는 방법에 대한 정보(예: HTTP 메서드 및 경로)가 포함됩니다.

import "google/api/annotations.proto";

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

HTTP 규칙은 다음과 같습니다.

gRPC 메서드에 대한 주석.
google.api.http 이름으로 식별됩니다.
google/api/annotations.proto 파일에서 가져옵니다. google/api/http.proto 및 google/api/annotations.proto 파일은 프로젝트에 있어야 합니다.

참고 항목

.NET 참조 원본의 설명서 링크는 일반적으로 다음 릴리스의 .NET을 위한 현재 개발을 나타내는 리포지토리의 기본 분기를 로드합니다. 특정 릴리스를 위한 태그를 선택하려면 Switch branches or tags(분기 또는 태그 전환) 드롭다운 목록을 사용합니다. 자세한 내용은 ASP.NET Core 소스 코드(dotnet/AspNetCore.Docs #26205)의 버전 태그를 선택하는 방법을 참조하세요.

HTTP 메서드

HTTP 메서드는 경로를 일치하는 HTTP 메서드 필드 이름으로 설정하여 지정합니다.

get
put
post
delete
patch

custom 필드는 다른 HTTP 메서드를 허용합니다.

다음 예제에서 CreateAddress 메서드는 지정된 경로를 사용하여 POST에 매핑됩니다.

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

경로

gRPC JSON 코드 변환 경로는 경로 매개 변수를 지원합니다. 예를 들어, 경로의 {name}에서 요청 메시지의 name 필드에 바인딩됩니다.

중첩된 메시지에 필드를 바인딩하려면 필드의 경로를 지정합니다. 다음 예제에서는 IssueParams 메시지의 org 필드에 {params.org}을 바인딩합니다.

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

코드 변환 경로 및 ASP.NET Core 경로에는 유사한 구문과 기능 집합이 있습니다. 그러나 일부 ASP.NET Core 라우팅 기능은 코드 변환에서 지원되지 않습니다. 여기에는 다음이 포함됩니다.

요청 본문

코드 변환은 요청 본문 JSON을 요청 메시지로 역직렬화합니다. body 필드는 HTTP 요청 본문이 요청 메시지에 매핑하는 방법을 지정합니다. 값은 값이 HTTP 요청 본문에 매핑되는 요청 필드의 이름이거나 모든 요청 필드를 매핑하기 위한 *의 이름입니다.

다음 예제에서 HTTP 요청 본문은 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;
}

쿼리 매개 변수

경로 매개 변수 또는 요청 본문에 바인딩되지 않은 요청 메시지의 모든 필드는 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;
}

앞의 예에서:

org 및 repo 필드는 경로 매개 변수에서 바인딩됩니다.
text 및 page의 중첩 필드와 같은 다른 필드는 쿼리 문자열 ?text=value&page.index=0&page.size=10에서 바인딩할 수 있습니다.

응답 본문

기본적으로 코드 변환은 전체 응답 메시지를 JSON으로 직렬화합니다. response_body 필드를 사용하면 응답 메시지의 하위 집합을 직렬화할 수 있습니다.

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

앞의 예제 address 에서 필드는 응답 본문에 JSON으로 직렬화됩니다.

규격

gRPC 코드 변환 사용자 지정에 대한 자세한 내용은 HttpRule 사양을 참조하세요.

JSON 사용자 지정

메시지는 Protobuf 사양에서 JSON 매핑을 사용하여 JSON으로 변환됩니다. Protobuf의 JSON 매핑은 JSON과 Protobuf 간에 변환하는 표준화된 방법이며 모든 serialization은 이러한 규칙을 따릅니다.

그러나 gRPC JSON 코드 변환은 다음 표와 같이 JSON을 GrpcJsonSettings사용자 지정하기 위한 몇 가지 제한된 옵션을 제공합니다.

옵션	기본값	설명
IgnoreDefaultValues	`false`	`true`로 설정하면 직렬화 중에 기본값이 있는 필드가 무시됩니다.
WriteEnumsAsIntegers	`false`	`true`로 설정하면 열거형 값이 문자열 대신 정수로 작성됩니다.
WriteInt64sAsStrings	`false`	`true`로 설정하면 `Int64` 및 `UInt64` 값이 숫자 대신 문자열로 작성됩니다.
WriteIndented	`false`	설정 `true`하면 JSON은 예쁜 인쇄를 사용하여 작성됩니다. 이 옵션은 줄로 구분된 JSON 메시지를 쓰고 예쁜 인쇄를 사용할 수 없는 스트리밍 메서드에 영향을 주지 않습니다.

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

파일 json_name 에서 .proto 필드 옵션은 다음 예제와 같이 JSON으로 serialize될 때 필드의 이름을 사용자 지정합니다.

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

코드 변환은 고급 JSON 사용자 지정을 지원하지 않습니다. 정확한 JSON 구조 제어가 필요한 앱은 ASP.NET Core Web API 사용을 고려해야 합니다.

다음을 통해 공유