gRPC API 명세서

본 섹션에서는 MORAI SIM에서는 사용하는 gRPC API의 세부 항목을 설명하는 API 명세서에 대하여 다룬다.

→ gRPC API 명세서 바로 가기

22.R4.0 gRPC API 개선 사항

22.R4.0에서 배포한 MORAI Standard Proto는 MORAI Simulator의 서비스 카테고리 별로 RPC와 Message를 가지는 구조를 가진다.

MORAI Standard Proto는 아래와 같은 서비스 타입 별로 구성된다.

22.R4.0 gRPC API은 아래와 같은 특징을 갖는 MORAI Standard Proto로 통합함

• MORAI Simulator의 서비스 카테고리 별로 RPC와 Message를 분류함

• Standard Proto 통합과 함께 RPC의 체계적인 관리를 위한 재구조화

• 메세지는 객체 단위로 분리

  • 확장성을 고려하여 message들을 각각의 성격에 부합하는 객체 단위로 분리

22.R4.0 gRPC Proto 구조

gRPC API는 아래와 같은 Proto 파일을 단위로 구성된다.

각 Proto 파일은 ‘Service > Procedure(RPC) > Message’ 순서의 계층적 구조를 갖는다.

Procedure 항목에서는 사용자가 호출할 수 있는 Remote Procedure에 대해서 카테고리를 나누어서 설명하고, Message 항목에서는 Procedure 정의 시 사용하는 Message들에 대해서 카테고리를 나누어서 설명한다.

syntax = "proto3";
package sample_msgs;
service SampleService {
    rpc FindPersonUnary (Person) returns (Person) { }
    rpc FindPersonStream (stream Person) returns (stream Person) { }
}

message Person {
    required string user_name        = 1;
    optional int64  favourite_number = 2;
    repeated string interests        = 3;
}

enum StatusCode {
	SUCCESS = 0;
	UNKNOWN_FAILURE = 1;  
}

• syntax

  • 위 예제에서는 proto3를 지정하여 version3의 규약을 따르겠다고 선언했습니다. 이를 명시하지 않으면 기본으로는 version2 문법을 따르게 됩니다. 버전에 따라 지원 언어와 문법에도 차이가 나타납니다. proto3가 지원 언어가 더 많고 새로운 기능 지원을 위해 proto3를 사용할 것을 권장합니다.

• message와 field

  • Proto파일은 주고 받는 데이터를 message라고 정의합니다. 그리고 이 메시지는 여러 타입의 field로 구성되며, 각 field는 고유한 번호를 가지게 됩니다. field 번호는 최소 1, 최대 536,870,911로 지정 가능하며, 19000~19999는 프로토콜 버퍼 구현을 위해 예약된 값이므로 사용할 수 없습니다.

  • 네이밍 이름은 PascalCase, 필드 이름은 snake_case로 사용할 것을 권장하고 있으며, 필드 이름은 숫자로 시작할 수 없습니다.

• package

  • package는 message 이름을 중첩 없이 구분할 때 사용합니다.

• service

  • service는 RPC를 통해 서버가 클라이언트에게 제공할 함수를 정의합니다. 기본적으로는 단방향(클라이언트 요청 서버 응답)으로 동작하지만 stream 옵션을 줘서 스트리밍을 구현할 수 있습니다.

• enum

  • enum은 상수를 저장하는 열거형 데이터입니다.