Opis metod (v1)

ostrzeżenie

To JavaScript API jest uważane za przestarzałe, zalecamy korzystanie z API wersji 2

Należy pamiętać, że niektóre metody wymagają użycia słowa kluczowego yield

`yield this.request()`

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

Pobieranie odpowiedzi HTTP na zapytanie, jako argumenty podaje się:

method - metoda zapytania (GET, POST...)
url - link do zapytania
queryParams - hash z parametrami get lub hash z ciałem zapytania post
opts - hash z opcjami zapytania

Jeśli używana jest metoda POST, ciało zapytania można przekazać na dwa sposoby:

po prostu wymieniając nazwy zmiennych i ich wartości w queryParams. Na przykład:

{
    key: set.query,
    id: 1234,
    type: 'text'
}

poprzez zmienną body w opts. Na przykład:

body: 'key=' + set.query + '&id=1234&type=text'

`opts.check_content`

check_content: [ warunek1, warunek2, ...] - tablica warunków do sprawdzenia otrzymanej treści, jeśli sprawdzenie nie powiedzie się, zapytanie zostanie powtórzone z innym proxy.

Możliwości:

użycie ciągów znaków jako warunków (wyszukiwanie wystąpienia ciągu)
użycie wyrażeń regularnych jako warunków
użycie własnych funkcji sprawdzających, do których przekazywane są dane i nagłówki odpowiedzi
można zdefiniować kilka różnych typów warunków jednocześnie
dla negacji logicznej umieść warunek w tablicy, tj. check_content: ['xxxx', [/yyyy/]] oznacza, że zapytanie zostanie uznane za udane, jeśli otrzymane dane zawierają podciąg xxxx, a jednocześnie wyrażenie regularne /yyyy/ nie znajduje dopasowań na stronie

Aby zapytanie zakończyło się sukcesem, muszą zostać zaliczone wszystkie sprawdzenia określone w tablicy

Przykład (w komentarzach wskazano, co jest potrzebne, aby zapytanie zostało uznane za udane):

let response = yield this.request('GET', set.query, {}, {
    check_content: [
        /<\/html>|<\/body>/, //na otrzymanej stronie musi zadziałać to wyrażenie regularne
        ['XXXX'], //na otrzymanej stronie nie może być tego podciągu
        '</html>', //na otrzymanej stronie musi znajdować się taki podciąg
        (data, hdr) => {
            return hdr.Status == 200 && data.length > 100;
        } //ta funkcja musi zwrócić true
    ]
});

`opts.decode`

decode: 'auto-html' - automatyczne wykrywanie kodowania i konwersja na utf8

Możliwe wartości:

auto-html - na podstawie nagłówków, tagów meta i zawartości strony (optymalna zalecana opcja)
utf8 - wskazuje, że dokument jest w kodowaniu utf8
<encoding> - dowolne inne kodowanie

`opts.headers`

headers: { ... } - hash z nagłówkami, nazwa nagłówka musi być podana małymi literami, można określić m.in. cookie Przykład:

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', ...] - pozwala nadpisać kolejność sortowania nagłówków

`opts.recurse`

recurse: N - maksymalna liczba przekierowań, domyślnie 7, użyj 0 aby wyłączyć podążanie za przekierowaniami

`opts.proxyretries`

proxyretries: N - liczba prób wykonania zapytania, domyślnie pobierana z ustawień scrapera

`opts.parsecodes`

parsecodes: { ... } - lista kodów odpowiedzi HTTP, które scraper będzie uważał za udane, domyślnie pobierana z ustawień scrapera. Jeśli podasz '*': 1, wszystkie odpowiedzi będą uważane za udane. Przykład:

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

`opts.timeout`

timeout: N - limit czasu odpowiedzi w sekundach, domyślnie pobierany z ustawień scrapera

`opts.do_gzip`

do_gzip: 1 - określa, czy używać kompresji (gzip/deflate/br), domyślnie włączone (1), aby wyłączyć należy ustawić wartość 0

`opts.max_size`

max_size: N - maksymalny rozmiar odpowiedzi w bajtach, domyślnie pobierany z ustawień scrapera

`opts.cookie_jar`

cookie_jar: { ... } - hash z ciasteczkami.

`opts.attempt`

attempt: N - wskazuje numer bieżącej próby, przy użyciu tego parametru wbudowany mechanizm obsługi prób dla tego zapytania jest ignorowany

`opts.browser`

browser: 1 - automatyczna emulacja nagłówków przeglądarki (1 - włączone, 0 - wyłączone)

`opts.use_proxy`

use_proxy: 1 - nadpisuje użycie proxy dla pojedynczego zapytania wewnątrz scrapera JS ponad globalnym parametrem Use proxy (1 - włączone, 0 - wyłączone)

`opts.noextraquery`

noextraquery: 0 - wyłącza dodawanie Extra query string do adresu URL zapytania (1 - włączone, 0 - wyłączone)

`opts.save_to_file`

save_to_file: file - pozwala pobrać plik bezpośrednio na dysk, pomijając zapis do pamięci. Zamiast file podaje się nazwę i ścieżkę, pod jaką zapisać plik. Przy użyciu tej opcji ignorowane jest wszystko związane z data (sprawdzanie treści w check_content, response.data będzie puste itp.).

`opts.data_as_buffer`

data_as_buffer: 0 - określa, czy zwracać data jako ciąg String (0) czy jako obiekt Buffer (1), domyślnie zwracany jest ciąg String

`opts.bypass_cloudflare`

bypass_cloudflare: 0 - automatyczne omijanie ochrony JavaScript CloudFlare przy użyciu przeglądarki Chrome (1 - włączone, 0 - wyłączone)

`opts.follow_meta_refresh`

follow_meta_refresh: 0 - pozwala podążać za przekierowaniami zadeklarowanymi przez tag HTML meta:

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

`opts.tlsOpts`

tlsOpts: { ... } – pozwala przekazywać ustawienia dla połączeń https

`yield this.parser.request()`

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

Pobieranie wyników z innego scrapera (wbudowanego lub innego scrapera JS), jako argumenty podaje się:

parser - nazwa scrapera (SE::Google, JS::Custom::Example)
preset - preset ustawień wywoływanego scrapera
overrideParams - hash z nadpisaniami ustawień wywoływanego scrapera
query - zapytanie

W overrideParams można nadpisywać parametry wywoływanego scrapera, dostępne są również takie flagi:

`overrideParams.resultArraysWithObjects`

resultArraysWithObjects: 0 - określa, w jakiej formie zwracać tablice wyników wywoływanego scrapera:

jeśli włączone (1) - będą zwracane tablice obiektów

[{link: 'link1', anchor: 'anchor1'}, {link: 'link2', anchor: 'anchor2'}, ...]

jeśli wyłączone (0) - będą zwracane standardowe tablice wartości
```
['link1', 'anchor1', 'link2', 'anchor2', ...]
```

`overrideParams.needData`

needData: 1 - określa, czy przekazywać (1) czy nie (0) w odpowiedzi data/pages[], może być używane do optymalizacji

`tools.*`

Globalny obiekt tools, pozwala uzyskać dostęp do wbudowanych funkcji A-Parser (odpowiednik narzędzi silnika szablonów $tools.*).

notatka

tools.query nie jest dostępny, należy używać this.query

`this.doLog()`

Pokazuje, czy prowadzenie logu zadania jest włączone, może być używane jako flaga optymalizacji w przypadkach, gdy log nie jest prowadzony, a argumentem dla this.logger.put jest złożone wyrażenie

`this.logger.*`

`.put()`

this.logger.put(message) - dodaje wiersz message do logu zadania

`.putHTML()`

this.logger.putHTML(code) - wyprowadza do logu zadania kod HTML, który zostanie wyświetlony w textarea

`yield this.sleep()`

yield this.sleep(sec)

Ustawia opóźnienie w wątku na liczbę sekund sec, może być ułamkowa.

`yield this.mutex.*`

Muteks do synchronizacji między wątkami, pozwala zablokować sekcję kodu dla jednego wątku

`.lock()`

Oczekiwanie na blokadę, wykonanie będzie kontynuował pierwszy wątek, który przejął blokadę, pozostałe wątki będą oczekiwać na zwolnienie blokady

`.unlock()`

Zwolnienie blokady, następny wątek będzie kontynuował wykonanie, jeśli oczekiwał na blokadę (.lock())

`this.cookies.*`

Praca z ciasteczkami dla bieżącego zapytania

`.getAll()`

Pobieranie tablicy ciasteczek

`.setAll()`

Ustawianie ciasteczek, jako argument musi zostać przekazana tablica z ciasteczkami

`.set()`

this.cookies.set(host, path, name, value) - ustawianie pojedynczego ciasteczka

`this.query.add()`

this.query.add(query, maxLvl)

Dodawanie nowego zapytania (query) z opcjonalną możliwością określenia maksymalnego poziomu (maxLvl), analogicznie do tools.query.add() Jako zapytanie (query) można przekazać hash z parametrami, działa to analogicznie do Kreatora zapytań

Przykład:

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

`this.proxy.*`

Praca z proxy

`.next()`

Zmień proxy na następne, stare proxy nie będzie już używane dla bieżącego zapytania

`.ban()`

Zmień i zbanuj proxy (należy używać, gdy serwis blokuje pracę po IP), proxy zostanie zbanowane na czas określony w ustawieniach scrapera (proxybannedcleanup)

`.get()`

Pobierz bieżące proxy (ostatnie proxy, z którym wykonano zapytanie)

`.set()`

this.proxy.set('http://127.0.0.1:8080', noChange = false) - ustaw proxy dla następnego zapytania, parametr noChange jest opcjonalny, jeśli ustawiony na true, proxy nie będzie zmieniane między próbami

`yield this.captcha.*`

Praca z captchą

`.recognize()`

yield this.captcha.recognize(preset, image, type, overrides) - przesyłanie captchy do rozpoznania

image - dane binarne obrazka do rozpoznania
preset - wskazuje na preset dla Util::AntiGate
type określa się jeden z: 'jpeg', 'gif', 'png'

Wynikiem będzie hash z polami:

answer - tekst z obrazka
id - id captchy, aby móc później zgłosić błąd przez reportBad
error - błąd tekstowy, jeśli answer nie został podany

`.recognizeFromUrl()`

yield this.captcha.recognizeFromUrl(preset, url, overrides) - analogicznie do poprzedniej metody, ale pobieranie captchy zostanie wykonane automatycznie z linku (url), bez użycia proxy

`.reportBad()`

yield this.captcha.reportBad(preset, id, overrides) - zgłoś serwisowi, że captcha została rozwiązana błędnie

`this.utils.*`

`.updateResultsData()`

this.utils.updateResultsData(results, data) - metoda do automatycznego wypełniania $pages.$i.data oraz $data, należy ją wywołać w celu dodania treści strony wynikowej

`.urlFromHTML()`

this.utils.urlFromHTML(url, base) - przetwarza link otrzymany z kodu HTML - dekoduje encje (& itp.), opcjonalnie można przekazać base - bazowy adres URL (np. URL strony źródłowej), w ten sposób można uzyskać pełny link

`.url.extractDomain()`

this.utils.url.extractDomain(url, removeDefaultSubdomain) - metoda przyjmuje jako pierwszy parametr link i zwraca domenę z tego linku. Drugi opcjonalny parametr określa, czy odciąć subdomenę www z domeny. Domyślnie 0 - czyli nie odcinać.

`.url.extractTopDomain()`

this.utils.url.extractTopDomain(url) - metoda przyjmuje jako pierwszy parametr link i zwraca domenę z tego linku, bez subdomen.

`.url.extractTopDomainByZone()`

this.utils.url.extractTopDomainByZone(url) - metoda przyjmuje jako pierwszy parametr link i zwraca domenę z tego linku, w tym bez subdomen. Działa ze wszystkimi strefami regionalnymi

`.url.extractMaxPath()`

this.utils.url.extractMaxPath(url) - metoda przyjmuje ciąg znaków i wybiera z niego adres URL

`.url.extractWOParams()`

this.utils.url.extractWOParams(url)- metoda przyjmuje link i zwraca ten sam link obcięty do ciągu parametrów. Czyli zwróci URL do znaku ?

`.removeHtml()`

this.utils.removeHtml(string) - metoda przyjmuje ciąg znaków i zwraca go oczyszczonego z tagów html this.utils.removeNoDigit(string) - metoda przyjmuje ciąg znaków, usuwa z niego wszystko poza cyframi i zwraca wynik

`.removeNoDigit()`

this.utils.removeNoDigit(string) - metoda przyjmuje ciąg znaków, usuwa z niego wszystko poza cyframi i zwraca wynik

`.removeComma()`

this.utils.removeComma(string) - metoda przyjmuje ciąg znaków, usuwa z niego znaki takie jak .,\r\n i zwraca wynik

`this.sessionManager.*`

Aby korzystać z sesji w JS scraperze, należy najpierw zainicjować Menedżera sesji. Odbywa się to za pomocą funkcji init()

init() {
    this.sessionManager.init({
       //tutaj można zdefiniować dodatkowe parametry
    });
}

W this.sessionManager.init() można użyć następujących parametrów:

name - parametr opcjonalny, pozwala przedefiniować nazwę scrapera, do którego należą sesje, domyślnie równa nazwie scrapera, w którym następuje inicjalizacja
canChangeProxy - parametr opcjonalny, możliwość zmiany proxy, domyślnie wynosi 1
domain - opcjonalny parametr, wskazuje, aby wyszukiwać sesje wśród wszystkich zapisanych dla tego scrapera (jeśli wartość nie jest ustawiona), albo tylko dla konkretnej domeny (należy podawać domenę z kropką na początku, np. .site.com)

Do pracy z sesjami istnieje kilka funkcji:

`.get()`

this.sessionManager.get() - pobiera nową sesję, należy wywołać przed wykonaniem zapytania

`.reset()`

this.sessionManager.reset() - czyszczenie plików cookie i pobieranie nowej sesji. Należy wywołać, jeśli zapytanie z bieżącą sesją nie powiodło się.

`.save()`

this.sessionManager.save() - zapisywanie udanej sesji lub zapisywanie dowolnych danych w sesji

`results.<array>.addElement()`

Metoda results.<array>.addElement() pozwala na wygodniejsze wypełnianie tablic w results. Przy jej użyciu nie trzeba pamiętać kolejności zmiennych w tablicy i wymieniać ich ręcznie.

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

Metody `init()` i `destroy()`

Metoda init() jest wywoływana przy starcie zadania, destroy() - przy zakończeniu.

Przykład użycia:

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()
Metody init() i destroy()
Przydatne linki

yield this.request()​

opts.check_content​

Możliwości:​

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()​

Metody init() i destroy()​

Przydatne linki​

🔗 Przykład zapisywania pliku na dysk

🔗 Przykład pracy z sesjami

🔗 Przykład zapisywania danych w sesji

🔗 Użycie results.addElement()

`yield this.request()`

`opts.check_content`

Możliwości:

`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()`

Metody `init()` i `destroy()`

Przydatne linki