Связаться с намиПодключиться

API в Managed Service for Apache Kafka®

Статья создана
Обновлена 20 августа 2025 г.

В кластере доступно несколько видов API, позволяющих выполнять различные операции.

Облачные API

Этот набор API предоставляется Yandex Cloud и включает в себя REST API и gRPC API. Любой из этих API может использоваться, чтобы работать со следующими объектами:

Использование

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

Доступные операции определяются ролями аккаунта, от имени которого выполняются запросы к API.

Описания методов REST API и вызовов gRPC API приведены в справочнике API. Примеры запросов см. в пошаговых инструкциях.

Ограничения

С помощью этих API можно управлять только частью сущностей Apache Kafka®. Чтобы получить расширенные возможности по управлению сущностями Apache Kafka®, используйте Managed Service for Apache Kafka® REST API или Client API.

Managed Service for Apache Kafka® REST API

Этот набор REST API предоставляется Yandex Cloud и включает в себя:

В кластерах Managed Service for Apache Kafka® используется продукт с открытым исходным кодом Karapace, который предоставляет эти REST API, а также служит основой для управляемого реестра схем формата данных.

Использование

Чтобы использовать любой из этих API:

  1. Получите доступ к API.

    По умолчанию Managed Schema Registry и оба REST API выключены и недоступны. Чтобы воспользоваться ими, укажите соответствующие настройки при создании или изменении кластера:

    • Реестр схем данных. В кластере станут доступны Managed Schema Registry и соответствующий ему REST API.
    • Kafka Rest API. В кластере станет доступен REST API для Apache Kafka®.

    Хотя оба REST API предоставляются Karapace, они независимы друг от друга: например, можно использовать только Managed Schema Registry и его REST API, только REST API для Apache Kafka®, или все сразу.

  2. Выполните все шаги по предварительной настройке для подключения к кластеру.

  3. Пройдите аутентификацию при выполнении запросов к API.

    Используется механизм HTTP Basic Authentication: каждый запрос должен содержать в себе HTTP-заголовок Authorization с реквизитами пользователя Apache Kafka®, от имени которого выполняется запрос.

Доступные операции определяются ролями пользователя Apache Kafka®, от имени которого выполняются запросы к API:

  • REST API для Managed Schema Registry:

    • Роль ACCESS_ROLE_SCHEMA_READER: пользователю доступны операции чтения над субъектами, на которые назначена роль.
    • Роль ACCESS_ROLE_SCHEMA_WRITER: пользователю доступны операции чтения и записи над субъектами, на которые назначена роль.
    • Роль ACCESS_ROLE_CONSUMER: пользователю доступны операции чтения над субъектами, связанными с топиком, на который назначена роль.
    • Роль ACCESS_ROLE_PRODUCER: пользователю доступны любые операции над субъектами, связанными с топиком, на который назначена роль.
    • Роль ACCESS_ROLE_ADMIN: пользователю доступны любые операции над субъектами, связанными с любым топиком (эта роль назначается на все топики).
    • Роль ACCESS_ROLE_TOPIC_ADMIN: пользователю доступны любые операции над субъектами, связанными с топиком, на который назначена роль.

    Перечень субъектов, с которыми можно работать, также определяется ролью пользователя. Подробнее о ролевой модели Managed Schema Registry см. в разделе Управление схемами данных.

  • REST API для Apache Kafka®:

    • Роль ACCESS_ROLE_CONSUMER: пользователь может получать информацию об объектах Apache Kafka®, а также работать с потребителями.
    • Роль ACCESS_ROLE_ADMIN, ACCESS_ROLE_PRODUCER или ACCESS_ROLE_TOPIC_ADMIN: пользователь может работать с объектами Apache Kafka® в полном объеме.

Описания методов REST API для Managed Schema Registry и REST API для Apache Kafka® приведены в документации Confluent. Пример работы с этими API см. в разделе Работа с управляемым реестром схем формата данных с помощью REST API.

Ограничения

  • REST API для Managed Schema Registry:

    Ограничено использование методов для управления режимом работы реестра:

    • Просматривать информацию о режимах работы реестра может только пользователь с правами ACCESS_ROLE_ADMIN.
    • Нельзя изменить режим работы реестра.

  • REST API для Apache Kafka®:

    • Нельзя управлять кластерами и другими объектами Apache Kafka®, кроме производителей и потребителей.
    • Доступны только методы Confluent REST Proxy API версии v2.

Client API Apache Kafka®

Client API — общее название для набора нативных API Apache Kafka®:

  • Producer API — позволяет работать с производителями.
  • Consumer API — позволяет работать с потребителями.
  • Streams API — позволяет работать с потоками данных.
  • Connect API — позволяет работать с коннекторами.
  • Admin API — позволяет работать с объектами Apache Kafka®.

Эти API позволяют управлять объектами Apache Kafka® (с некоторыми ограничениями).

Использование

Чтобы использовать любой из этих API:

  1. Выполните предварительную настройку для подключения к кластеру.

  2. Встройте нужный API в код приложения-клиента Apache Kafka®.

    Для работы с Client API необходимо вызывать нужные функции из кода приложений-клиентов — эти API не являются REST API.

  3. Настройте в коде приложения-клиента нужный механизм аутентификации, чтобы взаимодействовать с API. При аутентификации используются реквизиты пользователя Apache Kafka®.

    Механизмы аутентификации описаны в документации Confluent для приложений-клиентов. Примеры настройки см. в разделе Примеры кода для подключения к кластеру Apache Kafka®.

Доступные операции определяются ролями пользователя Apache Kafka®, от имени которого выполняются запросы к Client API.

Описания Client API приведены в документации Apache Kafka®. Пример работы с Producer API и Consumer API см. в разделе Работа с управляемым реестром схем формата данных.

Ограничения

  • Нельзя управлять кластерами и пользователями Apache Kafka®.

  • Можно управлять топиками с помощью Admin API, но со следующими ограничениями:

    • Для управления топиками используются:

      • пользователь-администратор с ролью ACCESS_ROLE_ADMIN, которая действует для всех топиков кластера. Если такого пользователя в кластере нет, создайте его;
      • пользователь с ролью ACCESS_ROLE_TOPIC_ADMIN, которая задается на произвольные топики.

      Подробнее о правах, которые предоставляет каждая роль.

    • Права доступа пользователей для производителей и потребителей настраиваются с помощью стандартных интерфейсов Yandex Cloud, а не Admin API Apache Kafka®.

Примеры использования

Предыдущая
Веб-интерфейс для Apache Kafka®
Следующая
Классы хостов