# gRPC (/ru/docs/requests/grpc)

Запрос gRPC вызывает один метод сервиса. Вы пишете сообщение в виде JSON; Echolot кодирует его по описанию сервиса,
отправляет по HTTP/2 и показывает ответ в виде JSON вместе со статусом вызова.

<Shot id="requests-grpc-message" alt="Inventory › Reserve stock: вкладка «Сообщение» с inventory.proto, сервисом Inventory и методом Reserve, unary, сообщение в JSON и ответ со статусом OK и одним сообщением" />

<Callout title="Попробуйте на Alpenglow">
  Запросы папки **Inventory** вызывают сервер gRPC на `localhost:50051`. Он лежит в папке `examples/servers` репозитория
  документации (`bun run grpc`).
</Callout>

## Создание запроса gRPC [#create-a-grpc-request]

Выберите **Файл › Новый запрос gRPC** или **Новый запрос gRPC** в меню **+** рядом с **Запросы** в боковой панели.
Адрес — это сервер, например `http://localhost:50051` (в Alpenglow — `{{grpcURL}}`), без пути.

В редакторе есть вкладки: **Документация**, **Сообщение**, **Заголовки**, **Авторизация**, **Переменные**, **Тесты**,
**Скрипты** и **Настройки**. Заголовки — это метаданные вызова. Вызовы gRPC всегда используют POST, поэтому вместо
метода на значке написано **gRPC**.

## Описание сервиса [#describe-the-service]

Вкладка **Сообщение** начинается с того, где описаны сервисы:

- Файл `.proto` в папке `specs/` рабочего пространства, например `specs/inventory.proto`. Его импорты читаются рядом с
  ним, а известные типы `google.protobuf` файла не требуют. Файлы `.proto` добавляются и редактируются на странице
  «Спецификации»: см. [файлы proto](/docs/specs/proto-files).
- **Рефлексия сервера**: Echolot запрашивает у сервера его сервисы. Сервер должен предоставлять сервис рефлексии.
  Вызов рефлексии идёт на адрес запроса с его заголовками, авторизацией и переменными.

Выберите **Загрузить**, чтобы прочитать сервисы. Затем выберите сервис и метод. Рядом с методом Echolot показывает его
вид: **unary**, **server streaming**, **client streaming** или **bidirectional streaming**.

<Callout>
  Быстрее начать с файла `.proto` на странице «Спецификации»: его структура перечисляет все методы, и у каждого есть
  кнопка, которая создаёт для него запрос gRPC с примером сообщения.
</Callout>

## Запись сообщения [#write-the-message]

Сообщение — это JSON в JSON-отображении protobuf, с `{{variables}}`:

```json
{
  "sku": "TNT-MH-2P",
  "quantity": 1,
  "order_id": "{{orderId}}"
}
```

**Пример** заменяет сообщение полями входного типа метода со значениями-примерами, включая вложенные сообщения, —
чтобы было с чего начать.

В JSON-отображении 64-битные целые — строки, bytes — Base64, enum — их имена, map — объекты, а `Timestamp`, `Duration`,
`FieldMask`, обёртки, `Struct` и `Any` имеют свои обычные формы JSON. Ключ, которого нет у типа сообщения, отклоняется,
так что опечатка не останется незамеченной.

## Виды вызовов [#call-kinds]

| Вид | Сообщение, которое вы пишете | Ответ |
| --- | --- | --- |
| Unary | Один объект JSON | Один объект JSON |
| Server streaming | Один объект JSON | Массив JSON из всех сообщений, которые прислал сервер |
| Client streaming | Массив JSON из сообщений | Один объект JSON |
| Bidirectional streaming | Массив JSON из сообщений | Массив JSON из всех сообщений, которые прислал сервер |

Для **Inventory › Watch stock**, вызова server streaming, сообщение называет товары для наблюдения, а ответ — это список
уровней запасов, которые прислал сервер.

## Статус, метаданные и трейлеры [#status-metadata-and-trailers]

gRPC сообщает, как прошёл вызов, в своём статусе, который приходит в трейлерах после сообщений. Сводка ответа
показывает его: `OK` зелёным или статус с кодом красным, например `NOT_FOUND (5)`, а также число полученных сообщений и
их сжатие. Вкладка **Заголовки** ответа показывает заголовки ответа.

Чтобы проверять статус в тестах, добавьте проверку **Статус gRPC** на вкладке **Тесты**: по умолчанию она равна `OK` и
принимает имена (`NOT_FOUND`) или коды (`5`). См. [скрипты и тесты](/docs/requests/scripts-and-tests).

## Сжатие и срок [#compression-and-deadline]

Значок **gRPC** перед адресом — это меню:

- **Сжимать сообщения**: **Нет**, **gzip** или **deflate**. Сжатые ответы читаются всегда, что бы здесь ни было выбрано.
- **Срок**: **Без ограничения** или 500 мс, 1 с, 5 с, 30 с. Срок передаётся серверу, и вызов, который его превысил,
  завершается с `DEADLINE_EXCEEDED`.

## TLS и сертификаты [#tls-and-certificates]

Адрес `http://` вызывает сервер по HTTP/2 без TLS. Адрес `https://` использует TLS с правилами сертификатов рабочего
пространства, так что пользовательские сертификаты CA и клиентские сертификаты работают. См.
[настройки запроса](/docs/requests/settings).

## Из командной строки [#from-the-command-line]

`echolot grpc describe` перечисляет сервисы и методы сервера, а `echolot grpc call` выполняет вызов и завершается с кодом
1 при статусе, отличном от `OK`. См. [echolot grpc](/docs/cli/grpc).