Перейти к содержанию

Протокол взаимодействия с Gateway платформы#

Gateway — это веб-сервис для приёма аналитических событий в Data Platform.

Зачем нужен Gateway:

  • Для упрощения интеграции, за счёт использования HTTP, который проще большинства других протоколов.
  • Для абстрагирования издателей от внутренних механизмов платформы, что обеспечит независимость в случае их изменения.
  • Для обеспечения большей гибкости в целом, за счёт различных механизмов проксирования HTTP-трафика.

В данной статье описаны нюансы взаимодействия с Gateway со стороны издателя.

Способ сериализации данных#

Для сериализации данных был выбрал формат Apache Avro. События собираются в пачку в рамках одного сообщения в виде OCF.

HTTPS#

В качестве протокола для передачи данных был выбран HTTP, в качестве механизма аутентификации — mTLS.

Как отправлять#

  1. Собрать пачку событий в рамках одного шарда.
  2. Сериализовать данные по схеме (.avsc).
  3. Вычислить заголовки (см. ниже).
  4. Отправить POST-запрос с телом и хедерами на указанный URL.

Пример URL для отправки данных#

https://gateway.kruma.ru/api/1.0/simple

Где «simple» — название потока данных, соответствующего контракту.

Версия контракта#

Версия модели наследуется от соответствующего data-contract и соответствует временной метке последнего коммита, изменившего контракт в GitLab.

git log -1 --format=%ct -- path/to/data-contract.yaml

Это гарантирует:

  • Синхронизацию между моделями и актуальной спецификацией контракта.
  • Трассируемость изменений: любая модификация контракта (добавление поля, изменение типа) автоматически отражается во всех производных моделях через CI/CD-процессы.
  • Совместимость при обновлениях: потребители данных могут проверять версии моделей, чтобы корректно обрабатывать изменения структуры.

Headers#

Ожидаемые хедеры:

  • Content-length: 1024 — размер сообщения в байтах.
  • Dto-hash: sha256; aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f — хеш-сумма сообщения.
  • Dto-batch: 100 — количество событий в сообщении.
  • Dto-shard: 1 (опционально) — идентификатор шарда, на котором было сформировано сообщение.
  • Dto-version: 1740998320 — версия контракта данных.

Коды ответа#

В случае успешной отправки данных, вы получите 201, а в случае неудачи, вам следует повторить запрос.