Большая статья по Admin API

admin-api-global

Ранее мы выпускали подобный материал по нашим главным скриптам интеграций KClient.php, KClient JS, а также S2S постбекам. И сегодня настала очередь подробно разобрать Admin API, а именно: зачем нужен Admin API, какие кейсы закрывает этот интерфейс и как правильно формировать запросы в трекер.

Интерфейс Admin API

API ( application programming interface) — описание способов (набор классов, процедур, функций и т.д.), с помощью которых одна компьютерная программа может взаимодействовать с другой программой. 

Keitaro Admin API — интерфейс, который позволяет путем входящих запросов осуществлять управление админ-панелью трекера Keitaro. То есть не заходя в админку трекера, вы можете, например, создать кампанию с необходимыми настройками, поменять содержимое потока или сформировать отчет по конверсиям, будь то серверный скрипт или внешнее приложение по типу Postman. 

Реальное применение Admin API 

Чаще всего Admin API используют в ситуациях, когда необходимо автоматизировать рутинные сценарии или работать с большим объемом данных. 

Пример А 

Клиент хочет выгружать актуальные конверсии из трекера каждые шесть часов и отправлять список в свою CRM.

При работе через веб-интерфейс конверсии придется выгружать в ручном режиме. После чего конвертировать полученный отчет из CSV или Excel в нужный формат для CRM и делать ручную отправку. 

В то время как Admin API позволяет сформировать серверный запрос на получение нужного отчета, который впоследствии можно автоматически распарсить, преобразовать и отправить в CRM. Все это можно поместить в один файла скрипта, который планировщик будет запускать каждые 6 часов, как и задано в условии. 

Пример B

Клиент получает каждые 24 часа новый список из 100 доменов, которые необходимо добавить в трекер. 

В ручном режиме полученный список нужно будет привести в строку, где каждое значение проставить через разделитель. И после этого добавить домены в трекер. 

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

Как использовать Admin API?

Для простой и удобной работы с Admin API желательно обладать как минимум базовыми навыками работы с любым из серверных языков: PHP, Node, Python и др. Но при желании этот интерфейс можно освоить и технически неподкованному человеку. 

Говоря простым языком, у трекера есть точка входа (некий адрес), на который вы отправляете запрос (принцип похож на тот, когда вы вызываете веб-сайт из строки вашего браузера) и в зависимости от заданных параметров запроса получаете тот или иной ответ. 

И для того, чтобы осуществить этот самый запрос и он был валидный, нужно:

1. Использовать ключ авторизации (грубо говоря ваш пароль, который не даст получить информацию сторонним юзерам).

2. Использовать правильный тип запроса

3. Задать обязательные параметры (нужны при запросах на создание сущностей, например, создание кампании).

Ключ аутентификации вы можете взять в трекере, в меню Обслуживание — Пользователи — Ключ для Admin API.

А что касается типа запроса, то при работе с Admin API Keitaro используется следующий набор: 

GET — для получения информации, например, списка кампаний трекера: 

https://keitarosupport1.xyz/admin_api/v1/campaigns

POST — для построения отчетов, а также создания чего-либо, например, новой кампании в трекере: 

https://keitarosupport1.xyz/admin_api/v1/campaigns

Обратите внимание, что адрес запроса внешне выглядит одинаково: в обоих случаях мы обращаемся на «точку входа трекера», которая содержит в себе: 

  • адрес трекера — keitarosupport1.xyz
  • далее указывает на раздел  Admin API — admin_api/v1/
  • и конкретный подраздел трекера, кампании — campaigns.

При этом отличается сам тип запроса, который надо указывать при отправке. Например, при использовании CURL запросы выглядят так: 

curl -X GET "https://keitarosupport1.xyz/admin_api/v1/campaigns" -H "accept: application/json" -H "Api-Key: 029e67361fc20e99ad02a8"

Для получения списка кампаний трекера.

curl -X POST "https://keitarosupport1.xyz/admin_api/v1/campaigns" -H "accept: application/json" -H "Api-Key: 029e67361fc20e99ad02a8" -H "Content-Type: application/json" -d "{\"alias\":\"alias\",\"type\":\"position\",\"name\":\"name\",.........\"url\":\"string\"}]}"

Для создания кампании соответственно.

PUT — для обновления имеющихся данных в трекере

DELETE — для удаления данных в трекере. 

Мы показали ключи и описали типы запросов. Осталось просмотреть параметры, и можно тренироваться составлять запросы. Где взять список required параметров запроса? 

Обратитесь в нашу документацию: https://admin-api.docs.keitaro.io

Найдите тип запроса, который хотите осуществить, и там же будет список обязательных параметров. Список необходимых параметров для создания кампании в трекере включает в себя: alias и name. 

Задав только эти два параметра вы уже можете создавать кампанию. Остальные настройки кампании будут заданы по умолчанию. 

Вы также можете получить готовый пример тела (body) запроса, в котором необходимо только заменить значения-заглушки на собственные и можно использовать этот код в своем запросе (показано на скрине справа).

Как начать работать с Admin API? 

Если вы дочитали до этого момента и вам не терпится попробовать свои силы в построении запросов и работе Admin API, то самый просто способ начать — использовать нашу Swagger документацию. Это интерфейс, который совмещает в себе нашу документацию Admin API и возможность отправлять реальные запросы на трекер. 

Открываем Обслуживание — Пользователи — Ключи для Admin API, копируем свой ключ и нажимаем на вкладку Документация. Вас перебросит в интерактивный режим, где можно потренироваться с запросами. 

Первым делом проходим авторизацию: 

Выбираем нужный раздел, например, создание кампании: 

И нажимаем Try it out. Это даст нам возможность редактировать наше тело (body) запроса, которое отправится при нажатии кнопки Execute. Внутри этого body мы задаем наши required параметры name и alias и все дополнительные, которые хотим указать при создании кампании. 

Нажимаем Execute и видим наш отправленный запрос, адрес запроса и ответ от трекера: 

Если запрос произошел с ошибкой, то вы увидите другой статус ответа, и в поле Response body будет описание ошибки. 

Таким образом вы можете тестировать любые типы запросов, пока не набьете руку и не достигнете желаемого результата в работе с Admin API. 

Более продвинутые могут попробовать работать с Admin API из стороннего приложения, например, Postman. Или попробовать написать свой серверный скрипт, в котором будет отправляться запрос на Admin API. 

Смотрите наш вебинар из серии «Keitaro на Максимум», где мы сделали краткий разбор работы с Admin API: 

А также видео-гайд по формированию нестандартных запросов: 

Если у вас остались вопросы по работе с Admin API, вы всегда можете написать нам в поддержку в чат на сайте либо в телеграм @keitarobot. Мы обязательно поможем разобраться.

Keitaro Team

Команда Keitaro. Отряд по доставке свежего и качественного контента!

Посмотреть все записи автора Keitaro Team →