Verificação de backlinks de página na publicação, passo a passo
Um webhook, uma chamada HTTP, uma decisão. Este runbook guia uma equipe de CMS headless pelo gatilho, pelas chamadas e pelos casos de falha.
Equipe de pesquisa da Contentin ·
Decida o que o gate pode fazer
Uma verificação de backlinks de página dentro de um fluxo de lançamento é uma tarefa pequena. Mantenha-a pequena. A parte difícil é decidir qual resposta é permitida alterar, pois um grafo de links que é atualizado mensalmente não pode vetar uma página por conta própria.
Sugerimos que o gate emita um aviso, registre o log e permita que a compilação continue. Os padrões podem mudar. Bloqueios rígidos pertencem a coisas que você controla, como marcação quebrada ou tag canonical ausente. Dados de links são um sinal, e sinais mudam.
Escreva a política. Faça isso antes de codificar. Uma política de uma linha como "avisar o editor, marcar a entrada, nunca interromper o deploy" economiza uma longa discussão às 18h de um dia de lançamento. Também diz ao próximo engenheiro quais falhas foram intencionais e quais foram bugs, o que é mais importante do que parece. Revise-a uma vez por trimestre.
Seis etapas do clique de publicação à nota armazenada
1
Escolha o gatilho
Inscreva-se no evento de publicação do seu CMS. Contentful, Sanity e Strapi podem chamar uma URL de sua propriedade quando uma entrada é publicada, e Storyblok e Payload também oferecem webhooks ou hooks. Filtre pelos tipos de conteúdo que contêm URLs de saída ou canônicos.
2
Reduza a URL para um domínio
A API espera um domínio no parâmetro q, então https://www.example.com/blog/post?x=1 precisa se tornar example.com primeiro. Decida de uma vez como você trata o www e teste um domínio real na ação domain gratuita antes de construir qualquer coisa.
3
Chame a ação gratuita primeiro
overview não custa nada. Se o retorno for escasso, o domínio pode ser novo ou simplesmente desconhecido para nosso índice. Isso não é prova de nada ruim.
4
Gaste créditos apenas quando uma regra disparar
Quando sua regra indicar para olhar mais de perto, chame backlinks com per=100. Custa 2 créditos, independentemente do número de linhas, então solicite uma página útil de linhas em vez de dez pequenas.
5
Escreva uma nota, não o JSON bruto
Armazene um veredito curto em um campo seu, além da data da verificação. Respostas brutas incham as entradas e envelhecem mal, já que o índice muda todo mês.
6
Falha suave
HTTP 401 significa que a chave está ausente ou errada, então alerte um humano. HTTP 402 significa que os créditos acabaram. Qualquer outro erro: registre o log, pule a verificação e permita que a publicação continue.
Onde a chave está e o que um 402 deve fazer
Toda chamada paga carrega sua chave, seja na string de consulta ou em um cabeçalho Bearer. Prefira o cabeçalho. Uma string de consulta pode acabar nos logs do servidor e nos rastros de proxy, enquanto um cabeçalho geralmente fica fora deles.
Armazene a chave como um segredo na sua plataforma de hospedagem, nunca na entrada. Editores podem ler qualquer campo que consigam abrir, mas o ambiente de uma função geralmente é visível apenas para as pessoas que gerenciam os deploys.
Onde a chave deve viver?
Uma chave que vaza pode gastar o saldo da sua conta, então trate-a como uma senha. Mantenha-a fora do repositório e do CMS, e faça a rotação se um arquivo de log mostrar a chave em texto puro.
Marque seus logs com o nome do hook. O gasto fica fácil de rastrear até uma função, mesmo quando vários hooks compartilham a mesma conta.
Uma ferramenta no-code pode fazer a chamada?
Sim, quando a ferramenta tem uma etapa de solicitação HTTP simples. Muitos construtores de automação podem enviar um GET com uma string de consulta e ler o JSON de volta, então a ação gratuita de overview não precisa de código.
Comece apenas com as ações gratuitas. Um fluxo que dispara a cada salvamento de rascunho pode gastar créditos mais rápido do que um editor percebe, então adicione uma etapa paga apenas quando as chamadas gratuitas tiverem rodado silenciosamente por um tempo.
O que um 402 deve disparar?
Um 402 significa que o saldo está zerado. Isso não diz nada sobre a página. Pule a verificação paga, registre o evento e envie um alerta para quem recarrega a conta, depois permita que a publicação continue.
Defina um alarme de saldo bem acima de zero, para que o aviso chegue enquanto ainda há tempo para recarregar. Um loop de retry não ajudará aqui, pois toda chamada falhará da mesma forma até que alguém adicione crédito. A tabela de custos tem os valores.
Teste as duas chamadas a partir de um terminal
Execute estas uma vez contra um domínio que você conhece antes que o hook faça isso por você. Leia o campo _credits na segunda resposta.
bash
# free, no key
curl -s "https://contentin.app/api.php?action=overview&q=example.com"
# 2 credits, key in a header
curl -s -H "Authorization: Bearer sk_live_..." \
"https://contentin.app/api.php?action=backlinks&q=example.com&per=100"
Qual domínio vai para o parâmetro q
A API espera um domínio nu em q, então uma URL completa precisa ser reduzida primeiro. Escreva essa redução uma vez, em uma função. Depois, teste-a em URLs reais.
Links relativos e esquemas ausentes são os casos que geralmente quebram um hook. Uma redução que funciona em exemplos limpos ainda pode falhar nas URLs confusas que um editor cola às 17h.
O www muda a resposta?
Pode, e a maneira honesta de descobrir é perguntar. Execute a ação de domínio gratuita em ambas as formas de um site que você conhece, depois compare as duas respostas lado a lado.
Qualquer que seja a regra escolhida, escreva-a em um comentário de código para que o próximo engenheiro não precise adivinhar. Um comentário não custa nada e economiza uma longa discussão depois.
E quanto a redirecionamentos e subdomínios?
Envie o host onde seus leitores realmente chegam, não o link que um editor colou anos atrás. Se esse link redirecionar, reduza o endereço final e ignore a parada intermediária.
Um blog em seu próprio subdomínio é uma questão de julgamento. Decida antecipadamente se ele é verificado sozinho ou junto com seu domínio pai, e anote essa escolha ao lado da regra.
Lista de verificação pré-lançamento para o hook
O hook dispara apenas na publicação, não em cada salvamento de rascunho
A URL é reduzida para um domínio nu antes da chamada
Ações gratuitas são executadas primeiro e os créditos são gastos apenas em um sinalizador
Um 401 e um 402 têm seu próprio alerta e sua própria mensagem
Um tempo limite é definido, para que uma API lenta nunca trave um editor
A nota armazenada carrega uma data, para que ninguém a confunda com dados em tempo real
A mesma entrada publicada duas vezes não é cobrada duas vezes (veja a lista de mitos)
Uma linha de log para cada verificação pulada é o rastro de auditoria mais barato que você pode construir. Registre o ID da entrada, o domínio que você enviou, o código de status e se uma etapa paga foi executada. Geralmente, isso é suficiente.
A nota armazenada permanece curta e datada, como dizem as etapas acima. Respostas completas pertencem aos seus próprios logs, se pertencerem a algum lugar, porque são grandes e envelhecem rapidamente.
Quais campos pertencem a uma linha de log?
Comece com o ID da entrada e a versão de publicação. Um webhook repetido aparecerá como o mesmo par duas vezes, que é exatamente o que você quer ver.
Adicione o domínio, o nome da ação, o código de status e a hora em que a chamada começou. Deixe a chave fora, já que um log que a contém se torna um segundo lugar onde segredos vivem.
Por quanto tempo uma nota armazenada deve viver?
Enquanto a entrada existir, a menos que uma verificação mais nova a substitua. O que importa é que um leitor possa saber há quanto tempo a nota foi feita, porque uma nota de meses atrás parece dados em tempo real.
O guia do campo score mostra os quatro campos que sugerimos para essa nota, incluindo a data.
Teste o hook na staging antes do lançamento
Execute essas quatro verificações antes que alguém confie no hook.
1
Reproduza uma publicação passada
Acione o hook com uma cópia de uma entrada que você já publicou. Compare a nota armazenada com o que você esperava e confirme que a mesma entrada não foi cobrada duas vezes.
2
Tente um domínio registrado recentemente
Use um domínio de parceiro que é novo para você. Uma resposta vazia ou escassa deve ser armazenada como desconhecida, não como uma falha, e a nota deve dizer isso em palavras claras.
3
Force um 402 propositalmente
Execute o hook com uma chave em uma conta de teste cujo saldo você esvaziou. Confirme que o skip, a linha de log e o alerta todos disparam, e que a publicação ainda chega à compilação.
4
Leia a mensagem que o editor vê
Peça a alguém de fora da equipe para ler o texto do erro em voz alta. Se eles não conseguirem dizer o que fazer a seguir, reescreva a mensagem antes do dia do lançamento. O post-mortem mostra o que uma mensagem vaga custou a uma equipe inventada.
O que o hook não pode ver
Nosso índice é atualizado aproximadamente uma vez por mês. Um link adicionado após a última atualização não aparecerá, e um link removido desde então ainda pode aparecer. Para prova no mesmo dia, use o relatório Links no Google Search Console.
