Creare uno strumento di verifica dei link inaccessibili

Questo documento descrive come configurare un test periodico dei link contenuti in un URI creando un monitoraggio sintetico. Specifica le opzioni per il test, ad esempio URI di origine, numero di link testati e numero di nuovi tentativi, quindi esegui il deployment di una Cloud Function preconfigurata. Per supportare le attività di risoluzione dei problemi e debug, i monitor sintetici salvano informazioni dettagliate su ogni test, inclusi screenshot. Gli screenshot ti consentono di visualizzare la risposta esatta vista dai clienti della tua applicazione.

Per scoprire di più sui monitoraggi sintetici, consulta Informazioni sui monitoraggi sintetici.

Informazioni sui controlli dei link inaccessibili

Ogni controllo dei link inaccessibili verifica i link in modo seriale ed esiste un timeout sintetico complessivo, configurabile.

Per impostazione predefinita, un controllo dei link inaccessibili:

  • Cerca l'URI di origine degli elementi anchor HTML con attributi href.
  • Testa i primi 10 link trovati nell'URI di origine.
  • Per ogni link, il controllo emette una richiesta e attende al massimo 30 secondi una risposta. Quando riceve una risposta, il controllo verifica che lo stato della risposta HTTP sia 200, che indica una risposta riuscita. Il controllo non esegue nuovi tentativi.

Tu specifichi l'URI di origine. Puoi configurare gli elementi HTML utilizzati dal controllo dei link inaccessibili, il numero massimo di elementi testati, il timeout per test e l'eventuale esecuzione di nuovi tentativi. Puoi anche configurare controlli dei link inaccessibili per attendere la comparsa di un selettore.

I controlli dei link inaccessibili utilizzano il modello broken-links-ok. La configurazione di un controllo dei link inaccessibili è specificata dall'oggetto options del file index.js. Se crei il controllo utilizzando la console Google Cloud, ti viene richiesta ogni opzione di configurazione e la Cloud Function viene aggiornata automaticamente. Tuttavia, se utilizzi l'API Cloud Monitoring o Terraform, devi completare questo oggetto.

Dopo aver creato un controllo dei link inaccessibili, per modificare la configurazione, aggiorna l'oggetto options ed esegui nuovamente il deployment della Cloud Function.

Prima di iniziare

  1. Per ottenere le autorizzazioni necessarie per visualizzare e modificare i monitoraggi sintetici utilizzando la console Google Cloud, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

    Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

  2. Abilita le API Cloud Monitoring API, Artifact Registry API, Cloud Build API, Cloud Functions API, Cloud Logging API, Pub/Sub API, and Cloud Run Admin API.

    Abilita le API

  3. Verifica che il progetto Google Cloud contenga l'account di servizio predefinito di Compute Engine. Questo account di servizio viene creato quando abiliti l'API Compute Engine e ha un nome simile a 12345-compute@developer.gserviceaccount.com.

    Nella console Google Cloud, vai alla pagina Account di servizio:

    Vai ad Account di servizio

    Se usi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo IAM e amministrazione.

    Se l'account di servizio Compute Engine predefinito non esiste, fai clic su Crea account di servizio e completa la finestra di dialogo.

  4. Assicurati che all'account di servizio Compute Engine predefinito, o all'account di servizio che hai creato, sia stato concesso il ruolo Editor (roles/editor).

    Per visualizzare i ruoli concessi al tuo account di servizio:

    1. Nella console Google Cloud, vai alla pagina IAM:

      Vai a IAM

      Se usi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo IAM e amministrazione.

    2. Seleziona Includi concessioni dei ruoli fornite da Google.
    3. Se l'account di servizio utilizzato dal monitoraggio sintetico non è in elenco o se non gli è stato concesso un ruolo che include le autorizzazioni nel ruolo di Agente Cloud Trace (roles/cloudtrace.agent), concedi questo ruolo al tuo account di servizio.
  5. Configura i canali di notifica che vuoi utilizzare per ricevere notifiche. Ti consigliamo di creare più tipi di canali di notifica. Per maggiori informazioni, vedi Creare e gestire canali di notifica e Creare e gestire canali di notifica tramite API.

Creare uno strumento di verifica dei link inaccessibili

Console

Quando crei un monitoraggio sintetico utilizzando la console Google Cloud, viene eseguito il deployment di una nuova Cloud Function (2ª generazione) e il relativo monitoraggio viene creato. Non puoi creare un monitoraggio sintetico per monitorare una Cloud Function esistente.

  1. Assicurati di aver abilitato le API richieste, che il progetto contenga un account di servizio Compute Engine predefinito e che all'account sia stato concesso il ruolo Editor (roles/editor). Per ulteriori informazioni, consulta Prima di iniziare.

  2. Nella console Google Cloud, vai alla pagina  Monitoraggio sintetico:

    Vai a Monitoraggio sintetico

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  3. Seleziona Crea monitoraggio sintetico.
  4. Per il modello, seleziona Verifica link non funzionanti.
  5. Inserisci un nome per il monitoraggio sintetico.

  6. (Facoltativo) Aggiorna il Timeout risposta, la Frequenza di controllo e aggiungi le etichette definite dall'utente.

  7. Configura l'URI e gli elementi da testare:

    1. Fai clic su URI di origine e inserisci un URI che vuoi testare. Il valore inserito deve essere un endpoint HTTP o HTTPS. Ad esempio, puoi inserire https://mywebsite.example.com.

    2. (Facoltativo) In Numero di link da seguire, aggiorna il numero massimo di link testati. Il valore predefinito di questo campo è 10.

    3. (Facoltativo) Nel campo Selettore di elementi HTML, inserisci l'elemento HTML che vuoi trovare sotto forma di elenco separato da virgole. Il valore inserito viene convertito in una stringa e poi passato al metodo Document: querySelectorAll().

      Per impostazione predefinita, questo campo è impostato su a, che corrisponde agli ancoraggi. Puoi inserire valori come a, img se vuoi abbinare sia gli ancoraggi che le immagini.

    4. (Facoltativo) Nel campo Attributi HTML da seguire, inserisci gli attributi HTML che vuoi trovare corrispondenti. I valori separati da virgole inseriti vengono passati singolarmente al metodo getAttribute().

      Per impostazione predefinita, questo campo è impostato su href, che specifica l'URI del link. Puoi inserire più attributi, ad esempio puoi inserire href, src. In questo esempio, il codice cerca l'attributo href e poi l'attributo src.

    5. (Facoltativo) Configura l'attesa per il selettore, il timeout per URI, i nuovi tentativi e i codici di stato previsti:

      1. Fai clic su Mostra altre opzioni.

      2. Per configurare il controllo dei link inaccessibili in modo che attenda la visualizzazione di un selettore specifico nell'URI prima che venga eseguito lo scraping dei link, inserisci i selettori CSS nel campo Attendi il selettore elemento. Il valore inserito viene convertito in una stringa e poi passato al metodo page.waitForSelector().

        Se il selettore non viene visualizzato prima della scadenza del timeout, l'errore viene registrato nei log.

      3. Aggiorna l'ordine in cui vengono selezionati i link per i test.

      4. Configura i nuovi tentativi.

        Per impostazione predefinita, viene inviata una richiesta a ciascun link e se la richiesta iniziale non va a buon fine per qualsiasi motivo, ad esempio, se ad esempio scade il comando o il codice di stato HTTP non è 200, il link viene contrassegnato come non riuscito.

        Questo campo specifica il numero di volte in cui lo strumento di verifica dei link inaccessibili può inviare una richiesta HTTP a un link prima di contrassegnare il collegamento come non riuscito.

      5. Configura un timeout che si applichi a ogni URI. Per impostazione predefinita, questo valore è impostato su 30 secondi.

      6. Per specificare il codice di stato previsto e il timeout per un URI specifico, fai clic su Aggiungi opzione per link e completa la finestra di dialogo.

  8. (Facoltativo) Configura se gli screenshot delle risposte vengono raccolti e salvati. Se utilizzi le impostazioni predefinite, gli screenshot non vengono salvati. Se attivi la raccolta di screenshot, puoi raccoglierli per tutti i test o solo per i test non riusciti. Cloud Monitoring utilizza la seguente convenzione per assegnare un nome al bucket Cloud Storage:

    gcm-PROJECT_ID-synthetics-LOCATION

    Nell'espressione precedente:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • LOCATION: la località del bucket Cloud Storage.

    Puoi scegliere di utilizzare un bucket Cloud Storage esistente.

  9. Rivedi la configurazione e assicurati che sia corretta e completa, quindi crea la funzione Cloud Function:

    1. Fai clic su Crea funzione.

      I valori nei campi Configurazione URI vengono copiati nell'oggetto Options nel file index.js quando fai clic su Crea funzione. Dopo aver fatto clic su Crea funzione, per cambiare la configurazione, modifica l'oggetto Options.

    2. Inserisci un nome visualizzato e seleziona una regione. I nomi devono essere univoci all'interno di una regione.

    3. Nella sezione Impostazioni di runtime, build, connessioni e sicurezza, segui questi passaggi:

      • Nella scheda Connessioni, assicurati che sia selezionata l'opzione Consenti tutto il traffico.

      • Rivedi le impostazioni predefinite e aggiornale quando necessario.

      • Nel campo Account di servizio di runtime, seleziona un account di servizio.

    4. Fai clic su Applica funzione.

  10. Configura il criterio di avviso:

    1. (Facoltativo) Aggiorna il nome del criterio di avviso e la durata dell'errore prima dell'invio delle notifiche.

    2. Aggiungi i canali di notifica.

  11. Fai clic su Crea.

    La funzione Cloud Functions che hai definito viene creata e ne viene eseguito il deployment come2ª generazionee, mentre viene creato il monitoraggio sintetico.

API

Il processo di creazione di un controllo dei link inaccessibili mediante l'API Cloud Monitoring è identico a quello di creazione di qualsiasi altro monitoraggio sintetico. Per informazioni sull'utilizzo dell'API Cloud Monitoring per creare un monitoraggio sintetico, consulta Creare un monitoraggio sintetico e seleziona la scheda Cloud Monitoring.

I controlli dei link inaccessibili utilizzano il modello broken-links-ok. La configurazione di un controllo dei link inaccessibili è specificata dall'oggetto options del file index.js.

Una volta definita la struttura options.screenshot_options, lo strumento di verifica dei link inaccessibili raccoglie gli screenshot e li salva in un bucket Cloud Storage. Se il campo screenshot_options.storage_location non è definito o se il valore è una stringa vuota, Monitoring crea un bucket Cloud Storage e gli screenshot vengono salvati in quel bucket. Monitoring utilizza la seguente convenzione per assegnare un nome al bucket Cloud Storage:

gcm-PROJECT_ID-synthetics-LOCATION

Nell'espressione precedente:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud.
  • LOCATION: la località del bucket Cloud Storage.

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, vedi Comandi Terraform di base. Per maggiori informazioni, consulta la documentazione di riferimento del provider Terraform.

Il processo di creazione di un controllo di link inaccessibili mediante Terraform è identico a quello di creazione di qualsiasi altro monitoraggio sintetico. Per informazioni sull'utilizzo di Terraform per creare un monitoraggio sintetico, consulta Creare un monitoraggio sintetico e seleziona la scheda Terraform.

I controlli dei link inaccessibili utilizzano il modello broken-links-ok. La configurazione di un controllo dei link inaccessibili è specificata dall'oggetto options del file index.js.

Una volta definita la struttura options.screenshot_options, lo strumento di verifica dei link inaccessibili raccoglie gli screenshot e li salva in un bucket Cloud Storage. Se il campo screenshot_options.storage_location non è definito o se il valore è una stringa vuota, Monitoring crea un bucket Cloud Storage e gli screenshot vengono salvati in quel bucket. Monitoring utilizza la seguente convenzione per assegnare un nome al bucket Cloud Storage:

gcm-PROJECT_ID-synthetics-LOCATION

Nell'espressione precedente:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud.
  • LOCATION: la località del bucket Cloud Storage.

Esplora i risultati

Per ogni esecuzione, un controllo di link inaccessibili esegue le seguenti operazioni:

  • Genera una tabella in cui ogni riga fornisce informazioni sul test di uno specifico URI. Le informazioni di riepilogo includono URI di destinazione, latenza, stato e identificatore dell'elemento HTML. Ad esempio, questa colonna elenca a quando viene testato un elemento anchor HTML. Quando la riga corrisponde all'URI di origine, il valore dell'identificatore dell'elemento HTML è -.

  • Raccoglie metriche, dati di traccia e dati di log.

  • Raccoglie screenshot, se configurati.

Per maggiori informazioni su come esplorare i dati raccolti, consulta Esplorare i risultati del monitoraggio sintetico.

Risolvere i problemi

Questa sezione fornisce informazioni che possono aiutarti a risolvere i problemi relativi ai controlli dei link inaccessibili.

Impossibile modificare la configurazione di uno strumento di verifica dei link inaccessibili

Hai creato un controllo dei link inaccessibili utilizzando la console Google Cloud e vuoi modificare gli elementi HTML testati o modificare il timeout dell'URI, i nuovi tentativi, attendi il selettore e le opzioni per link. Tuttavia, quando modifichi lo strumento di verifica dei link inaccessibili, nella console Google Cloud non vengono visualizzati i campi di configurazione.

Per risolvere l'errore:

  1. Nella console Google Cloud, vai alla pagina  Monitoraggio sintetico:

    Vai a Monitoraggio sintetico

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  2. Individua il monitor sintetico che vuoi modificare, fai clic su Altre opzioni, quindi seleziona Modifica.
  3. Fai clic su Modifica funzione.

  4. Modifica l'oggetto options nel file index.js, quindi fai clic su Applica funzione.

    Per informazioni sui campi e sulla sintassi per questo oggetto, consulta broken-links-ok/index.js.

  5. Fai clic su Salva.

Visualizza la console Google Cloud che non riesce a salvare screenshot

Hai creato uno strumento di verifica dei link inaccessibili e l'hai configurato in modo da salvare gli screenshot. Tuttavia, nella console Google Cloud viene visualizzato uno dei seguenti messaggi di avviso insieme a informazioni più dettagliate:

  • InvalidStorageLocation
  • StorageValidationError
  • BucketCreationError
  • ScreenshotFileUploadError

Per risolvere questi errori, prova a procedere nel seguente modo:

  • Se viene visualizzato il messaggio InvalidStorageLocation, verifica l'esistenza del bucket Cloud Storage specificato nel campo denominato options.screenshot_options.storage_location.

  • Visualizza i log relativi alla tua Cloud Function. Per ulteriori informazioni, consulta Trovare i log.

  • Verifica che l'account di servizio in uso nella Cloud Function corrispondente disponga di un ruolo Identity and Access Management che gli consenta di creare, accedere e scrivere nei bucket Cloud Storage.

Passaggi successivi