Core

Core — центральный модуль для работы с API Т-Инвестиций.

Какие задачи решает

Предоставляет интерфейс для работы с API Т-Инвестиций.
Является обёрткой для работы с унарными запросами, server-side и bidirectional-стримами.
Логирует и трассирует запросы.
Обрабатывает ошибки и повторные попытки (retry).
Поддерживает конфигурации resilience4j для унарных запросов.
Объединяет стримы рыночных данных в один поток с помощью MarketDataStreamManager.

Добавить модуль в проект

Задать конфигурацию клиента

Конфигурацию клиента можно задать в файле properties в classpath. Значения по умолчанию:

token=t.*****
connection.timeout=30000
connection.keepalive=60000
connection.max-message-size=16777216
connection.retry.max-attempts=3
connection.retry.wait-duration=2000
grpc.debug=false
grpc.context-fork=true
target=invest-public-api.tinkoff.ru:443
sandbox.target=sandbox-invest-public-api.tinkoff.ru:443
sandbox.enabled=false
stream.market-data.max-streams-count=16
stream.market-data.max-subscriptions-count=300
stream.inactivity-timeout=10000
stream.ping-delay=5000

Подробнее о каждом параметре:

token — токен доступа к API Т-Инвестиций.
connection.timeout — таймаут соединения в миллисекундах.
connection.keepalive — интервал проверки соединения в миллисекундах.
connection.max-message-size — максимальный размер сообщения в байтах.
connection.retry.max-attempts — максимальное количество попыток отправки запроса.
connection.retry.wait-duration — интервал ожидания между попытками отправки запроса в миллисекундах.
grpc.debug — включение отладочной информации.
grpc.context-fork — включение форка контекста.
target — URL API Т-Инвестиций.
sandbox.target — URL API песочницы Т-Инвестиций.
sandbox.enabled — включение песочницы.
stream.market-data.max-streams-count — максимальное количество стримов для рыночных данных. Используется в MarketDataStreamManager.
stream.market-data.max-subscriptions-count — максимальное количество подписок на рыночные данные в одном стриме. Используется в MarketDataStreamManager.
stream.inactivity-timeout — таймаут отсутствия сообщений в стриме в миллисекундах.
stream.ping-delay — интервал пинга в стриме в миллисекундах.

Чтобы видеть, какие ответы приходят от API и их tracking-id, в параметре grpc.debug укажите true.

За загрузку конфигурации подключения из файла или объекта Properties и ее хранение отвечает ConnectorConfiguration.

Ниже привели примеры кода на Java, в которых в качестве ресурса для ConnectorConfiguration указан файл invest.properties. Содержание файла соответствует представленному выше.

Унарные запросы

Есть два вида выполнения унарных запросов на клиенте — синхронный и асинхронный.

Синхронный

Синхронные запросы блокируют выполнение программы до получения ответа от сервера. Чтобы выполнить запрос, создайте экземпляр SyncStubWrapper.

Для поддержки механизма resilience можно использовать класс ResilienceSyncStubWrapper, который включает retry, bulkhead, rate-limiting и circuit-breaker. По сути, это обёртка над SyncStubWrapper.

Асинхронный

Асинхронные запросы возвращают CompletableFuture, которые могут быть обработаны позже. Не блокируют выполнение программы. Чтобы выполнить запрос, создайте экземпляр AsyncStubWrapper.

Для поддержки resilience можно использовать ResilienceAsyncStubWrapper. Как и в случае с синхронным вызовом, это обёртка над AsyncStubWrapper.

По умолчанию конфигурация настроена только для retry, но вы также можете настроить другие компоненты resilience.

Stream-соединения

SDK предоставляет удобные обёртки для работы со стримами. Они позволяют устанавливать листенеры для получения данных — например, OnNextListener, OnErrorListener или OnCompleteListener.

Server-side

Для создания server-side стрима используется класс ServerSideStreamWrapper.

Resilience server-side wrapper

Для упрощения работы с server-side стримами и повышения их надёжности был создан ResilienceServerSideStreamWrapper.

Он инициирует автоматическое переподключение стрима и повторную отправку последнего успешного запроса на подписку, если в стриме не было активности в течение времени, заданного в параметрах stream.inactivity-timeout.

Чтобы получить экземпляр ResilienceServerSideStreamWrapper, создайте один из вариантов конфигурации ResilienceServerSideStreamWrapperConfiguration:

OrderStateStreamWrapperConfiguration
TradeStreamWrapperConfiguration
PortfolioStreamWrapperConfiguration
PositionStreamWrapperConfiguration

Bidirectional

Для работы с bidirectional-стримами используется класс BidirectionalStreamWrapper.

Чтобы получать данные для bidirectional-стрима, нужно отправить запрос на подписку.

Также для более удобной работы с MarketDataStreamService при создании BidirectionalStreamWrapper можно передать конфигурацию MarketDataStreamConfiguration.

Учитывайте, что листенеры в MarketDataStreamConfiguration возвращают Wrapper-объекты над сгенерированными gRPC-объектами. Это нужно для удобной работы с ценами и временем, так как в gRPC используется свой Timestamp для времени и Quotation для чисел с плавающей запятой. Wrapper преобразует их в LocalDateTime и BigDecimal соответственно.

Подробнее про нестандартные типы данных

Resilience market data wrapper

Для повышения надежности при работе с MarketDataStream создан MarketDataStreamWrapper. Он инициирует автоматическое переподключение стрима и повторную отправку последовательности совершенных до обрыва соединения запросов, если в стриме не было активности в течение времени, заданного в параметрах stream.inactivity-timeout.

MarketDataStreamManager

Ещё одна удобная обёртка над bidirectional-стримами MarketDataStream — менеджер MarketDataStreamManager.

Он нужен, чтобы избавить пользователя от необходимости заботиться о количестве подписок и их распределении по стримам — они ограничиваются лимитами API.

Менеджер позволяет объединить подписки из всех стримов в один общий поток данных и обрабатывать их в листенерах.

При использовании MarketDataStreamManager не забывайте вызывать метод start() — это можно сделать как до подписки, так и после нее. Метод запускает обработку поступающих в листенеры данных.