gRPC - это современный высокопроизводительный фреймворк для удалённого вызова процедур, разработанный компанией Google. Он использует HTTP/2 в качестве транспорта и Protocol Buffers (Protobuf) в качестве формата сериализации данных
Думаю, с HTTP/2 не должно быть особых вопросов: это всем известный протокол HTTP, только более современной, второй версии ("в интернете" мы обычно используем версию 1.1.). gRPC использует HTTP/2 и его новые фишки для быстрой и оптимальной передачи сообщений в формате Protobuf
Protobuf же, в свою очередь, это формат данных, в который сериализуются все сообщения между клиентом и сервером gRPC. Он бинарный, что означает, с одной стороны, невозможность прочесть его человеком (как, например, JSON), но с другой - компактность и более быструю программную обработку при отправке и получении
gRPC крайне хорош и наиболее часто встречаем в системах с микросервисной архитектурой. Вставьте сюда шутку про монолит. Благодаря скорости работы, а также некоторым другим особенностям, которые мы затронем далее, его обычно используют для организации быстрого обмена данными между разрозненными сервисами в рамках одной системы. gRPC может быть использован и для организации публичных API, но это встречается гораздо реже: двоичный формат Protobuf сложнее отлаживать, да и в целом протокол не так распространен, как классический HTTP с JSON или XML сообщениями
Про proto-файлы
Отличительной особенностью gRPC, которая сразу бросается в глаза и с которой вы столкнетесь тут же, как только начнете работу, это proto-файлы
Proto - это схема, которая описывает все функции и форматы сообщений, доступные при обращении к конкретному серверу gRPC. Это похоже на WSDL или, в меньшей степени, на XSD (XML схемы), т.е. является контрактом, однозначно определяющим, что сервер готов принять в качестве запроса и что вернет в ответ. Выглядит он следующим образом:
syntax = "proto3";
package user;
service UserService {
rpc GetUser (UserRequest) returns (UserResponse);
rpc ListUsers (ListRequest) returns (stream UserResponse);
}
message UserRequest {
string user_id = 1;
}
message UserResponse {
string user_id = 1;
string name = 2;
string email = 3;
}
message ListRequest {
int32 page = 1;
}
Давайте разберем, что тут происходит:
- syntax = "proto3" - указание на версию синтаксиса. Сейчас актуальна третья версия, которая проще и чище второй
- package - это как пространство имен. Помогает избежать конфликтов, если у вас много разных proto-файлов
- service - описание сервиса, т.е. набора методов, которые можно вызвать. В нашем случае это UserService с двумя методами: GetUser и ListUsers
- message - это структура данных. Аналог JSON-объекта или структуры в 1С. Каждое поле имеет тип, имя и уникальный номер (это важно для сериализации)
- rpc - описание конкретного метода: что принимает на вход и что возвращает
Также вы могли заметить слово stream в определении ListUsers, но о нем поговорим чуть позже, когда дойдем до потоковых вызовов
Типы данных в Protobuf
Сообщение gRPC до преобразования в двоичный вид немного напоминает JSON. Однако, в отличии от последнего, в proto есть свой, более широкий, набор типов данных и строгая типизация для всех определяемых полей. Список основных типов состоит из:
- string - строки
- int32, int64 - целые числа
- double, float - числа с плавающей точкой
- bool - булево значение
- bytes - двоичные данные
- message - это когда другая структура выступает типом данных для поля текущей
Кроме этого, также встречается ключевое слово repeated. Это не то чтобы полноценный тип, но указатель, показывающий, что значений указанного типа может быть несколько. Можно сказать, что это массив значений. Например:
repeated string tags = 4;
То есть несколько значений типа "Строка" в поле tags
Типы вызовов в gRPC
А теперь к самому интересному - способам передачи данных. В отличие от обычного REST API, где у нас есть просто "запрос-ответ", gRPC предлагает целых четыре варианта взаимодействия между клиентом и сервером:
1. Унарный вызов (Unary RPC)
Самый простой вызов - один запрос, один ответ. Такой же, как и в обычном HTTP:
rpc GetUser (UserRequest) returns (UserResponse);
Здесь клиент отправляет запрос к сервису GetUser с сообщением типа UserRequest, поля которого описаны где-то в другом месте proto-файла. Сервер же обрабатывает это и возвращает в ответ объект (структуру) UserResponse
2. Серверный поток (Server Streaming)
Клиент отправляет один запрос, а сервер возвращает поток ответов:
rpc ListUsers (ListRequest) returns (stream UserResponse);
Это удобно, когда сервер должен вернуть большой объем данных, который лучше передавать частями. Например, список всех пользователей системы - вместо того, чтобы ждать формирования огромного массива данных, сервер может отправлять информацию по мере ее получения из базы. А клиент может начать обрабатывать, не дожидаясь полного окончания обмена
3. Клиентский поток (Client Streaming)
Обратная ситуация - клиент отправляет несколько запросов, сервер возвращает один ответ:
rpc UploadData (stream DataChunk) returns (UploadResponse);
Полезно для загрузки больших файлов или массовой отправки данных. Вместо того, чтобы паковать все в один гигантский запрос, можно отправлять необходимую информацию порциями. Ничего сложного, но важно отметить, что момент завершения получения со стороны сервера в proto-файле не регламентирован. Т.е., в зависимости от ситуации, сервер может как сам закрыть поток, получив нужное ему количество информации, так и ожидать сигнала о явном завершении от клиента. Все это зависит исключительно от логики, реализованной на сервере
4. Двунаправленный поток (Bidirectional Streaming)
Самый мощный вариант - и клиент, и сервер могут отправлять потоки данных независимо друг от друга:
rpc Chat (stream Message) returns (stream Message);
Классический пример - чаты или любое другое real-time взаимодействие. Обе стороны могут отправлять сообщения в любой момент, не дожидаясь ответа на предыдущее. Порядок обмена здесь также регламентирован только внутренней логикой сервера
Импорт proto-файлов
Кроме всего прочего, proto-файлы можно импортировать друг в друга, чтобы переиспользовать общие типы. Это работает примерно как подключение модулей в языках программирования
Допустим, у нас есть файл common.proto с общими типами:
syntax = "proto3";
package common;
message Pagination {
int32 page = 1;
int32 page_size = 2;
}
message Address {
string country = 1;
string city = 2;
string street = 3;
}
Теперь в user.proto можем их использовать:
syntax = "proto3";
package user;
import "common.proto";
service UserService {
rpc ListUsers (ListUsersRequest) returns (stream UserResponse);
}
message ListUsersRequest {
common.Pagination pagination = 1;
}
message UserResponse {
string user_id = 1;
string name = 2;
common.Address address = 3;
}
Ключевые моменты:
- import "common.proto" - импортирует файл. Путь указывается относительно корневой директории proto-файлов (далее мы будем говорить про 1С - там это не будет иметь значения)
- common.Pagination - используем импортированный тип через имя пакета. Это позволяет избежать конфликтов имен.
- Если в импортируемом файле есть свои импорты, они подтягиваются автоматически - явно импортировать их не нужно, если вы не используете типы из них напрямую.
gRPC в 1С
Теперь к практике. К сожалению, встроенными средствами 1С реализовать обмен через gRPC нельзя: в теории, можно было бы реализовать protobuf через работу с двоичными данными, но поддержки HTTP/2 для отправки все равно нет. Но зато готовые методы, основанные на внешней компоненте, есть в Открытом пакете интеграций!
Открытый пакет интеграций - это бесплатное и с открытым исходным кодом расширение, представляющее из себя набор общих модулей для работы с разнообразными онлайн-сервисами и технологиями
Узнать больше:
Репозиторий на Github | Основная статья на Инфостарт | Документация
Начало работы
При начале работы с библиотекой gRPC нужно создать соединение с сервером. Здесь есть два варианта. Вариант номер один: открыть соединение один раз явно, получить объект внешней компоненты, и потом передавать его в остальные функции библиотеки для выполнения запросов. Второй вариант - просто передать настройки соединения прямо в функцию запроса. В таком случае соединение откроется и закроется прямо внутри выполняемой функции. Второй вариант удобен для разовых вызовов, первый - когда нужно сделать несколько операций подряд, не открывая новое соединение на каждую из них.
Настройки соединения формируются через функцию ПолучитьПараметрыСоединения(). Ей нужно передать адрес сервера, Proto-файлы и, если надо, метаданные:
Адрес = "https://grpcb.in:9001";
Proto1 = "C:/grpcbin_with_import.proto";
Proto2 = "C:/mt.proto";
Схемы = Новый Соответствие;
Схемы.Вставить("main.proto" , Proto1);
Схемы.Вставить("my_types.proto", Proto2);
Мета = Новый Структура("mykey", "myvalue");
Параметры = OPI_GRPC.ПолучитьПараметрыСоединения(Адрес, Схемы, Мета);
Tls = OPI_GRPC.ПолучитьНастройкиTls(Истина);
Соединение = OPI_GRPC.ОткрытьСоединение(Параметры, Tls);
Proto-файлы схемы можно передавать по-разному: строкой с содержимым, в виде пути к файлу на диске или как URL к файлу в интернете. Если у вас один файл без импортов, можно просто передать значение - библиотека сама обернет его в коллекцию. А если файлов несколько, и они импортируют друг друга, тогда нужно явно указать имя каждого в ключе соответствия - эти имена будут использоваться в директивах import. Порядок указания файлов, при этом, не важен
Обработка запросов
Выполнение простого унарного вызова выглядит следующим образом:
Запрос = Новый Структура;
Запрос.Вставить("user_id", "12345");
Tls = OPI_GRPC.ПолучитьНастройкиTls(Истина);
Параметры = OPI_GRPC.ПолучитьПараметрыСоединения(Адрес, Proto);
Результат = OPI_GRPC.ВызватьМетод(Параметры, "UserService", "GetUser", Запрос, 10000, Tls);
Здесь ничего сложного: формируем сообщение запроса в виде структуры, формируем настройки соединения (или открываем соединение явно), после чего вызываем функцию ВызватьМетод с этими данными плюс именем сервиса и необходимого метода
С потоками уже интереснее. Библиотека поддерживает все типы потоковой передачи данных, которые мы рассматривали ранее. Для каждого типа есть два способа работы: можно управлять всем вручную (больше контроля, но больше кода) или использовать готовые функции, которые все сделают сами - потоково обработают переданный массив сообщений и/или также потоково примут ответы, вернув единый сформированный результат (проще, но менее гибко)
Здесь я покажу только двунаправленный поток. Описание и примеры остальных потоков, а также других функции ОПИ, всегда доступно в онлайн-документации
Дополнительные особенности
Кроме непосредственно обработки запросов, вы также можете узнать, какие сервисы и методы доступны на сервере при помощи функций ПолучитьСписокСервисов, ПолучитьСписокМетодов и ПолучитьМетод:
Сервисы = OPI_GRPC.ПолучитьСписокСервисов(Соединение);
Методы = OPI_GRPC.ПолучитьСписокМетодов(Соединение, "UserService");
Информация = OPI_GRPC.ПолучитьМетод(Соединение, "UserService", "GetUser");
Также в библиотеке реализована работа с метаданными. Метаданные - это как заголовки в HTTP. Здесь их можно устанавливать и менять на лету:
НовыеМетаданные = Новый Соответствие;
НовыеМетаданные.Вставить("authorization", "Bearer token123");
НовыеМетаданные.Вставить("x-custom-header", "value");
OPI_GRPC.УстановитьМетаданные(Соединение, НовыеМетаданные);
В заключение
gRPC - это мощная технология, которая при правильном применении может значительно ускорить обмен данными между системами. Да, она сложнее REST API и требует больше подготовки. Но если у вас есть реальная потребность в производительности или вы вынуждены работать с уже существующим gRPC сервисом - ничего страшного в нем нет
А на этом все! Напомню, что Открытый пакет интеграций - это не только сегодняшнее обновление для работы с gRPC, но функционал для работы с уже более 30-ю разнообразными сервисами и технологиями, доступный в 3-х независимых вариантах: расширения 1С, пакета для OneScript и даже полноценного консольного приложения для Windows и Linux. Там всегда найдется что-нибудь интересное!
Ссылки на остальные ресурсы Открытого пакета интеграций будут ниже
Спасибо за внимание!
Если вам нравится ОПИ, то не забывайте поддерживать его на GitHub, Инфостарт и Boosty (ссылка в репозитории)!
Репозиторий ОПИ: github.com/Bayselonarrend/OpenIntegrations
Последний релиз: github.com/Bayselonarrend/OpenIntegrations/releases/latest
Документация: openintegrations.dev
Другие статьи про Открытый пакет интеграций на Инфостарт:
Открытый пакет интеграций для популярных API: Telegram, VK, Viber, Twitter
Работа с Notion API | Обновление Открытого пакета интеграций
Библиотека работы с Яндекс Диском (Open-source)
Открываем свою лавку на платформе VK Market
Библиотека для работы с Google Calendar API (open-source)
Telegram в режиме форума: делаем чаты комфортными
Открытый пакет интеграций для OneScript
Мой GitHub: https://gitub.com/Bayselonarrend OpenYellow: https://openyellow.org Лицензия MIT: https://mit-license.org
Вступайте в нашу телеграмм-группу Инфостарт
