Descrizione dei metodi (v1)

avvertimento

Questa JavaScript API è considerata obsoleta, si consiglia di utilizzare l' API versione 2

Si prega di notare che alcuni metodi richiedono l'uso della parola chiave yield

`yield this.request()`

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

Ottenere una risposta HTTP tramite richiesta, gli argomenti specificati sono:

method - metodo della richiesta (GET, POST...)
url - link per la richiesta
queryParams - hash con parametri get o hash con il corpo della richiesta post
opts - hash con le opzioni della richiesta

Se viene utilizzato il metodo POST, il corpo della richiesta può essere trasmesso in due modi:

elencando semplicemente i nomi delle variabili e i loro valori in queryParams. Ad esempio:

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

tramite la variabile body in opts. Ad esempio:

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

`opts.check_content`

check_content: [ condizione1, condizione2, ...] - array di condizioni per verificare il contenuto ricevuto; se la verifica fallisce, la richiesta verrà ripetuta con un altro proxy.

Funzionalità:

utilizzo di stringhe come condizioni (ricerca per occorrenza della stringa)
utilizzo di espressioni regolari come condizioni
utilizzo di funzioni di verifica personalizzate, a cui vengono passati i dati e gli header della risposta
è possibile impostare contemporaneamente diversi tipi di condizioni
per la negazione logica, inserire la condizione in un array, ovvero check_content: ['xxxx', [/yyyy/]] significa che la richiesta sarà considerata riuscita se i dati ricevuti contengono la sottostringa xxxx e allo stesso tempo l'espressione regolare /yyyy/ non trova corrispondenze nella pagina

Per una richiesta riuscita, devono passare tutte le verifiche specificate nell'array

Esempio (nei commenti è indicato cosa serve affinché la richiesta sia considerata riuscita):

let response = yield this.request('GET', set.query, {}, {
    check_content: [
        /<\/html>|<\/body>/, //questa espressione regolare deve corrispondere nella pagina ricevuta
        ['XXXX'], //questa sottostringa non deve essere presente nella pagina ricevuta
        '</html>', //questa sottostringa deve essere presente nella pagina ricevuta
        (data, hdr) => {
            return hdr.Status == 200 && data.length > 100;
        } //questa funzione deve restituire true
    ]
});

`opts.decode`

decode: 'auto-html' - rilevamento automatico della codifica e conversione in utf8

Valori possibili:

auto-html - basato su header, tag meta e contenuto della pagina (opzione consigliata ottimale)
utf8 - indica che il documento è in codifica utf8
<encoding> - qualsiasi altra codifica

`opts.headers`

headers: { ... } - hash con gli header, il nome dell'header va specificato in minuscolo, è possibile indicare anche i cookie Esempio:

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', ...] - consente di ridefinire l'ordine di ordinamento degli header

`opts.recurse`

recurse: N - numero massimo di reindirizzamenti (redirect), predefinito 7, utilizzare 0 per disabilitare i redirect

`opts.proxyretries`

proxyretries: N - numero di tentativi di esecuzione della richiesta, per impostazione predefinita viene preso dalle impostazioni dello scraper

`opts.parsecodes`

parsecodes: { ... } - elenco dei codici di risposta HTTP che lo scraper considererà riusciti, per impostazione predefinita viene preso dalle impostazioni dello scraper. Se si specifica '*': 1, tutte le risposte saranno considerate riuscite. Esempio:

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

`opts.timeout`

timeout: N - timeout della risposta in secondi, per impostazione predefinita viene preso dalle impostazioni dello scraper

`opts.do_gzip`

do_gzip: 1 - determina se utilizzare la compressione (gzip/deflate/br), abilitato per impostazione predefinita (1), per disabilitare impostare il valore a 0

`opts.max_size`

max_size: N - dimensione massima della risposta in byte, per impostazione predefinita viene preso dalle impostazioni dello scraper

`opts.cookie_jar`

cookie_jar: { ... } - hash con i cookie.

`opts.attempt`

attempt: N - indica il numero del tentativo corrente; quando si utilizza questo parametro, il gestore dei tentativi integrato per questa richiesta viene ignorato

`opts.browser`

browser: 1 - emulazione automatica degli header del browser (1 - abilitato, 0 - disabilitato)

`opts.use_proxy`

use_proxy: 1 - ridefinisce l'uso del proxy per una singola richiesta all'interno dello scraper JS rispetto al parametro globale Use proxy (1 - abilitato, 0 - disabilitato)

`opts.noextraquery`

noextraquery: 0 - disabilita l'aggiunta di Extra query string all'URL della richiesta (1 - abilitato, 0 - disabilitato)

`opts.save_to_file`

save_to_file: file - consente di scaricare un file direttamente su disco, evitando la scrittura in memoria. Al posto di file si specifica il nome e il percorso con cui salvare il file. Quando si utilizza questa opzione, viene ignorato tutto ciò che riguarda data (verifica del contenuto in check_content, response.data sarà vuoto, ecc.).

`opts.data_as_buffer`

data_as_buffer: 0 - determina se restituire data come stringa String (0) o come oggetto Buffer (1), per impostazione predefinita viene restituita una stringa String

`opts.bypass_cloudflare`

bypass_cloudflare: 0 - bypass automatico della protezione JavaScript di CloudFlare utilizzando il browser Chrome (1 - abilitato, 0 - disabilitato)

`opts.follow_meta_refresh`

follow_meta_refresh: 0 - consente di seguire i redirect dichiarati tramite il meta tag HTML:

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

`opts.tlsOpts`

tlsOpts: { ... } – consente di passare le impostazioni per le connessioni https

`yield this.parser.request()`

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

Ottenere i risultati da un altro scraper (integrato o un altro scraper JS), gli argomenti specificati sono:

parser - nome dello scraper (SE::Google, JS::Custom::Example)
preset - preset delle impostazioni dello scraper chiamato
overrideParams - hash con le ridefinizioni delle impostazioni dello scraper chiamato
query - richiesta

In overrideParams è possibile ridefinire i parametri dello scraper chiamato, sono inoltre disponibili questi flag:

`overrideParams.resultArraysWithObjects`

resultArraysWithObjects: 0 - determina in quale formato restituire gli array dei risultati dello scraper chiamato:

se abilitato (1) - verranno restituiti array di oggetti

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

se disabilitato (0) - verranno restituiti array standard di valori
```
['link1', 'anchor1', 'link2', 'anchor2', ...]
```

`overrideParams.needData`

needData: 1 - determina se trasmettere (1) o meno (0) nella risposta data/pages[], può essere utilizzato per l'ottimizzazione

`tools.*`

Oggetto globale tools, consente di accedere alle funzioni integrate di A-Parser (analogo agli strumenti del template toolkit $tools.*).

nota

tools.query non è disponibile, è necessario utilizzare this.query

`this.doLog()`

Indica se la registrazione del log dell'attività è abilitata, può essere utilizzato come flag per l'ottimizzazione, nei casi in cui il log non viene registrato e l'argomento per this.logger.put è un'espressione complessa

`this.logger.*`

`.put()`

this.logger.put(message) - aggiunge la riga message al log dell'attività

`.putHTML()`

this.logger.putHTML(code) - output nel log dell'attività di codice HTML, che verrà visualizzato nella textarea

`yield this.sleep()`

yield this.sleep(sec)

Imposta un ritardo nel thread per il numero di secondi sec, può essere frazionario.

`yield this.mutex.*`

Mutex per la sincronizzazione tra i thread, consente di bloccare una sezione di codice per un singolo thread

`.lock()`

Attesa del lock, l'esecuzione continuerà con il primo thread che ha acquisito il lock, gli altri thread attenderanno il rilascio del lock

`.unlock()`

Rilascio del lock, il thread successivo continuerà l'esecuzione se era in attesa del lock (.lock())

`this.cookies.*`

Lavoro con i cookie per la richiesta corrente

`.getAll()`

Ottenere un array di cookie

`.setAll()`

Impostazione dei cookie, come argomento deve essere passato un array con i cookie

`.set()`

this.cookies.set(host, path, name, value) - impostazione di un singolo cookie

`this.query.add()`

this.query.add(query, maxLvl)

Aggiunta di una nuova query (query) con la possibilità opzionale di specificare il livello massimo (maxLvl), analogamente a tools.query.add() È possibile passare come query (query) un hash con i parametri, funziona analogamente al Costruttore di query

Esempio:

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

`this.proxy.*`

Lavoro con i proxy

`.next()`

Cambiare il proxy con il successivo, il vecchio proxy non verrà più utilizzato per la richiesta corrente

`.ban()`

Cambiare e bannare il proxy (necessario quando il servizio blocca l'operazione per IP), il proxy verrà bannato per il tempo specificato nelle impostazioni dello scraper (proxybannedcleanup)

`.get()`

Ottenere il proxy corrente (l'ultimo proxy con cui è stata effettuata la richiesta)

`.set()`

this.proxy.set('http://127.0.0.1:8080', noChange = false) - impostare il proxy per la richiesta successiva, il parametro noChange è opzionale, se impostato su true il proxy non cambierà tra i tentativi

`yield this.captcha.*`

Lavoro con i captcha

`.recognize()`

yield this.captcha.recognize(preset, image, type, overrides) - caricamento del captcha per il riconoscimento

image - dati binari dell'immagine per il riconoscimento
preset - indica il preset per Util::AntiGate
type specificare uno tra: 'jpeg', 'gif', 'png'

Il risultato sarà un hash con i campi:

answer - testo dall'immagine
id - id del captcha, per poter segnalare successivamente un errore tramite reportBad
error - errore testuale, se answer non è impostato

`.recognizeFromUrl()`

yield this.captcha.recognizeFromUrl(preset, url, overrides) - analogo al metodo precedente, ma il caricamento del captcha verrà eseguito automaticamente tramite link (url), senza l'uso di proxy

`.reportBad()`

yield this.captcha.reportBad(preset, id, overrides) - segnalare al servizio che il captcha è stato risolto in modo errato

`this.utils.*`

`.updateResultsData()`

this.utils.updateResultsData(results, data) - metodo per la compilazione automatica di $pages.$i.data e $data, necessario chiamarlo per aggiungere il contenuto della pagina risultante

`.urlFromHTML()`

this.utils.urlFromHTML(url, base) - elabora un link ottenuto dal codice HTML - decodifica le entità (& ecc.), opzionalmente è possibile passare base - URL di base (ad esempio l'URL della pagina di origine), in questo modo è possibile ottenere il link completo

`.url.extractDomain()`

this.utils.url.extractDomain(url, removeDefaultSubdomain) - il metodo accetta come primo parametro un link e restituisce il dominio da quel link. Il secondo parametro opzionale determina se rimuovere il sottodominio www dal dominio. Per impostazione predefinita 0 - ovvero non rimuovere.

`.url.extractTopDomain()`

this.utils.url.extractTopDomain(url) - il metodo accetta come primo parametro un link e restituisce il dominio da quel link, senza sottodomini.

`.url.extractTopDomainByZone()`

this.utils.url.extractTopDomainByZone(url) - il metodo accetta come primo parametro un link e restituisce il dominio da quel link, inclusi i casi senza sottodomini. Funziona con tutte le zone regionali

`.url.extractMaxPath()`

this.utils.url.extractMaxPath(url) - il metodo accetta una stringa e seleziona un URL da essa

`.url.extractWOParams()`

this.utils.url.extractWOParams(url)- il metodo accetta un link e restituisce lo stesso link troncato prima della stringa dei parametri. Ovvero restituirà l'URL fino al ?

`.removeHtml()`

this.utils.removeHtml(string) - il metodo accetta una stringa e la restituisce pulita dai tag html

`.removeNoDigit()`

this.utils.removeNoDigit(string) - il metodo accetta una stringa, rimuove tutto tranne le cifre e restituisce il risultato

`.removeComma()`

this.utils.removeComma(string) - il metodo accetta una stringa, rimuove caratteri come .,\r\n e restituisce il risultato

`this.sessionManager.*`

Per utilizzare le sessioni nello scraper JS, è necessario prima inizializzare il Gestore delle sessioni. Questo viene fatto utilizzando la funzione init()

init() {
    this.sessionManager.init({
       //qui è possibile impostare parametri aggiuntivi
    });
}

In this.sessionManager.init() è possibile utilizzare i seguenti parametri:

name - parametro opzionale, consente di ridefinire il nome dello scraper a cui appartengono le sessioni, per impostazione predefinita è uguale al nome dello scraper in cui avviene l'inizializzazione
canChangeProxy - parametro opzionale, possibilità di cambiare proxy, per impostazione predefinita è uguale a 1
domain - parametro opzionale, indica di cercare le sessioni tra tutte quelle salvate per questo scraper (se il valore non è impostato), oppure solo per un dominio specifico (è necessario specificare il dominio con un punto davanti, ad esempio .site.com)

Esistono diverse funzioni per lavorare con le sessioni:

`.get()`

this.sessionManager.get() - ottiene una nuova sessione, deve essere chiamato prima di effettuare una richiesta

`.reset()`

this.sessionManager.reset() - pulizia dei cookie e ottenimento di una nuova sessione. Deve essere chiamato se la richiesta con la sessione corrente non ha avuto successo.

`.save()`

this.sessionManager.save() - salvataggio di una sessione riuscita o salvataggio di dati arbitrari nella sessione

`results.<array>.addElement()`

Il metodo results.<array>.addElement() consente di compilare gli array in results in modo più comodo. Utilizzandolo, non è necessario ricordare la sequenza delle variabili nell'array ed elencarle manualmente.

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

Metodi `init()` e `destroy()`

Il metodo init() viene chiamato all'avvio dell'attività, destroy() - al completamento.

Esempio di utilizzo:

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()
Metodi init() e destroy()
Link utili

yield this.request()​

opts.check_content​

Funzionalità:​

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

Metodi init() e destroy()​

Link utili​

🔗 Esempio di salvataggio di un file su disco

🔗 Esempio di lavoro con le sessioni

🔗 Esempio di salvataggio dei dati nella sessione

🔗 Utilizzo di results.addElement()

`yield this.request()`

`opts.check_content`

Funzionalità:

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

Metodi `init()` e `destroy()`

Link utili