Описание методов (v1) | Документация | A-Parser - парсер для SEO, маркетинга, разработчиков и SaaS
Перейти к основному содержимому

Описание методов (v1)

warning

Данное JavaScript API считается устаревшим, рекомендуем использовать API версии 2

Обратите внимание что часть методов требуют указания ключевого слова yield

yield this.request()

yield this.request(method, url, queryParams, opts)

Получение HTTP ответа по запросу, в качестве аргументов указывается:

  • method - метода запроса (GET, POST...)
  • url - ссылка для запроса
  • queryParams - хэш с get параметрами или хэш с телом post-запроса
  • opts - хэш с опциями запроса

Если используется метод POST, то тело запроса можно передать двумя способами:

  • просто перечислив названия переменных и их значения в queryParams. Например:
{
key: set.query,
id: 1234,
type: 'text'
}
  • через переменную body в opts. Например:
body: 'key=' + set.query + '&id=1234&type=text'

opts.check_content

check_content: [ условие1, условие2, ...] - массив условий для проверки получаемого контента, если проверка не проходит, то запрос будет повторен с другим прокси.

Возможности:

  • использование в качестве условий строк (поиск по вхождению строки)
  • использование в качестве условий регулярных выражений
  • использование своих функций проверок, в которые передаются данные и хедеры ответа
  • можно задать сразу несколько разных типов условий
  • для логического отрицания поместите условие в массив, т.е. check_content: ['xxxx', [/yyyy/]] означает что запрос будет считаться успешным, если в полученных данных содержится подстрока xxxx и при этом регулярное выражение /yyyy/ не находит совпадений на странице

Для успешного запроса должны пройти все указанные в массиве проверки

Пример (в комментариях указано что нужно для того, чтобы запрос считался успешным):

let response = yield this.request('GET', set.query, {}, {
check_content: [
/<\/html>|<\/body>/, //на полученной странице должно сработать это регулярное выражение
['XXXX'], //на полученной странице не должно быть этой подстроки
'</html>', //на полученной странице должна быть такая подстрока
(data, hdr) => {
return hdr.Status == 200 && data.length > 100;
} //эта функция должна вернуть true
]
});

opts.decode

decode: 'auto-html' - автоматическое определение кодировки и преобразование в utf8

Возможные значения:

  • auto-html - на основе заголовков, тегов meta и по содержимому страници (оптимальный рекомендуемый вариант)
  • utf8 - указывает что документ в кодировке utf8
  • <encoding> - любая другая кодировка

opts.headers

headers: { ... } - хэш с заголовками, название заголовка задается в нижнем регистре, можно указать в т.ч. cookie Пример:

headers: {
accept: 'image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8',
'accept-encoding': 'gzip, deflate, br',
cookie: 'a=321; b=test',
'user-agent' 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.150 Safari/537.36'
}

opts.headers_order

headers_order: ['cookie', 'user-agent', ...] - позволяет переопределить порядок сортировки заголовков

opts.recurse

recurse: N - максимальное число переходов по редиректам, по умолчанию 7, используйте 0 для отключения перехода по редиректам

opts.proxyretries

proxyretries: N - число попыток выполнения запроса, по умолчанию берется из настроек парсера

opts.parsecodes

parsecodes: { ... } - перечень кодов HTTP ответов, которые парсер будет считать удачными, по умолчанию берется из настроек парсера. Если указать '*': 1 то все ответы будут считаться удачными. Пример:

parsecodes: {
200: 1,
403: 1,
500: 1
}

opts.timeout

timeout: N - таймаут ответа в секундах, по умолчанию берется из настроек парсера

opts.do_gzip

do_gzip: 1 - определяет использовать ли компрессию (gzip/deflate/br), по умолчанию включено (1), для выключения нужно задать значение 0

opts.max_size

max_size: N - максимальный размер ответа в байтах, по умолчанию берется из настроек парсера

opts.cookie_jar

cookie_jar: { ... } - хэш с куками.

opts.attempt

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

opts.browser

browser: 1 - автоматическая эмуляция заголовков браузера (1 - включено, 0 - выключено)

opts.use_proxy

use_proxy: 1 - переопределяет использование прокси для отдельного запроса внутри JS парсера поверх глобального параметра Use proxy (1 - включено, 0 - выключено)

opts.noextraquery

noextraquery: 0 - отключает добавление Extra query string к урлу запроса (1 - включено, 0 - отключено)

opts.save_to_file

save_to_file: file - позволяет скачать файл напрямую на диск, минуя запись в память. Вместо file указывается имя и путь под каким сохранить файл. При использовании этой опции игнорируется все, что связано с data (проверка контента в check_content, response.data будет пустой и т.д.).

opts.needData

needData: 1 - определяет передавать (1) или нет (0) в ответе data/pages[], может использоваться для оптимизации

opts.data_as_buffer

data_as_buffer: 0 - определяет возвращать data как строку String (0) или как объект Buffer (1), по умолчанию возвращается строка String

opts.bypass_cloudflare

bypass_cloudflare: 0 - автоматический обход JavaScript защиты CloudFlare используя браузер Chrome (1 - включено, 0 - выключено)

opts.follow_meta_refresh

follow_meta_refresh: 0 - позволяет переходить по редиректам, объявленным через HTML мета тег:

<meta http-equiv="refresh" content="time; url=..." />

opts.tlsOpts

tlsOpts: { ... } – позволяет передавать настройки для https соединений ​

yield this.parser.request()

yield this.parser.request(parser, preset, overrideParams, query)

Получение результатов от другого парсера (встроенного или еще другого JS парсера), в качестве аргументов указывается

  • parser - имя парсера (SE::Google, JS::Custom::Example)
  • preset - пресет настроек вызываемого парсера
  • overrideParams - хэш с переопределениями настроек вызываемого парсера
  • query - запрос

В overrideParams, кроме параметров вызываемого парсера, дополнительно можно передать флаг resultArraysWithObjects: 1 - он позволяет возвращать массив объектов в результатах вместо стандартного массива значений

tools.*

Глобальный объект tools, позволяет получить доступ к встроенным функциям A-Parser'а (аналог инструментов шаблонизатора $tools.*).

important

tools.query не доступен, необходимо использовать this.query

this.doLog()

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

this.logger.*

.put()

this.logger.put(message) - добавляет строчку message в лог задания

.putHTML()

this.logger.putHTML(code) - вывод в лог задания HTML кода, который будет отображен в textarea

yield this.sleep()

yield this.sleep(sec)

Устанавливает задержку в потоке на число секунд sec, может быть дробным.

yield this.mutex.*

Мютекс для синхронизации между потоками, позволяет заблокировать секцию кода для одного потока

.lock()

Ожидание лока, исполнение продолжит первый поток, который захватил лок, остальные потоки будут ожидать освобождение лока

.unlock()

Освобождение лока, следующий поток продолжит выполнение, если он ожидал лок(.lock())

this.cookies.*

Работа с cookies для текущего запроса

.getAll()

Получение массива cookies

.setAll()

Установка cookies, в качестве аргумента должен быть передан массив с cookies

.set()

this.cookies.set(host, path, name, value) - установка одиночного cookie

this.query.add()

this.query.add(query, maxLvl)

Добавление нового запроса (query) с возможностью опционально указать максимальный уровень (maxLvl), аналогично tools.query.add() Можно передавать в качестве запроса (query) хэш с параметрами, работает аналогично Конструктору запросов

Пример:

this.query.add({
query: "http://site.com",
param1: "..",
...
});

this.proxy.*

Работа с прокси

.next()

Сменить прокси на следующий, старый прокси больше не будет использован для текущего запроса

.ban()

Сменить и забанить прокси (необходимо использовать когда сервис блокирует работу по IP), прокси будет забанен на время, указанное в настройках парсера(proxybannedcleanup)

.get()

Получить текущий прокси (последний прокси с которым был сделан запрос)

.set()

this.proxy.set('http://127.0.0.1:8080', noChange = false) - установить прокси для следующего запроса, параметр noChange необязательный, если задан true то прокси не будет меняться между попытками

yield this.captcha.*

Работа с каптчей

.recognize()

yield this.captcha.recognize(preset, image, type, overrides) - загрузка каптчи для распознавания

  • image - бинарные данные картинки для распознавания
  • preset - указывает на пресет для Util::AntiGateUtil::AntiGate
  • type указывается один из: 'jpeg', 'gif', 'png'

Результатом будет хэш с полями:

  • answer - текст из картинки
  • id - id каптчи, для возможности в дальнейшем сообщить об ошибке через reportBad
  • error - текстовая ошибка, если answer не задан

.recognizeFromUrl()

yield this.captcha.recognizeFromUrl(preset, url, overrides) - аналогично предыдущему методу, но загрузка каптчи будет выполнятся автоматически по ссылке (url), без использования прокси

.reportBad()

yield this.captcha.reportBad(preset, id, overrides) - сообщить сервису что каптча разгадана неверно

this.utils.*

.updateResultsData()

this.utils.updateResultsData(results, data) - метод для автоматического заполнения $pages.$i.data и $data, необходимо вызывать для добавления контента результирующей страницы

.urlFromHTML()

this.utils.urlFromHTML(url, base) - обрабатывает ссылку полученную из HTML кода - декодирует entities (&amp; и т.п.), опционально можно передавать base - базовый урл (например урл исходной страницы), таким образом может быть получена полная ссылка

.url.extractDomain()

this.utils.url.extractDomain(url, removeDefaultSubdomain) - метод принимает в качестве первого параметра ссылку и возвращает домен из этой ссылки. Второй необязательный параметр определяет обрезать ли из домена субдомен www. По умолчанию 0 - то есть не обрезать.

.url.extractTopDomain()

this.utils.url.extractTopDomain(url) - метод принимает в качестве первого параметра ссылку и возвращает домен из этой ссылки, без субдоменов.

.url.extractTopDomainByZone()

this.utils.url.extractTopDomainByZone(url) - метод принимает в качестве первого параметра ссылку и возвращает домен из этой ссылки, без субдоменов в том числе. Работает cо всеми региональными зонами

.url.extractMaxPath()

this.utils.url.extractMaxPath(url) - метод принимает строку и выбирает из нее урл

.url.extractWOParams()

this.utils.url.extractWOParams(url)- метод принимает ссылку и возвращает эту же ссылку обрезанную до строки параметров. То есть вернет урл до ?

.removeHtml()

this.utils.removeHtml(string) - метод принимает строку и возвращает её очищенной от html тегов

.removeNoDigit()

this.utils.removeNoDigit(string) - метод принимает строку, удаляет из неё все кроме цифр и возвращает результат

.removeComma()

this.utils.removeComma(string) - метод принимает строку, удаляет из неё такие символы как .,\r\n и возвращает результат

this.sessionManager.*

Для использования сессий в JS парсере сначала нужно инициализировать Менеджер сессий. Делается это с помощью функции init()

init() {
this.sessionManager.init({
//здесь можно задать дополнительные параметры
});
}

В this.sessionManager.init() можно использовать следующие параметры:

  • name - необязательный параметр, позволяет переопределить имя парсера, которому принадлежат сессии, по-умолчанию равно имени парсера, в котором происходит инициализация
  • canChangeProxy - необязательный параметр, возможность менять прокси, по-умолчанию равно 1
  • domain - необязательный параметр, указывает искать сессии среди всех сохраненных для этого парсера (если значение не задано), или же только для конкретного домена (необходимо указывать домен с точкой спереди, например .site.com)

Для работы с сессиями существует несколько функций:

.get()

this.sessionManager.get() - получает новую сессию, необходимо вызывать перед осуществлением запроса

.reset()

this.sessionManager.reset() - очистка куков и получение новой сессии. Необходимо вызывать, если с текущей сессией запрос не был удачным.

.save()

this.sessionManager.save() - сохранение удачной сессии либо сохранение произвольных данных в сессии

results.<array>.addElement()

Метод results.<array>.addElement() позволяет более удобно заполнять массивы в results. При его использовании не нужно помнить последовательность переменных в массиве и перечислять их вручную.

results.serp.addElement({
link: 'https://google.com',
anchor: 'Google',
snippet: 'Loreps ipsum...',
});

Методы init() и destroy()

Метод init() вызывается при старте задания, destroy() - при завершении.

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

const puppeteer = require("puppeteer");
let globalBrowser;

class Parser {
constructor() {
...
}

async init() {
globalBrowser = await puppeteer.launch();
};

async destroy() {
if(globalBrowser)
await globalBrowser.close();
}
}

Полезные ссылки

Пример сохранения файла на диск

Пример, демонстрирующий способ сохранения файлов напрямую на диск

Пример работы с сессиями

Использование функционала сессий в JavaScript парсерах

Пример сохранения данных в сессии

Демонстрация возможности хранить произвольные данные в сессии

Использование results.addElement()

Пример заполнения массива данных с помощью results.addElement() и демонстрация отличия от обычного .push()