Creare uno strumento di controllo 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 l'URI di origine, il numero di link testati e il numero di nuovi tentativi, quindi esegui il deployment di una Cloud Function preconfigurata. Per supportare le operazioni 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 ai clienti della tua applicazione.

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

Informazioni sulla verifica dei link inaccessibili

Ogni strumento di controllo dei link interrotti verifica i link in serie ed è previsto un timeout sintetico complessivo configurabile.

Per impostazione predefinita, uno strumento di controllo dei link inaccessibili:

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

Devi specificare l'URI di origine. Puoi configurare gli elementi HTML cercati dallo strumento, il numero massimo di elementi testati, il timeout per test e l'eventuale esecuzione di nuovi tentativi. Puoi anche configurare i controlli dei link inaccessibili in modo che attendano la visualizzazione di un selettore.

Gli strumenti di controllo dei link non funzionanti utilizzano il modello broken-links-ok. La configurazione di uno strumento di controllo dei link inaccessibili è specificata dall'oggetto options del file index.js. Se crei il controllo utilizzando la console Google Cloud, vengono richieste tutte le opzioni di configurazione e la Cloud Function viene aggiornata automaticamente. Tuttavia, se utilizzi l'API Cloud Monitoring o Terraform, devi compilare questo oggetto.

Dopo aver creato uno strumento di 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 monitor sintetici utilizzando la console Google Cloud, chiedi all'amministratore di concederti i seguenti ruoli IAM sul tuo progetto:

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

    Potresti anche essere in grado di 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 Compute Engine predefinito. Questo account di servizio viene creato quando abiliti l'API Compute Engine e ha un nome simile a 12345-compute@developer.gserviceaccount.com.

    Nel pannello di navigazione della console Google Cloud, seleziona IAM e amministrazione, quindi Account di servizio:

    Vai ad Account di servizio

    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. Nel pannello di navigazione della console Google Cloud, seleziona IAM:

      Vai a IAM

    2. Seleziona Includi concessioni di ruoli fornite da Google.
    3. Se l'account di servizio utilizzato dal monitoraggio sintetico non è elencato 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 le notifiche. Ti consigliamo di creare più tipi di canali di notifica. Per maggiori informazioni, consulta Creare e gestire i canali di notifica e Creare e gestire i canali di notifica tramite API.

Creare uno strumento di controllo 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 viene creato il relativo monitor. Non puoi creare un monitoraggio sintetico per monitorare una Cloud Function esistente.

  1. Assicurati di aver abilitato le API richieste, che il tuo progetto contenga un account di servizio Compute Engine predefinito e che a questo account sia stato concesso il ruolo Editor (roles/editor). Per saperne di più, consulta Prima di iniziare.

  2. Nel pannello di navigazione della console Google Cloud, seleziona Monitoring, quindi  Monitoraggio sintetico:

    Vai a Monitoraggio sintetico

  3. Seleziona Crea monitoraggio sintetico.
  4. Per il modello, seleziona Verifica link inaccessibili.
  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 l'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 sottoposti a test. Il valore predefinito di questo campo è 10.

    3. (Facoltativo) Nel campo Selettore di elementi HTML, inserisci l'elemento HTML che vuoi abbinare, sotto forma di elenco separato da virgole. Il valore inserito viene convertito in stringa e poi trasmesso 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 gli ancoraggi e le immagini.

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

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

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

      1. Fai clic su Mostra altre opzioni.

      2. Per configurare lo strumento di controllo dei link inaccessibili in modo che venga visualizzato un selettore specifico nell'URI prima che venga eseguito lo scraping di eventuali link, inserisci i selettori CSS nel campo Attendi il selettore di elementi. Il valore inserito viene convertito in stringa e poi trasmesso 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 i link vengono selezionati 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 si verifica il timeout del 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 link come non riuscito.

      5. Configura un timeout che si applichi a ciascun 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 vengono raccolti e salvati gli screenshot delle risposte. Se utilizzi le impostazioni predefinite, gli screenshot non vengono salvati. Se abiliti la raccolta di screenshot, puoi raccoglierli per tutti i test o solo per quelli non superati. Cloud Monitoring utilizza la convenzione seguente 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.

    Hai la possibilità di utilizzare un bucket Cloud Storage esistente.

  9. Rivedi la configurazione, assicurati che sia corretta e completa, quindi crea la tua 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:

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

      • Controlla le impostazioni predefinite e aggiornale se 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 sottoposto a deployment come 2ª generazione, dopodiché viene creato il monitor sintetico.

API

Il processo di creazione di uno strumento di verifica dei link non funzionanti utilizzando 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 Creazione di un monitoraggio sintetico e seleziona la scheda Cloud Monitoring.

Gli strumenti di controllo dei link non funzionanti utilizzano il modello broken-links-ok. La configurazione di uno strumento di controllo dei link inaccessibili è specificata dall'oggetto options del file index.js.

Quando viene definita la struttura options.screenshot_options, lo strumento di controllo 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 convenzione seguente per assegnare il 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, consulta Comandi Terraform di base. Per maggiori informazioni, consulta la documentazione di riferimento del provider Terraform.

Il processo di creazione di una verifica di link non funzionanti utilizzando Terraform è identico a quello di creazione di qualsiasi altro monitor sintetico. Per informazioni sull'utilizzo di Terraform per creare un monitoraggio sintetico, consulta Creare un monitoraggio sintetico e seleziona la scheda Terraform.

Gli strumenti di controllo dei link non funzionanti utilizzano il modello broken-links-ok. La configurazione di uno strumento di controllo dei link inaccessibili è specificata dall'oggetto options del file index.js.

Quando viene definita la struttura options.screenshot_options, lo strumento di controllo 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 convenzione seguente per assegnare il 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, uno strumento di controllo dei link inaccessibili:

  • Genera una tabella in cui ogni riga fornisce informazioni sui test di un URI specifico. 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 di ancoraggio 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 gli screenshot, se configurati.

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

Risolvere i problemi

Questa sezione fornisce informazioni che possono essere utili per risolvere i problemi relativi alla verifica dei link non funzionanti.

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

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

Per risolvere l'errore:

  1. Nel pannello di navigazione della console Google Cloud, seleziona Monitoring, quindi  Monitoraggio sintetico:

    Vai a Monitoraggio sintetico

  2. Individua il monitor sintetico da modificare, fai clic su Altre opzioni, poi seleziona Modifica.
  3. Fai clic su Modifica funzione.

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

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

  5. Fai clic su Salva.

La console Google Cloud mostra che il salvataggio degli screenshot non riesce

Hai creato uno strumento di controllo dei link non funzionanti e l'hai configurato per salvare gli screenshot. Tuttavia, la console Google Cloud mostra uno dei seguenti messaggi di avviso insieme a informazioni più dettagliate:

  • InvalidStorageLocation
  • StorageValidationError
  • BucketCreationError
  • ScreenshotFileUploadError

Per risolvere questi errori, prova quanto segue:

  • 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 l'articolo Trovare i log.

  • Verifica che l'account di servizio utilizzato nella Cloud Function corrispondente abbia un ruolo Identity and Access Management che consente di creare, accedere e scrivere nei bucket Cloud Storage.

Passaggi successivi