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

предупреждение

Данное 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.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 можно переопределять параметры вызываемого парсера, также доступны такие флаги:

`overrideParams.resultArraysWithObjects`

resultArraysWithObjects: 0 - определяет в каком виде возвращать массивы результатов вызываемого парсера:

если включено (1) - будут возвращаться массивы объектов
```
[{link: 'link1', anchor: 'anchor1'}, {link: 'link2', anchor: 'anchor2'}, ...]
```
если выключено (0) - будут возвращаться стандартные массивы значений
```
['link1', 'anchor1', 'link2', 'anchor2', ...]
```

`overrideParams.needData`

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

`tools.*`

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

примечание

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::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 (& и т.п.), опционально можно передавать 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();
    }
}

yield this.request()
yield this.parser.request()
- overrideParams.resultArraysWithObjects
- overrideParams.needData
tools.*
this.doLog()
this.logger.*
- .put()
- .putHTML()
yield this.sleep()
yield this.mutex.*
- .lock()
- .unlock()
this.cookies.*
this.query.add()
this.proxy.*
yield this.captcha.*
this.utils.*
this.sessionManager.*
results.<array>.addElement()
Методы init() и destroy()
Полезные ссылки

yield this.request()​

opts.check_content​

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

opts.decode​

opts.headers​

opts.headers_order​

opts.recurse​

opts.proxyretries​

opts.parsecodes​

opts.timeout​

opts.do_gzip​

opts.max_size​

opts.cookie_jar​

opts.attempt​

opts.browser​

opts.use_proxy​

opts.noextraquery​

opts.save_to_file​

opts.data_as_buffer​

opts.bypass_cloudflare​

opts.follow_meta_refresh​

opts.tlsOpts​

yield this.parser.request()​

overrideParams.resultArraysWithObjects​

overrideParams.needData​

tools.*​

this.doLog()​

this.logger.*​

.put()​

.putHTML()​

yield this.sleep()​

yield this.mutex.*​

.lock()​

.unlock()​

this.cookies.*​

.getAll()​

.setAll()​

.set()​

this.query.add()​

this.proxy.*​

.next()​

.ban()​

.get()​

.set()​

yield this.captcha.*​

.recognize()​

.recognizeFromUrl()​

.reportBad()​

this.utils.*​

.updateResultsData()​

.urlFromHTML()​

.url.extractDomain()​

.url.extractTopDomain()​

.url.extractTopDomainByZone()​

.url.extractMaxPath()​

.url.extractWOParams()​

.removeHtml()​

.removeNoDigit()​

.removeComma()​

this.sessionManager.*​

.get()​

.reset()​

.save()​

results.<array>.addElement()​

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

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

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

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

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

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

`yield this.request()`

`opts.check_content`

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

`opts.decode`

`opts.headers`

`opts.headers_order`

`opts.recurse`

`opts.proxyretries`

`opts.parsecodes`

`opts.timeout`

`opts.do_gzip`

`opts.max_size`

`opts.cookie_jar`

`opts.attempt`

`opts.browser`

`opts.use_proxy`

`opts.noextraquery`

`opts.save_to_file`

`opts.data_as_buffer`

`opts.bypass_cloudflare`

`opts.follow_meta_refresh`

`opts.tlsOpts`

`yield this.parser.request()`

`overrideParams.resultArraysWithObjects`

`overrideParams.needData`

`tools.*`

`this.doLog()`

`this.logger.*`

`.put()`

`.putHTML()`

`yield this.sleep()`

`yield this.mutex.*`

`.lock()`

`.unlock()`

`this.cookies.*`

`.getAll()`

`.setAll()`

`.set()`

`this.query.add()`

`this.proxy.*`

`.next()`

`.ban()`

`.get()`

`.set()`

`yield this.captcha.*`

`.recognize()`

`.recognizeFromUrl()`

`.reportBad()`

`this.utils.*`

`.updateResultsData()`

`.urlFromHTML()`

`.url.extractDomain()`

`.url.extractTopDomain()`

`.url.extractTopDomainByZone()`

`.url.extractMaxPath()`

`.url.extractWOParams()`

`.removeHtml()`

`.removeNoDigit()`

`.removeComma()`

`this.sessionManager.*`

`.get()`

`.reset()`

`.save()`

`results.<array>.addElement()`

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

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