Pular para o conteúdo principal

Descrição de métodos (v1)

aviso

Esta API de JavaScript é considerada obsoleta, recomendamos usar a API versão 2

Observe que alguns métodos exigem o uso da palavra-chave yield

yield this.request()​

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

Obtenção de resposta HTTP por solicitação, os seguintes argumentos são especificados:

  • method - método da solicitação (GET, POST...)
  • url - link para a solicitação
  • queryParams - hash com parâmetros get ou hash com o corpo da solicitação post
  • opts - hash com opções da solicitação

Se o método POST for utilizado, o corpo da solicitação pode ser enviado de duas formas:

  • apenas listando os nomes das variáveis e seus valores em queryParams. Por exemplo:
{
    key: set.query,
    id: 1234,
    type: 'text'
}
  • através da variável body em opts. Por exemplo:
body: 'key=' + set.query + '&id=1234&type=text'

opts.check_content​

check_content: [ condição1, condição2, ...] - array de condições para verificar o conteúdo recebido; se a verificação falhar, a solicitação será repetida com outro proxy.

Recursos:​

  • uso de strings como condições (busca por ocorrência de string)
  • uso de expressões regulares como condições
  • uso de funções de verificação personalizadas, para as quais são passados os dados e os cabeçalhos da resposta
  • é possível definir vários tipos diferentes de condições simultaneamente
  • para negação lógica, coloque a condição em um array, ou seja, check_content: ['xxxx', [/yyyy/]] significa que a solicitação será considerada bem-sucedida se os dados recebidos contiverem a substring xxxx e, ao mesmo tempo, a expressão regular /yyyy/ não encontrar correspondências na página

Para uma solicitação bem-sucedida, todas as verificações especificadas no array devem passar

Exemplo (os comentários indicam o que é necessário para que a solicitação seja considerada bem-sucedida):

let response = yield this.request('GET', set.query, {}, {
    check_content: [
        /<\/html>|<\/body>/, //esta expressão regular deve ser acionada na página recebida
        ['XXXX'], //esta substring não deve estar presente na página recebida
        '</html>', //esta substring deve estar presente na página recebida
        (data, hdr) => {
            return hdr.Status == 200 && data.length > 100;
        } //esta função deve retornar true
    ]
});

opts.decode​

decode: 'auto-html' - detecção automática de codificação e conversão para utf8

Valores possíveis:

  • auto-html - baseado em cabeçalhos, tags meta e conteúdo da página (opção recomendada ideal)
  • utf8 - indica que o documento está na codificação utf8
  • <encoding> - qualquer outra codificação

opts.headers​

headers: { ... } - hash com cabeçalhos, o nome do cabeçalho é definido em letras minúsculas, pode-se especificar inclusive cookie Exemplo:

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', ...] - permite redefinir a ordem de classificação dos cabeçalhos

opts.recurse​

recurse: N - número máximo de redirecionamentos, o padrão é 7, use 0 para desativar o seguimento de redirecionamentos

opts.proxyretries​

proxyretries: N - número de tentativas de execução da solicitação, por padrão é obtido das configurações do scraper

opts.parsecodes​

parsecodes: { ... } - lista de códigos de resposta HTTP que o scraper considerará bem-sucedidos, por padrão é obtido das configurações do scraper. Se especificar '*': 1, todas as respostas serão consideradas bem-sucedidas. Exemplo:

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

opts.timeout​

timeout: N - tempo limite de resposta em segundos, por padrão é obtido das configurações do scraper

opts.do_gzip​

do_gzip: 1 - determina se deve usar compressão (gzip/deflate/br), ativado por padrão (1), para desativar defina o valor como 0

opts.max_size​

max_size: N - tamanho máximo da resposta em bytes, por padrão é obtido das configurações do scraper

opts.cookie_jar​

cookie_jar: { ... } - hash com cookies.

opts.attempt​

attempt: N - indica o número da tentativa atual; ao usar este parâmetro, o manipulador de tentativas integrado para esta solicitação é ignorado

opts.browser​

browser: 1 - emulação automática de cabeçalhos de navegador (1 - ativado, 0 - desativado)

opts.use_proxy​

use_proxy: 1 - substitui o uso de proxy para uma solicitação individual dentro do scraper JS sobre o parâmetro global Use proxy (1 - ativado, 0 - desativado)

opts.noextraquery​

noextraquery: 0 - desativa a adição de Extra query string à URL da solicitação (1 - ativado, 0 - desativado)

opts.save_to_file​

save_to_file: file - permite baixar o arquivo diretamente para o disco, ignorando a gravação na memória. Em vez de file, especifique o nome e o caminho sob o qual salvar o arquivo. Ao usar esta opção, tudo relacionado a data é ignorado (verificação de conteúdo em check_content, response.data ficará vazio, etc.).

opts.data_as_buffer​

data_as_buffer: 0 - determina se deve retornar data como uma string String (0) ou como um objeto Buffer (1), por padrão retorna uma string String

opts.bypass_cloudflare​

bypass_cloudflare: 0 - contorno automático da proteção JavaScript do CloudFlare usando o navegador Chrome (1 - ativado, 0 - desativado)

opts.follow_meta_refresh​

follow_meta_refresh: 0 - permite seguir redirecionamentos declarados via tag HTML meta:

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

opts.tlsOpts​

tlsOpts: { ... } – permite passar configurações para conexões https ​

yield this.parser.request()​

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

Obtenção de resultados de outro scraper (integrado ou outro scraper JS), os seguintes argumentos são especificados:

  • parser - nome do scraper (SE::Google, JS::Custom::Example)
  • preset - predefinição de configurações do scraper chamado
  • overrideParams - hash com substituições de configurações do scraper chamado
  • query - consulta

Em overrideParams é possível redefinir parâmetros do scraper chamado, também estão disponíveis estas flags:

overrideParams.resultArraysWithObjects​

resultArraysWithObjects: 0 - determina em que formato retornar os arrays de resultados do scraper chamado:

  • se ativado (1) - serão retornados arrays de objetos
    [{link: 'link1', anchor: 'anchor1'}, {link: 'link2', anchor: 'anchor2'}, ...]
  • se desativado (0) - serão retornados arrays padrão de valores
    ['link1', 'anchor1', 'link2', 'anchor2', ...]

overrideParams.needData​

needData: 1 - determina se deve passar (1) ou não (0) data/pages[] na resposta, pode ser usado para otimização

tools.*​

Objeto global tools, permite acessar as funções integradas do A-Parser (análogo às ferramentas do motor de modelos $tools.*).

nota

tools.query não está disponível, é necessário usar this.query

this.doLog()​

Indica se o registro de log da tarefa está ativado, pode ser usado como uma flag para otimização, para casos onde o log não é registrado e o argumento para this.logger.put é uma expressão complexa

this.logger.*​

.put()​

this.logger.put(message) - adiciona a linha message ao log da tarefa

.putHTML()​

this.logger.putHTML(code) - exibe código HTML no log da tarefa, que será renderizado no textarea

yield this.sleep()​

yield this.sleep(sec)

Define um atraso na thread por um número de segundos sec, podendo ser fracionário.

yield this.mutex.*​

Mutex para sincronização entre threads, permite bloquear uma seção de código para uma única thread

.lock()​

Aguardando o lock, a execução continuará pela primeira thread que capturou o lock, as outras threads aguardarão a liberação do lock

.unlock()​

Liberação do lock, a próxima thread continuará a execução se estiver aguardando o lock (.lock())

this.cookies.*​

Trabalho com cookies para a solicitação atual

.getAll()​

Obtenção de um array de cookies

.setAll()​

Definição de cookies, um array com cookies deve ser passado como argumento

.set()​

this.cookies.set(host, path, name, value) - definição de um único cookie

this.query.add()​

this.query.add(query, maxLvl)

Adição de uma nova consulta (query) com a possibilidade opcional de especificar o nível máximo (maxLvl), similar a tools.query.add() É possível passar como consulta (query) um hash com parâmetros, funciona de forma análoga ao Construtor de Consultas

Exemplo:

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

this.proxy.*​

Trabalho com proxy

.next()​

Mudar o proxy para o próximo, o proxy antigo não será mais usado para a solicitação atual

.ban()​

Mudar e banir o proxy (deve ser usado quando o serviço bloqueia o trabalho por IP), o proxy será banido pelo tempo especificado nas configurações do scraper (proxybannedcleanup)

.get()​

Obter o proxy atual (o último proxy com o qual a solicitação foi feita)

.set()​

this.proxy.set('http://127.0.0.1:8080', noChange = false) - define o proxy para a próxima solicitação, o parâmetro noChange é opcional; se definido como true, o proxy não mudará entre as tentativas

yield this.captcha.*​

Trabalho com captcha

.recognize()​

yield this.captcha.recognize(preset, image, type, overrides) - carregamento de captcha para reconhecimento

  • image - dados binários da imagem para reconhecimento
  • preset - indica o preset para o Util::AntiGateUtil::AntiGate
  • type especifica um dos seguintes: 'jpeg', 'gif', 'png'

O resultado será um hash com os campos:

  • answer - texto da imagem
  • id - id do captcha, para possibilidade futura de relatar erro através de reportBad
  • error - erro de texto, se answer não estiver definido

.recognizeFromUrl()​

yield this.captcha.recognizeFromUrl(preset, url, overrides) - similar ao método anterior, mas o carregamento do captcha será realizado automaticamente pelo link (url), sem o uso de proxy

.reportBad()​

yield this.captcha.reportBad(preset, id, overrides) - informar ao serviço que o captcha foi resolvido incorretamente

this.utils.*​

.updateResultsData()​

this.utils.updateResultsData(results, data) - método para preenchimento automático de $pages.$i.data e $data, deve ser chamado para adicionar o conteúdo da página resultante

.urlFromHTML()​

this.utils.urlFromHTML(url, base) - processa um link obtido de código HTML - decodifica entidades (&amp; etc.), opcionalmente pode-se passar base - URL base (por exemplo, a URL da página de origem), permitindo obter o link completo

.url.extractDomain()​

this.utils.url.extractDomain(url, removeDefaultSubdomain) - o método recebe como primeiro parâmetro um link e retorna o domínio desse link. O segundo parâmetro opcional determina se deve remover o subdomínio www do domínio. O padrão é 0 - ou seja, não remover.

.url.extractTopDomain()​

this.utils.url.extractTopDomain(url) - o método recebe como primeiro parâmetro um link e retorna o domínio desse link, sem subdomínios.

.url.extractTopDomainByZone()​

this.utils.url.extractTopDomainByZone(url) - o método recebe como primeiro parâmetro um link e retorna o domínio desse link, inclusive sem subdomínios. Funciona com todas as zonas regionais

.url.extractMaxPath()​

this.utils.url.extractMaxPath(url) - o método recebe uma string e extrai uma URL dela

.url.extractWOParams()​

this.utils.url.extractWOParams(url)- o método recebe um link e retorna o mesmo link cortado até a string de parâmetros. Ou seja, retornará a URL até o ?

.removeHtml()​

this.utils.removeHtml(string) - o método recebe uma string e a retorna limpa de tags html

.removeNoDigit()​

this.utils.removeNoDigit(string) - o método recebe uma string, remove tudo exceto dígitos e retorna o resultado

.removeComma()​

this.utils.removeComma(string) - o método recebe uma string, remove caracteres como .,\r\n e retorna o resultado

this.sessionManager.*​

Para usar sessões no scraper JS, primeiro é necessário inicializar o Gerenciador de Sessões. Isso é feito usando a função init()

init() {
    this.sessionManager.init({
       //aqui você pode definir parâmetros adicionais
    });
}

Em this.sessionManager.init() podem ser usados os seguintes parâmetros:

  • name - parâmetro opcional, permite redefinir o nome do scraper ao qual as sessões pertencem, por padrão é igual ao nome do scraper onde ocorre a inicialização
  • canChangeProxy - parâmetro opcional, possibilidade de mudar o proxy, por padrão é igual a 1
  • domain - parâmetro opcional, indica para procurar sessões entre todas as salvas para este scraper (se o valor não for definido), ou apenas para um domínio específico (é necessário especificar o domínio com um ponto na frente, por exemplo .site.com)

Existem várias funções para trabalhar com sessões:

.get()​

this.sessionManager.get() - obtém uma nova sessão, deve ser chamado antes de realizar a solicitação

.reset()​

this.sessionManager.reset() - limpeza de cookies e obtenção de uma nova sessão. Deve ser chamado se a solicitação com a sessão atual não foi bem-sucedida.

.save()​

this.sessionManager.save() - salvamento de uma sessão bem-sucedida ou salvamento de dados arbitrários na sessão

results.<array>.addElement()​

O método results.<array>.addElement() permite preencher arrays em results de forma mais conveniente. Ao usá-lo, não é necessário lembrar a sequência de variáveis no array e listá-las manualmente.

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

Métodos init() e destroy()​

O método init() é chamado no início da tarefa, destroy() - na conclusão.

Exemplo de uso:

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

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

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