Verifica dei backlink alla pagina alla pubblicazione, passo dopo passo
Un webhook, una chiamata HTTP, una decisione. Questo runbook guida un team CMS headless attraverso il hook, le chiamate e i casi di errore.
Team di ricerca Contentin ·
Decidere cosa può fare il gate
Una verifica dei backlink alla pagina all'interno di un flusso di rilascio è un lavoro piccolo. Mantenetelo piccolo. La parte difficile è decidere quali risposte sono consentite, perché un grafo dei link che si aggiorna mensilmente non può di per sé bloccare una pagina.
Suggeriamo che il gate avvisi, registri il log e permetta al build di continuare. I valori predefiniti possono cambiare. I blocchi rigidi appartengono a cose che controllate, come markup rotto o un tag canonical mancante. I dati sui link sono un segnale, e i segnali possono variare.
Scrivetelo. Fatelo prima di codificarlo. Una politica di una riga come "avvisa l'editor, tagga la voce, non fermare mai il deploy" risparmia una lunga discussione alle 6 pm il giorno del rilascio. Indica anche al prossimo ingegnere quali errori erano intenzionali e quali erano bug, cosa che conta più di quanto sembri. Rivedetela una volta al trimestre.
Sei passaggi dal clic di pubblicazione alla nota archiviata
1
Scegliere il trigger
Iscrivetevi all'evento di pubblicazione del vostro CMS. Contentful, Sanity e Strapi possono chiamare un URL di vostra proprietà quando una voce viene pubblicata, e Storyblok e Payload offrono webhook o hook. Filtrate per i tipi di contenuto che contengono URL in uscita o canonical.
2
Ridurre l'URL a un dominio
L'API richiede un dominio in q, quindi https://www.example.com/blog/post?x=1 deve diventare example.com prima. Decidete una volta come trattate il www e testate un dominio reale sull'azione gratuita domain prima di costruire qualsiasi cosa.
3
Chiamare prima l'azione gratuita
overview non costa nulla. Se il risultato è scarso, il dominio potrebbe essere nuovo o semplicemente sconosciuto al nostro indice. Questo non è prova di nulla di negativo.
4
Spendere crediti solo quando una regola scatta
Quando la vostra regola dice di guardare più da vicino, chiamate backlinks con per=100. Costa 2 crediti, indipendentemente dal numero di righe, quindi chiedete una pagina utile di righe piuttosto che dieci piccole.
5
Scrivere una nota, non il JSON grezzo
Archiviate un breve verdetto in un campo vostro, insieme alla data della verifica. Le risposte grezze gonfiano le voci e invecchiano male, poiché l'indice si muove ogni mese.
6
Fallire in modo soft
HTTP 401 significa che la chiave manca o è errata, quindi avvisate un essere umano. HTTP 402 significa che i crediti sono finiti. Qualsiasi altro errore: registratelo nel log, saltate la verifica, permettete alla pubblicazione di procedere.
Dove risiede la chiave e cosa dovrebbe fare un 402
Ogni chiamata a pagamento trasporta la vostra chiave, sia nella query string che in un header Bearer. Preferite l'header. Una query string può finire nei log del server e nelle tracce dei proxy, mentre un header di solito rimane escluso.
Archiviate la chiave come segreto nella vostra piattaforma di hosting, mai nella voce stessa. Gli editor possono leggere qualsiasi campo che possono aprire, ma l'ambiente di una funzione è di solito visibile solo alle persone che gestiscono i deploy.
Dove dovrebbe risiedere la chiave?
Una chiave che fuoriesce può spendere il saldo sul vostro account, quindi trattatela come una password. Tenetela fuori dal repository e dal CMS, e ruotatela se un file di log la mostra mai in chiaro.
Taggate i vostri log con il nome del hook. La spesa è così facile da tracciare fino a una funzione, anche quando più hook condividono lo stesso account.
Può uno strumento no-code fare la chiamata?
Sì, quando lo strumento ha un passaggio di richiesta HTTP semplice. Molti builder di automazione possono inviare un GET con una query string e leggere il JSON restituito, quindi l'azione gratuita overview non richiede codice.
Iniziate solo con le azioni gratuite. Un flusso che si attiva su ogni salvataggio di bozza può spendere crediti più velocemente di quanto un editor se ne accorga, quindi aggiungete un passaggio a pagamento una volta che le chiamate gratuite sono state eseguite tranquillamente per un po' di tempo.
Cosa dovrebbe attivare un 402?
Un 402 significa che il saldo è vuoto. Non dice nulla sulla pagina. Saltate la verifica a pagamento, registrate l'evento e inviate un alert a chi ricarica l'account, poi permettete alla pubblicazione di procedere.
Impostate un allarme del saldo ben sopra zero, così l'avviso arriva mentre c'è ancora tempo per ricaricare. Un ciclo di retry non aiuterà qui, perché ogni chiamata fallirà allo stesso modo finché qualcuno non aggiunge credito. La tabella dei costi ha le cifre.
Testare le due chiamate da un terminale
Eseguitele una volta contro un dominio che conoscete prima che il hook lo faccia per voi. Leggete il campo _credits nella seconda risposta.
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"
Quale dominio va nel parametro q
L'API richiede un dominio nudo in q, quindi un URL completo deve essere ridotto prima. Scrivete quella riduzione una volta, in una funzione. Poi testatela su URL reali.
I link relativi e i protocolli mancanti sono i casi che di solito rompono un hook. Una riduzione che funziona su esempi puliti può ancora fallire sugli URL disordinati che un editor incolla alle 5 pm.
Il www cambia la risposta?
Potrebbe, e il modo onesto per scoprirlo è chiedere. Eseguite l'azione gratuita domain su entrambe le forme di un sito che conoscete, poi confrontate le due risposte fianco a fianco.
Qualunque sia la regola che scegliete, scrivetela in un commento di codice così il prossimo ingegnere non dovrà indovinare. Un commento non costa nulla e risparmia una lunga discussione più tardi.
E i redirect e i sottodomini?
Inviate l'host su cui atterrano effettivamente i vostri lettori, non il link che un editor ha incollato anni fa. Se quel link reindirizza, riducete l'indirizzo finale e ignorate il salto intermedio.
Un blog su un sottodominio è una valutazione soggettiva. Decidete in anticipo se viene controllato da solo o insieme al suo dominio padre, e scrivete quella scelta accanto alla regola.
Checklist pre-rilascio per il hook
Il hook si attiva solo alla pubblicazione, non su ogni salvataggio di bozza
L'URL è ridotto a un dominio nudo prima della chiamata
Le azioni gratuite vengono eseguite per prime e i crediti vengono spesi solo su un flag
Un 401 e un 402 hanno ciascuno il loro alert e il loro messaggio
È impostato un timeout, così un'API lenta non blocca mai un editor
La nota archiviata contiene una data, così nessuno la scambia per dati live
La stessa voce pubblicata due volte non viene fatturata due volte (vedi la lista dei miti)
Una riga di log per ogni verifica saltata è la traccia di audit più economica che possiate costruire. Registrare l'ID della voce, il dominio che avete inviato, il codice di stato e se è stato eseguito un passaggio a pagamento. Di solito è sufficiente.
La nota archiviata rimane breve e datata, come dicono i passaggi sopra. Le risposte complete appartengono ai vostri log, se appartengono da qualche parte, perché sono grandi e invecchiano rapidamente.
Quali campi appartengono a una riga di log?
Iniziate con l'ID della voce e la versione di pubblicazione. Un webhook ripetuto apparirà poi come la stessa coppia due volte, che è esattamente quello che volete vedere.
Aggiungete il dominio, il nome dell'azione, il codice di stato e l'ora di inizio della chiamata. Lasciate fuori la chiave stessa, poiché un log che la contiene diventa un secondo luogo dove risiedono i segreti.
Per quanto tempo dovrebbe vivere una nota archiviata?
Per tutto il tempo in cui vive la voce, a meno che un controllo più recente non la sostituisca. Ciò che conta è che un lettore possa capire quanto è vecchia la nota, perché una nota di mesi fa sembra dati live.
Eseguite questi quattro controlli prima che qualcuno si affidi al hook.
1
Riprodurre una pubblicazione passata
Attivate il hook con una copia di una voce che avete già pubblicato. Confrontate la nota archiviata con ciò che vi aspettavate e confermate che la stessa voce non sia stata fatturata due volte.
2
Provare un dominio registrato di recente
Usate un dominio partner che è nuovo per voi. Una risposta vuota o scarsa dovrebbe essere archiviata come sconosciuta, non come un fallimento, e la nota dovrebbe dirlo in parole chiare.
3
Forzare un 402 apposta
Eseguite il hook con una chiave su un account di test il cui saldo avete svuotato. Confermate che il salto, la riga di log e l'allarme si attivino tutti, e che la pubblicazione raggiunga comunque il build.
4
Leggere il messaggio che vede l'editor
Chiedete a qualcuno fuori dal team di leggere il testo dell'errore ad alta voce. Se non possono dire cosa fare dopo, riscrivete il messaggio prima del giorno del lancio. Il post-mortem mostra quanto è costato un messaggio vago a un team inventato.
Cosa non può vedere il hook
Il nostro indice si aggiorna circa una volta al mese. Un link aggiunto dopo l'ultimo aggiornamento non apparirà, e un link rimosso da allora potrebbe ancora apparire. Per una prova nello stesso giorno, usate il rapporto Links in Google Search Console.
