Pular para o conteúdo
SEOCheck
SEOCheckCadastre-se

Engenharia

Insira dados de links em um pipeline sem quebrá-lo

Puxar uma tabela uma vez é fácil. Puxá-la todo mês por um ano sem lacunas silenciosas é o verdadeiro trabalho.

Equipe de pesquisa da SEOCheck ·

Sistema de tubos de água fluindo através de rochas mostrando pipeline de dados confiável

Um job mensal em doze linhas

Python, apenas biblioteca padrão. Ele pagina pelos domínios de referência e para em um erro alto. Cada resposta coloca suas linhas em rows; adicione per (10 a 5000) para páginas maiores, e o loop para assim que tiver lido total linhas.

python
import json, urllib.request as u
KEY='sk_live_...'
def get(**p):
    q='&'.join(f'{k}={v}' for k,v in p.items())
    url=f'https://seocheck.dev/api.php?{q}&key={KEY}'
    with u.urlopen(url) as r:
        return json.load(r)
rows, page = [], 1
while True:
    d = get(action='refdomains', q='example.com', page=page)
    if not d['ok']: raise SystemExit(d)
    rows += d['rows']
    if not d['rows'] or len(rows) >= d['total']: break
    page += 1
print(len(rows), 'of', d['total'], 'balance', d['_credits']['balance'])

Por que jobs de api de backlink seo falham silenciosamente

Não com um crash. Com uma tabela que está faltando a última página. A causa usual é um loop que termina em um palpite em vez de em uma contagem.

Verifique três coisas em cada execução. ok voltou true? A contagem de linhas atingiu total? _credits mostrou o saldo que você espera? Se alguma resposta for não, falhe o job e avise alguém.

Sucesso silencioso é pior que uma falha barulhenta. Um job que termina com as linhas erradas parece saudável até alguém ler a planilha.

Limites de taxa e respostas lentas importam menos aqui do que em muitas APIs. Um job mensal pode simplesmente tentar novamente uma hora depois. O que importa é que as tentativas não cobrem duas vezes você por uma chamada que já teve sucesso. Registre o saldo de _credits antes e depois de cada execução e compare. Um salto maior do que o custo esperado do job significa que algo loopou. Investigue isso antes da próxima execução.

Equipes que já executam Airflow ou um cron simples em um pequeno servidor não precisam de nada novo. Um agendamento do GitHub Actions também funciona. A estrutura permanece a mesma: buscar, validar, armazenar, alertar. Veja a comparação de custos se você está avaliando isso contra uma exportação de suíte.

Armadilhas comuns de ingestão

ArmadilhaSintomaCorreção
Filtragem client-side após a paginaçãoExecuções lentas, páginas desperdiçadasUse sort e order server-side, depois corte
Paginação além do limiteLoop nunca terminaPaginação profunda para em 50.000 linhas; planeje-se para isso
Tratar HTTP 402 como um bugJob tenta novamente para sempre402 significa que os créditos acabaram; recarregue, não tente novamente
Tratar 401 como transitórioIgualChave inválida; alerte e pare
Comparando meses cegamenteQuedas fantasmasAtualizações de índice mensais; compare similar com similar
Misturando fornecedores de pontuaçãoTendências sem sentidoUma fonte por planilha

Uma forma sensata para o todo

01

Mantenha uma lista de domínios em um só lugar

Uma planilha ou uma tabela. Uma coluna de domínios, nada mais no início.

02

Pontue a lista com bulk_dr

Até 2.000 domínios por chamada, um crédito. GET com domains= ou POST a lista como o corpo quando for longa.

03

Puxe detalhes apenas para os sobreviventes

Execute refdomains ou anchors na fatia superior. Dois créditos por chamada, até 1.000 linhas cada.

04

Armazene snapshots, não substituições

Data cada puxada. Tendências precisam de histórico.

05

Alerte sobre mudanças

Uma queda de DR de vários pontos em um domínio de fornecedor vale uma mensagem.

Google Sheets e CORS

CORS está aberto, então um snippet de navegador ou um Apps Script pode chamar a API diretamente. Um pequeno exemplo para uma função de célula. A função retorna a Domain Rating do domínio na célula.

javascript
function DR(domain){
  var url='https://seocheck.dev/api.php?action=domain&q='+encodeURIComponent(domain);
  var r=JSON.parse(UrlFetchApp.fetch(url).getContentText());
  return r.metrics.dr;
}
Árvore de carvalho resistente com raízes profundas representando atualizações mensais estáveis

Atualidade e honestidade

O índice é reconstruído cerca de uma vez por mês a partir do nosso próprio crawler. Espere atraso. Dados com mais de algumas semanas são normais. Não agende puxadas horárias; elas retornam a mesma coisa e custam créditos.

Escolha o dia após a atualização quando puder. Caso contrário, execute no mesmo dia todo mês e aceite o pequeno atraso.

Suítes completas de palavras-chave, crawls diários e rastreamento de posições vivem em outro lugar. Ahrefs e Semrush cobrem isso; leia a comparação de custos antes de duplicar qualquer coisa. A referência de endpoints tem todos os parâmetros.

Quatro ferramentas distintas em uma bancada representando etapas modulares do pipeline

Projetando o job para que você possa confiar nele

Um pipeline é tão bom quanto sua execução mais fraca. Construa cada execução para deixar evidências, para que um mês ruim possa ser explicado em vez de adivinhado. O trabalho extra é pequeno. Economiza muita discussão depois, e também economiza créditos.

Pense em quatro etapas: buscar, validar, armazenar e alertar. Mantenha cada uma simples. Cada etapa deve ser capaz de falhar sozinha, e cada falha deve dizer qual etapa quebrou. As mesmas quatro etapas se aplicam a qualquer job de api de backlink seo, independente da linguagem em que você o escreva.

Armazene a resposta bruta antes de transformá-la

Salve o JSON exatamente como ele voltou, com a data e os parâmetros da chamada no nome do arquivo ou em uma linha de cabeçalho. Quando um número parecer errado no próximo trimestre, você pode voltar ao que a API realmente disse em vez de para uma planilha que alguém editou.

Arquivos brutos custam pouco para manter. Uma planilha que foi substituída três vezes não pode dizer o que aconteceu em março.

Mantenha um log de execução com a contagem de linhas e saldo

Cada execução deve adicionar uma linha a um log: a hora de início, as chamadas feitas, as linhas retornadas, o valor de total e o saldo de _credits. O log é o primeiro lugar para olhar quando um número muda.

Se as linhas retornadas não corresponderem a total, a execução está incompleta. Marque-a como falha, mantenha o arquivo parcial e não o mescle na tendência.

Separe tentativas de novas execuções

Uma tentativa repete uma chamada que falhou sem resposta. Uma nova execução repete um job inteiro que terminou mas precisa ser refazido. Trate-os diferentemente, porque uma tentativa de uma chamada que na verdade teve sucesso pode custar créditos duas vezes.

Se você não consegue dizer se uma chamada teve sucesso, leia o log antes de enviá-la novamente. Esse único hábito evita a maioria dos encargos surpresa.

Alerte sobre as falhas que importam

Um alerta só é útil quando alguém age sobre ele. Envie um para uma chave falha, um saldo vazio, uma contagem de linhas que não corresponde a total e um custo muito acima da figura esperada. Deixe os sucessos rotineiros fora da mensagem, ou as pessoas deixarão de lê-la.

Agendamento sem desperdiçar créditos

O agendamento deve seguir os dados, não o relógio. Um job que roda a cada hora paga pela mesma snapshot vinte e quatro vezes por dia, é por isso que o ritmo mensal importa tanto para esse tipo de trabalho.

Escolha um agendamento uma vez e anote-o. Mudá-lo todo mês é como uma linha de tendência pega degraus artificiais.

Mensal vence horário para esses dados

O índice é reconstruído cerca de uma vez por mês. Puxadas mais frequentes que isso retornam a mesma coisa e custam créditos. Se você precisar de uma execução extra, faça-a após uma atualização conhecida, não no meio de uma.

Um job, muitos domínios

Coloque todos os domínios em uma única lista e execute a pontuação em uma única passagem. Uma chamada bulk_dr lida com até 2.000 domínios por um crédito, então uma lista de 1.500 prospects custa o mesmo que uma lista de dez. Divida o trabalho apenas quando um domínio precisar de dados mais profundos, como refdomains.

Mantenha a lista em um só lugar. Duas cópias de uma lista de domínios se separam, e então sua tendência compara conjuntos diferentes de sites.

Quem deve ser dono do job

Dê ao job um único dono, mesmo que ele rode em um servidor compartilhado. Alguém deve responder quando o alerta disparar, verificar o saldo e decidir se um mês falho precisa de uma nova execução. Sem um dono, um job que falha silenciosamente pode passar despercebido por um trimestre. Escreva o nome do dono no cabeçalho do log, para que a próxima pessoa saiba a quem perguntar.

Teste em uma lista pequena primeiro

Quando você mudar um job, execute-o em cinco domínios antes de apontá-lo para a lista completa. Um erro em um loop mostra-se em segundos em uma amostra pequena e em créditos em uma grande. O teste de cinco domínios custa quase nada. Cinco domínios são suficientes para mostrar um loop.

Mantenha essa lista de teste no repositório junto ao job, para que seja a mesma toda vez que você verificar.

Quando um pipeline é a resposta errada

Um pipeline ganha seu lugar quando você precisa dos mesmos números repetidas vezes. Escolha a ferramenta certa. Para uma única pergunta, uma puxada manual é frequentemente a melhor ferramenta. Seja honesto sobre qual dos dois você realmente precisa.

A outra razão para pular o pipeline é a forma do trabalho. Se a pergunta muda toda semana, um job fixo continuará medindo a coisa errada.

Uma exportação única não é um pipeline

Digamos que você precise dos domínios de referência de um rival para uma única proposta. Execute refdomains uma vez, salve o arquivo e siga em frente. Construir um job agendado para isso adicionaria manutenção sem adicionar insights.

Quando seus números encontram outros dados

Dados de links respondem a um tipo de pergunta. Se você precisa juntá-los com rankings de palavras-chave, conversões ou logs de chamadas, mantenha a junção no seu próprio sistema e mantenha a snapshot de links como uma entrada. Não espere que a API segure as outras fontes para você.

Decida o que você mantém, e por quanto tempo

Decida, antes da primeira execução, quais campos você armazena e por quanto tempo os mantém do seu lado. Reduza as linhas que você não precisa. Um arquivo menor é mais fácil de compartilhar com um cliente ou colega, e mais fácil de excluir quando o projeto termina.

A referência de endpoints lista todos os campos e o custo de cada chamada, o que torna essa decisão mais fácil de anotar.

Lista de pré-voo

  • Chave armazenada como segredo, não no repositório.
  • Loop termina na contagem de linhas, não na esperança.
  • HTTP 401 e 402 tratados separadamente.
  • Snapshots datados e mantidos.
  • Um fornecedor de pontuação por tabela.
  • Agendamento mensal, não horário.