PolyApiIDE работает с gRPC-сервисами через JSON-transcoding: импортирует .proto, помогает собрать тело запроса и разобрать ответ — но нативного gRPC-канала из браузера не открывает.
Начнём с главного, чтобы не вводить в заблуждение: нативный gRPC — это HTTP/2 с трейлерами и бинарным protobuf, и браузерный код такой канал открыть не может. Поэтому gRPC-пространство в PolyApiIDE рассчитано на сервисы, перед которыми стоит JSON-transcoding: шлюз принимает обычный HTTP с JSON и переводит вызов в gRPC.
JSON-transcoding — стандартный приём в gRPC-экосистеме. Метод в .proto получает HTTP-аннотацию (google.api.http), и шлюз начинает принимать на обычный URL JSON-тело, превращая его в protobuf-сообщение. Такой слой есть почти везде: фильтр grpc_json_transcoder в Envoy, grpc-gateway для Go, встроенный JSON transcoding в ASP.NET Core.
Для клиента это выглядит как HTTP-запрос с JSON. Значит, работают все привычные вещи: заголовки, авторизация, окружения, подстановка переменных, QA-проверки, скрипты и сценарии. А .proto нужен затем, чтобы не угадывать имена полей и типы: импорт файла даёт список методов и структуру сообщений.
| Сценарий | В браузере | Комментарий |
|---|---|---|
| Unary-вызов через JSON-шлюз | Да | Обычный HTTP-запрос с JSON-телом |
| Импорт .proto | Да | Методы и структура сообщений, на бесплатном тарифе |
| Нативный gRPC-канал | Нет | Требует HTTP/2-трейлеров, недоступных браузерному коду |
| Server / client streaming | Нет | Нужен серверный инструмент: grpcurl, ghz, Postman-десктоп |
| gRPC-Web без прокси | Нет | gRPC-Web тоже требует прокси перед сервисом |
| Рефлексия сервиса | Нет | Структуру берём из .proto-файла |
Если перед вашим сервисом нет шлюза с JSON-transcoding, браузерный клиент ему не подойдёт — это ограничение платформы, и обходить его мы не пытаемся.
Спросите у команды сервиса, принимает ли он JSON поверх HTTP, и получите базовый URL шлюза. Признак того, что транскодинг настроен, — HTTP-аннотации в .proto и импорт google/api/annotations.proto.
Импорт .proto входит в бесплатный тариф. После него видно список методов и поля сообщений — тело запроса собирается по структуре, а не по памяти.
Метод превращается в POST (реже GET) на путь из аннотации, тело — JSON по схеме сообщения:
POST {{gateway}}/v1/users/42:activate
Content-Type: application/json
{"reason": "manual"}
Токен держите в окружении и подставляйте в заголовок через {{token}}. Иерархия значений та же, что в REST: запрос → коллекция → пространство → окружение, пустые значения не применяются.
Шлюз переводит gRPC-статус в HTTP-код, а детали кладёт в JSON-тело. Соответствие кодов — в таблице ниже, по ней понятно, отказал сам сервис или вызов не прошёл валидацию.
| gRPC-статус | HTTP | Типичная причина |
|---|---|---|
| OK | 200 | Вызов выполнен |
| INVALID_ARGUMENT | 400 | Тело не соответствует сообщению из .proto |
| UNAUTHENTICATED | 401 | Нет токена или он просрочен |
| PERMISSION_DENIED | 403 | Токен есть, прав не хватает |
| NOT_FOUND | 404 | Нет объекта — или метод не описан в аннотациях шлюза |
| RESOURCE_EXHAUSTED | 429 | Сработал лимит |
| UNIMPLEMENTED | 501 | Метод не реализован или не проброшен через шлюз |
| UNAVAILABLE | 503 | Сервис за шлюзом недоступен |
| DEADLINE_EXCEEDED | 504 | Вызов не успел за отведённое время |
Пара 404 и 501 — самая частая подсказка: обычно это значит, что метод существует в .proto, но HTTP-аннотация для него не прописана.
Из браузера — нет. Нативный gRPC требует управления HTTP/2-трейлерами, к которым у кода на странице нет доступа. Мы пишем об этом прямо, вместо того чтобы обещать «gRPC в браузере» и оставлять разбираться на месте.
Чтобы знать методы и структуру сообщений. JSON-тело для транскодинга строится ровно по полям protobuf-сообщения, и список полей избавляет от угадывания имён и типов.
Server- и client-streaming в браузерном клиенте недоступны. Для них берите серверные инструменты — grpcurl или ghz. Если нужен живой поток именно из браузера, посмотрите в сторону WebSocket или SSE: оба поддерживаются.
Для импорта .proto и отправки вызовов — нет, это Free. Платные тарифы добавляют автоматизацию: сценарии, нагрузочные профили, PDF-отчёты и патчи коллекций.