grpcurl

KO | EN

gitlite — search

#javascript #react #ai #android #linux #java #nodejs #awesome #cli #kubernetes #awesome-list #security #openai #open-source

(★ 12,782)

cURL과 같지만 gRPC를 위한 도구: gRPC 서버와 상호작용하기 위한 명령줄 도구

파일 탐색기

최종 버전 다운로드 (.zip)

- config.yml
- - codesee-arch-diagram.yml
- dependabot.yml
- - grpcurl.go
  - indent_test.go
  - unix.go
- - example.proto
  - example.protoset
  - example2.proto
  - test.pb.go
  - test.proto
  - test.protoset
  - test_grpc.pb.go
  - test_server.go
- do-release.sh
- README.md
- RELEASE_NOTES.md
- README.md
- snapcraft.yaml
.gitignore
.goreleaser.yml
desc_source.go
desc_source_test.go
Dockerfile
download_protoc.sh
format.go
format_test.go
go.mod
go.sum
grpcurl.go
grpcurl_test.go
invoke.go
LICENSE
Makefile
mk-test-files.sh
README.md
tls_settings_test.go

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# gRPCurl
[![Build Status](https://circleci.com/gh/fullstorydev/grpcurl/tree/master.svg?style=svg)](https://circleci.com/gh/fullstorydev/grpcurl/tree/master)
[![Go Report Card](https://goreportcard.com/badge/github.com/fullstorydev/grpcurl)](https://goreportcard.com/report/github.com/fullstorydev/grpcurl)
[![Snap Release Status](https://snapcraft.io/grpcurl/badge.svg)](https://snapcraft.io/grpcurl)

`grpcurl`은 gRPC 서버와 상호작용할 수 있게 해주는 커맨드 라인 도구입니다.
기본적으로 gRPC 서버를 위한 `curl`이라고 생각하시면 됩니다.

이 도구의 주된 목적은 커맨드 라인에서 gRPC 서버의 RPC 메서드를 호출하는 것입니다. gRPC 서버는 통신 시 바이너리 인코딩([protocol buffers](https://developers.google.com/protocol-buffers/), 줄여서 "protobufs")을 사용합니다. 따라서 일반적인 `curl`로는 상호작용하는 것이 거의 불가능합니다 (HTTP/2를 지원하지 않는 이전 버전의 `curl`은 당연히 사용할 수 없습니다). 이 프로그램은 JSON 인코딩을 사용하는 메시지를 허용하므로 인간과 스크립트 모두에게 훨씬 더 친숙합니다.

이 도구를 사용하면 [server reflection](https://github.com/grpc/grpc/blob/master/src/proto/grpc/reflection/v1/reflection.proto)을 지원하는 서버에 쿼리를 보내거나, proto 소스 파일을 읽거나, 또는 컴파일된 "protoset" 파일(인코딩된 파일 [descriptor protos](https://github.com/google/protobuf/blob/master/src/google/protobuf/descriptor.proto)가 포함된 파일)을 로드하여 gRPC 서비스의 스키마를 탐색할 수 있습니다.
실제로 이 도구가 JSON 요청 데이터를 바이너리 인코딩된 protobuf로 변환하는 방식도 바로 이 동일한 스키마를 사용하는 것입니다. 따라서 상호작용하려는 서버가 reflection을 지원하지 않는 경우, 서비스를 정의하는 proto 소스 파일이나 `grpcurl`이 사용할 수 있는 protoset 파일이 필요합니다.

이 저장소는 또한 동적으로 gRPC 엔드포인트를 호출하는 다른 커맨드 라인 도구의 제작을 단순화하는 함수들을 포함하는 라이브러리 패키지인 `github.com/fullstorydev/grpcurl`을 제공합니다. 이 코드는 [protoreflect](https://godoc.org/github.com/jhump/protoreflect) 라이브러리의 다양한 패키지를 사용하는 방법을 보여주는 훌륭한 예시이며, 그 기능들을 잘 보여줍니다.

[GopherCon 2018의 `grpcurl` 발표](https://www.youtube.com/watch?v=dDr-8kbMnaw)도 참고하세요.

## 특징
`grpcurl`은 스트리밍 메서드를 포함한 모든 종류의 RPC 메서드를 지원합니다. 대화형 터미널에서 `grpcurl`을 실행하고 표준 입력(stdin)을 요청 본문으로 사용하면 양방향 스트리밍 메서드도 대화형으로 조작할 수 있습니다!

`grpcurl`은 보안/TLS 서버와 평문 서버(즉, TLS 없음)를 모두 지원하며, TLS 설정을 위한 수많은 옵션을 제공합니다. 또한 클라이언트가 클라이언트 인증서를 제시해야 하는 상호 TLS(mutual TLS)도 지원합니다.

앞서 언급했듯이, 서버가 reflection 서비스를 지원하는 경우 `grpcurl`은 원활하게 작동합니다. 그렇지 않은 경우 `.proto` 소스 파일을 제공하거나 `grpcurl`에 protoset 파일(컴파일된 디스크립터가 포함되어 있고 `protoc`로 생성된 파일)을 제공할 수 있습니다.

## 설치

### 바이너리

[releases](https://github.com/fullstorydev/grpcurl/releases) 페이지에서 바이너리를 다운로드하세요.

### Homebrew (macOS)

macOS에서는 Homebrew를 통해 `grpcurl`을 설치할 수 있습니다:
```shell
brew install grpcurl
```

### Docker

Docker를 지원하는 플랫폼의 경우, `grpcurl`을 실행할 수 있는 이미지를 다운로드할 수 있습니다:
```shell
# Download image
docker pull fullstorydev/grpcurl:latest
# Run the tool
docker run fullstorydev/grpcurl api.grpc.me:443 list
```
Docker를 사용할 때 몇 가지 주의사항이 있습니다:
- 호스트의 루프백 네트워크에서 수신 대기 중인 서버와 통신해야 하는 경우, `localhost` 대신 호스트를 `host.docker.internal`로 지정해야 하며(Mac 또는 Windows의 경우), _또는_ 컨테이너가 `-network="host"`를 사용하여 호스트 네트워크를 사용하도록 해야 합니다(Linux 전용).
- proto 소스 파일이나 디스크립터 세트를 제공해야 하는 경우, 파일이 포함된 폴더를 볼륨으로 마운트하고(`-v $(pwd):/protos`), 그에 따라 import 경로를 컨테이너 경로로 조정해야 합니다.
- `-d @` 옵션을 사용하여 표준 입력(stdin)을 통해 요청 메시지를 전달하려면, docker 명령어에 `-i` 플래그를 사용해야 합니다.

### 기타 패키지

서드파티에서 생성한 레시피/패키지 지원 덕분에 `grpcurl`을 설치할 수 있는 수많은 다른 방법이 있습니다. 여기에는 Windows와 수많은 Linux 배포판을 포함한 다양한 환경에서 `grpcurl`을 설치하는 다른 방법들이 포함됩니다.

`grpcurl`에 대한 더 자세한 내용과 전체 기타 패키지 목록은 _repology.org_에서 확인할 수 있습니다:
https://repology.org/project/grpcurl/information

### Snap

snap 패키지를 사용하여 `grpcurl`을 설치할 수 있습니다:

`snap install grpcurl`

### 소스에서 직접 설치
[Go SDK](https://golang.org/doc/install)가 이미 설치되어 있는 경우, `go` 도구를 사용하여 `grpcurl`을 설치할 수 있습니다:
```shell
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
```

이렇게 하면 `$GOPATH` 환경 변수가 가리키는 곳의 `bin` 하위 폴더에 명령어가 설치됩니다. (`GOPATH` 환경 변수가 설정되어 있지 않은 경우, 기본 설치 위치는 `$HOME/go/bin`입니다). 이 디렉토리가 이미 `$PATH`에 포함되어 있다면 바로 사용할 수 있습니다.

이미 이 저장소를 `$GOPATH`에 포함되지 않은 위치로 다운로드했고 소스에서 빌드하려는 경우, 저장소 디렉토리로 이동(`cd`)한 후 `make install`을 실행하면 됩니다.

컴파일 오류가 발생하고 Go SDK 1.13 이전 버전을 사용하는 경우, `grpcurl`의 종속성이 오래되었을 수 있습니다. `make updatedeps`를 실행하여 종속성을 업데이트할 수 있습니다. 또는 Go 1.11 또는 1.12를 사용하는 경우, 위 명령어 앞에 접두사로 `GO111MODULE=on`을 추가하면 (`GOPATH`에 이미 있을 수 있는 것 대신) 올바른 버전의 종속성을 사용하여 빌드할 수 있습니다.

## 사용법
이 도구의 사용법 문서는 수많은 옵션을 설명합니다:
```shell
grpcurl -help
```

아래 섹션에서는 `grpcurl` 사용 방법을 보여주는 수많은 예제를 확인할 수 있습니다.

### RPC 호출
신뢰할 수 있는 서버(예: 자체 서명된 키나 커스텀 CA가 없는 TLS)에서 클라이언트 인증서가 필요 없고 서버 리플렉션을 지원하는 RPC를 호출하는 것은 `grpcurl`로 할 수 있는 가장 간단한 작업입니다. 이 최소한의 호출은 빈 요청 본문을 전송합니다:
```shell
grpcurl grpc.server.com:443 my.custom.server.Service/Method

# no TLS
grpcurl -plaintext grpc.server.com:80 my.custom.server.Service/Method
```

비어 있지 않은 요청을 보내려면 `-d` 인수를 사용하십시오. 모든 인수는 서버 주소와 메서드 이름 *앞에* 와야 합니다:
```shell
grpcurl -d '{"id": 1234, "tags": ["foo","bar"]}' \
    grpc.server.com:443 my.custom.server.Service/Method
```

예제에서 볼 수 있듯이, 제공된 본문은 JSON 형식이어야 합니다. 본문은 구문 분석된 후 protobuf 바이너리 형식으로 서버에 전송됩니다.

`jq`를 사용하는 경우처럼 `grpcurl`을 명령어 파이프라인에 포함하여 요청 본문을 생성하려는 경우, `-d @`를 사용할 수 있습니다. 이는 `grpcurl`에게 표준 입력(stdin)에서 실제 요청 본문을 읽어오도록 지시합니다:
```shell
grpcurl -d @ grpc.server.com:443 my.custom.server.Service/Method <<EOM
{
  "id": 1234,
  "tags": [
    "foo",
    "bar"
  ]
}
EOM
```
### 요청에 헤더/메타데이터 추가하기
`-H name:value` 명령 라인 옵션을 통해 rpc 요청에 헤더와 메타데이터를 추가할 수 있습니다. 이와 유사한 방식으로 여러 헤더를 추가할 수 있습니다.
예시:
```shell
grpcurl -H header1:value1 -H header2:value2 -d '{"id": 1234, "tags": ["foo","bar"]}' grpc.server.com:443 my.custom.server.Service/Method
```
더 많은 사용법 가이드는 `grpcurl -help`를 통해 도움말 문서를 확인하세요.

### 서비스 목록 조회
서버가 노출하는 모든 서비스 목록을 보려면 "list" 동사를 사용합니다. 서버 리플렉션 대신 `.proto` 소스나 protoset 파일을 사용하는 경우, 이는 소스 또는 protoset 파일에 정의된 모든 서비스 목록을 보여줍니다.
```shell
# 서버가 리플렉션을 지원하는 경우
grpcurl localhost:8787 list

# 컴파일된 protoset 파일을 사용하는 경우
grpcurl -protoset my-protos.bin list

# proto 소스를 사용하는 경우
grpcurl -import-path ../protos -proto my-stuff.proto list

# proto 파일 내보내기 (-proto-out-dir을 사용하여 출력 디렉토리 지정)
grpcurl -plaintext -proto-out-dir "out_protos" "localhost:8787" describe my.custom.server.Service

# protoset 파일 내보내기 (-protoset-out을 사용하여 출력 파일 지정)
grpcurl -plaintext -protoset-out "out.protoset" "localhost:8787" describe my.custom.server.Service

```

또한 "list" 동사를 사용하면 특정 서비스에 있는 모든 메서드를 볼 수 있습니다:
```shell
grpcurl localhost:8787 list my.custom.server.Service
```

### 요소 설명 조회
"describe" 동사는 서버가 알고 있거나 주어진 protoset 파일에서 찾을 수 있는 모든 심볼의 타입을 출력합니다. 또한 proto 소스의 스니펫 형태로 해당 심볼에 대한 설명을 출력합니다. 요소를 정의한 원래 소스와 정확히 일치하지 않을 수는 있지만, 동등한 내용을 출력합니다.

```shell
# 서버가 리플렉션을 지원하는 경우
grpcurl localhost:8787 describe my.custom.server.Service.MethodOne

# 컴파일된 protoset 파일을 사용하는 경우
grpcurl -protoset my-protos.bin describe my.custom.server.Service.MethodOne

# proto 소스를 사용하는 경우
grpcurl -import-path ../protos -proto my-stuff.proto describe my.custom.server.Service.MethodOne
```

## 디스크립터 소스
`grpcurl` 도구는 다양한 디스크립터 소스를 기반으로 작동할 수 있습니다. `grpcurl`이 RPC 스키마를 이해하고, 입력을 protobuf 바이너리 형식으로 변환하며, 바이너리 형식의 응답을 텍스트로 변환하기 위해 디스크립터가 필요합니다. 아래 섹션에서는 지원되는 소스와 이를 사용하는 데 필요한 명령 라인 플래그에 대해 설명합니다.

### 서버 리플렉션

추가적인 명령 라인 플래그 없이, `grpcurl`은 [서버 리플렉션](https://github.com/grpc/grpc/blob/master/src/proto/grpc/reflection/v1/reflection.proto)을 사용하려고 시도합니다.

서버 리플렉션을 설정하는 방법에 대한 예시는 [여기](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md#known-implementations)에서 확인할 수 있습니다.

리플렉션을 사용할 때는 `grpcurl`이 서버에 연결하여 디스크립터를 요청할 수 있도록 "list" 및 "describe" 작업에서도 서버 주소(host:port 또는 Unix 소켓 경로)가 필요합니다.

### Proto 소스 파일
리플렉션을 지원하지 않는 서버에서 `grpcurl`을 사용하려면 `.proto` 소스 파일을 사용할 수 있습니다.

`grpcurl`에 관련 proto 소스 파일을 지정하기 위해 `-proto` 플래그를 사용하는 것 외에도, 종속성을 가져올 폴더를 `grpcurl`에 알려주기 위해 `-import-path` 플래그를 제공해야 할 수도 있습니다.

`protoc`로 컴파일할 때와 마찬가지로, `protoc`에 포함된 표준 proto들의 위치(패키지 정의가 `google.protobuf`인 다양한 "well-known types"를 포함함)에 대해 import 경로를 제공할 필요가 *없습니다*. 디스크립터의 스냅샷이 `grpcurl` 바이너리에 내장되어 있으므로 이러한 파일들은 `grpcurl`에 의해 "알려져" 있습니다.

proto 소스를 사용할 때는 "list" 및 "describe" 작업이 proto 소스 파일만 참조하면 되기 때문에 서버 주소(host:port 또는 Unix 소켓 경로)를 생략할 수 있습니다.

### Protoset 파일
`grpcurl`에서 컴파일된 protoset 파일을 사용할 수도 있습니다. `grpcurl`을 스크립트에서 사용하고 여러 번 호출할 때 동일한 proto 소스를 재사용해야 하는 경우, protoset 파일을 사용하면 (호출할 때마다 발생하는 파싱 및 컴파일 단계를 건너뛰므로) 더 나은 성능을 얻을 수 있습니다.

Protoset 파일에는 바이너리로 인코딩된 `google.protobuf.FileDescriptorSet` proto가 포함되어 있습니다. protoset 파일을 생성하려면 서비스를 정의하는 `*.proto` 파일과 함께 `protoc`를 실행하세요.
```shell
protoc --proto_path=. \
    --descriptor_set_out=myservice.protoset \
    --include_imports \
    my/custom/server/service.proto
```

`--descriptor_set_out` 인자는 `protoc`에 protoset을 생성하도록 지시하는 역할을 하며, `--include_imports` 인자는 protoset이 `grpcurl`이 스키마를 처리하고 이해하는 데 필요한 모든 것을 포함하도록 하는 데 필수적입니다.

protoset을 사용할 때는 "list" 및 "describe" 작업이 protoset 파일만 참조하면 되기 때문에 서버 주소(host:port 또는 Unix 소켓 경로)를 생략할 수 있습니다.

grpcurl

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

grpcurl

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README