Описание API-интерфейса, библиотека и тестовый проект для взаимодействия с MOAB Tools
Для работы с API нужно получить API-ключ, который находится в вашем профиле https://moab.tools/Profile. Все запросы отправляются на сервис методом POST в кодировке UTF-8 с Content-Type "application/json".
Адрес, куда слать запросы: https://moab.tools/api/Parse/AddTasks
Пример отправляемых данных:
{task: tsk,api_key: api_key,partner_code: null}tsk – конструкция вида:
{phrases_list: [],regions: '',syntax: 1,depth: 1,db: 0,group_id: null,also_suggests: false,also_check: false,fix_words_order: false,type: 0,minus_words: [],suggests_types: [],suggests_depth: 1}partner_code - необязательное строковое поле, предназначенное для идентификации вашего решения в маркетинговых целях (согласовывается с техподдержкой). Пример: partner_code: "MyGreatSoftware". По умолчанию - null, при передаче JSON-конструкции поле можно не указывать.
Описание полей:
| Поле | Тип данных | Описание |
|---|---|---|
| phrases_list | массив строк | Массив исходных фраз Максимальное количество фраз в массиве: - Wordstat Deep - 1 - Direct Check – 10 000 - Подсказки – 10 000 Хотя бы одна фраза должна быть в массиве |
| regions | строка | Список регионов через запятую, пример "256,13,1" Все коды регионов - https://dobrovkonstantin.ru/yandexgeo По умолчанию – пустая строка (все регионы). |
| syntax | число | Синтаксис запросов к Wordstat 1 – без кавычек 2 – в кавычках "слово1 слово2" 3 – в кавычках с воскл.знаком "!слово1 !слово2" По умолчанию 1 В Wordstat Deep и Подсказках поддерживается только 1 |
| depth | число | Глубина парсинга в Wordstat Deep По умолчанию 2 Поддерживается только в Wordstat Deep, для остальных типов заданий нужно ставить 1 |
| db | число | Устройства в Wordstat 0 – все устройства 1 – десктопы 2 – мобильные 3 – только телефоны 4 – только планшеты По умолчанию 0 (Все устройства) Поддерживается только в Wordstat Deep |
| group_id | число | Id группы (в API пока не поддерживается Нужно ставить null – попадет в группу «Без группы» |
| also_suggests | boolean | Поддерживается только в Wordstat Deep, соответствует флажку «Также получить Яндекс-подсказки по полученным фразам». Для остальных типов заданий нужно ставить false |
| also_check | boolean | Поддерживается только в Wordstat Deep, соответствует флажку «Также проверить полученные подсказки на общую частоту Wordstat». Для остальных типов заданий нужно ставить false |
| fix_words_order | boolean | Пока не поддерживается в API, нужно ставить false |
| type | число | Тип выборки: 0 – Wordstat Deep 1 – Direct Check 2 – Подсказки |
| minus_words | массив строк | Массив минус-слов До 100 минус-слов в массиве Поддерживается только в Wordstat Deep, для остальных типов заданий массив должен быть пустым |
| suggests_types | массив чисел | Способ сбора подсказок в Wordstat Deep или Подсказках: 1 – фраза 2 – фраза и пробел 3 – фраза и русский алфавит 4 – фраза и английский алфавит 5 – фраза и цифры Нельзя передавать пустой массив, хотя бы одно число должно быть |
| suggests_depth | число | Глубина сбора подсказок в Wordstat Deep или Подсказках. В Wordstat Deep всегда 1, в Подсказках может быть от 1 до 3 |
При успешном добавлении задания возвращается код 200 и JSON-конструкция вида:
{total_pages: 10,added_ids: [12345],exists_ids: [],errors: null}В случае ошибки возвращается HTTP-код 400 и JSON-конструкция вида:
{total_pages: 0,added_ids: null,exists_ids: null,errors: ["Задание с такими параметрами уже было добавлено вами ранее"]}| Поле | Тип данных | Описание |
|---|---|---|
| total_pages | число | Сервисная информация – сколько всего страниц с выборками у пользователя |
| added_ids | массив чисел | Массив целых чисел – id добавленных заданий В случае запроса через API содержит одно число – id добавленного задания Если задание добавилось с ошибкой – возвращает null |
| exists_ids | массив чисел | Массив целых чисел – id существующих заданий В случае запроса через API содержит одно число – id существующего задания Существующим считается задание, полностью соответствующее по всем параметрам добавляемому В дальнейшем вы можете скачать это задание (как получить путь к файлу - см. раздел «Проверка статуса задания и получение результата») и отдать файл пользователю, или сообщить об ошибке на основе имеющейся информации Если задание добавилось с ошибкой – возвращает null Если существующих заданий нет - вернется пустой массив |
| errors | массив строк | Массив описаний ошибок Если задания добавились успешно – значение null |
Из массива ids нужно достать id задания и при помощи запроса Check раз в 5 секунд проверять его статус.
Адрес, куда слать запросы: https://moab.tools/api/Parse/Check
Пример отправляемых данных:
{id: task_id,api_key: api_key}Здесь task_id – целое число, идентификатор задания, полученный на этапе добавления задания.
Запрос можно выполнять не чаще 1 раза в 5 секунд.
Возвращаемые данные:
{status: 0,progress: 0,download_zip: null,balance: 100}| Поле | Тип данных | Описание |
|---|---|---|
| status | число | Статус проверяемого задания 0 – новое 1 – выполняется 2 – завершено 3 – приостановлено пользователем 4 – приостановлено из-за нехватки баланса |
| progress | число | Прогресс выполнения задания, от 0 до 100 |
| download_zip | строка | При статусах 2, 3 или 4 вернется абсолютный путь на скачивание готовой или приостановленной выборки. Если выборка в статусе «новая» или «выполняется» – вернется null. |
| balance | число | Баланс пользователя (кол-во фраз, которые он ещё может получить) на момент запроса check |
Адрес, куда слать запросы: https://moab.tools/api/Parse/TasksList
Пример отправляемых данных:
{type: 0,page: 1,api_key: api_key}| Поле | Тип данных | Описание |
|---|---|---|
| type | число | Тип возвращаемых выборок: 0 – Wordstat Deep 1 – Direct Check 2 – Подсказки |
| page | число | Необязательный параметр. Страница выборок, которую нужно вернуть (аналогично странице в интерфейсе веб-версии). Если страницу не указывать - вернутся все выборки. |
В случае ошибки возвращается статус 400 и JSON-конструкция, аналогичная таковой при добавлении задания. В случае успешного выполнения функции возвращается JSON-конструкция вида:
{tasks_list: [task,task, ...],total_pages: 1}В массиве tasks_list возвращается список заданий. Помимо полей задания, описанных в разделе "Добавление заданий", в каждом задании присутствуют дополнительные поля, описание которых приводим в таблице ниже:
| Поле | Тип данных | Описание |
|---|---|---|
| id | число | Уникальный идентификатор задания |
| date_created | дата и время | Дата и время создания задания |
| date_finished | дата и время | Дата и время завершения выполнения задания |
| status | число | Статус задания (значения описаны в разделе "Проверка статуса задания и получение результата") |
| summ | decimal | Сумма задания, списываемая с баланса пользователя (соответствует количеству полученных фраз) |
| full_name | строка | Полное имя задания |
Приостановить задание (поставить на паузу) можно, отправив на адрес https://moab.tools/api/Parse/PauseTask запрос вида:
{api_key: api_key,task_id: 12345}Здесь task_id – целое число, идентификатор задания, полученный на этапе добавления задания.
Продолжить поставленное ранее на паузу задание можно, отправив аналогичный запрос на адрес https://moab.tools/api/Parse/RunTask
При успешной приостановке / продолжении задания возвращается HTTP-код 200 и пустое тело ответа. В случае ошибки возвращается код 400 и ответ вида:
{total_pages: null,added_ids: null,exists_ids: null,errors: ["Задание не найдено или принадлежит другому пользователю"]}Свойства аналогичны таковым при добавлении задания, за исключением того, что total_pages, added_ids и exists_ids всегда будут null.
Библиотека написана на C#, распространяется в виде исходных кодов. Для работы с ней сохраните этот репозиторий в Zip-файл, откройте его в Visual Studio версии не ниже 2015 и скомпилируйте, затем добавьте ссылку на MoabTools.dll в ваш проект.
Зависимости:
Возможности библиотеки:
- Создание и отправка задания
- Валидация задания перед отправкой
- Проверка статуса задания с получением ссылки на скачивание
- Получение списка заданий
- Наличие тестового проекта, в коде которого можно посмотреть примеры использования библиотеки
Чтобы создать и отправить задание, а затем проверить его состояние и скачать готовую выборку, выполните следующий код:
// создадим задание на парсинг WordstatDeep// параметры по умолчанию - смотрим конструктор Task// параметры соответствуют действию человека "зашел в сервис, ввёл фразу, нажал «Получить фразы», // не вникая в тонкие настройки сервисаTasktask=newTask();task.phrases_list.Add("автострахование краснодар");// если задание валидно - отправляем заданиеConsole.WriteLine("Отправляем задание");// создадим запрос на добавление заданияRequestreq=newRequest();req.task=task;req.api_key=api_key;varreq_valid=req.Validate();// валидируем запрос и заданиеif(req_valid!=null){// если запрос или задание невалидны - дадим знать об этом пользователюConsole.ForegroundColor=ConsoleColor.Red;foreach(varrinreq_valid){Console.WriteLine(r.ErrorMessage);}Console.ReadKey();return;}// отправляем запрос на добавление заданияRequestAnswerans;try{ans=req.Send();}catch(WebExceptionex){// если вернулся ответ 400 - разберем его и покажем пользователю ошибкиvarresp=newStreamReader(ex.Response.GetResponseStream()).ReadToEnd();dynamicerr=JsonConvert.DeserializeObject(resp.ToString());// todothrow;}if(ans.exists_ids!=null){// задание с такими параметрами уже существует у пользователя // в массиве exists_ids присутствует id// вернем ошибку или скачаем, если готово, при помощи функции Checkreturn;}varid=ans.added_ids[0];// создадим запрос на проверку статуса заданияCheckchk=newCheck();chk.id=id;chk.api_key=api_key;varchk_valid=chk.Validate();if(chk_valid!=null){// если запрос невалидный - дадим знать об этом пользователюConsole.ForegroundColor=ConsoleColor.Red;foreach(varcinchk_valid){Console.WriteLine(c.ErrorMessage);}Console.ReadKey();return;}// раз в 5 сек отправляем запрос на проверку статуса заданияCheckAnswerchk_ans;while(true){Thread.Sleep(5000);Console.WriteLine($"Проверяем статус задания {id}");try{chk_ans=chk.Send();}catch(Exception){continue;}if(chk_ans.status==2||chk_ans.status==3||chk_ans.status==4){Console.WriteLine("Скачиваем готовую выборку");// todobreak;}}Console.ReadKey();По всем вопросам, связанным с интеграцией API MOAB Tools в вашу систему, вы можете обращаться в техподдержку сервиса https://moab.tools/Support
Команда MOAB оставляет за собой право изменять свойства, методы, поведение и другие части интерфейса API без предварительного уведомления об этом пользователей. Обратная совместимость при этом не гаратируется. Другими словами, если у вас вдруг перестало работать ваше решение по интеграции - сверьтесь с последними изменениями на этой странице - здесь всегда будет самая актуальная информация.