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

작성자: 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 파일은 프로젝트에 있어야 합니다.

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사용자 지정하기 위한 몇 가지 제한된 옵션을 제공합니다.

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 사용을 고려해야 합니다.

추가 리소스

• ASP.NET Core gRPC 앱의 gRPC JSON 코드 변환
• HttpRule 사양