Creare un controllo dei link interrotti

Questo documento descrive come configurare un test periodico dei link contenuti in un URI creando un monitor sintetico. Specifichi le opzioni per il test, come l'URI di origine, il numero di link testati e il numero di tentativi, quindi esegui il deployment di una funzione Cloud Run preconfigurata. Per supportare i tuoi sforzi 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 visualizzata dai clienti della tua applicazione.

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

Questa funzionalità è supportata solo per i progetti Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.

Informazioni sui controlli dei link non funzionanti

Ogni controllo dei link non funzionanti testa i link in serie e viene applicato un timeout sintetico complessivo, configurabile.

Per impostazione predefinita, un controllo dei link non funzionanti esegue le seguenti operazioni:

  • Cerca nell'URI di origine elementi di ancoraggio HTML con attributi href.
  • Esegue il test dei primi 10 link trovati nell'URI di origine.
  • Per ogni link, il controllo invia una richiesta e attende al massimo 30 secondi per una risposta. Quando viene ricevuta una risposta, il controllo verifica che lo stato della risposta HTTP sia 200, che indica una risposta riuscita. Il controllo non esegue nuovi tentativi.

Specifica l'URI di origine. Puoi configurare gli elementi HTML che il controllo dei link non funzionanti cerca, il numero massimo di elementi testati, il timeout per test e se vengono eseguiti tentativi. Puoi anche configurare i controlli dei link non funzionanti in modo che attendano la visualizzazione di un selettore.

I controlli dei link non funzionanti utilizzano il modello broken-links-ok. La configurazione di un controllo dei link non funzionanti è specificata dall'oggetto options del file index.js. Se crei il controllo utilizzando la consoleGoogle Cloud , ti viene chiesto di specificare ogni opzione di configurazione e la funzione Cloud Run viene aggiornata automaticamente. Tuttavia, se utilizzi l'API Cloud Monitoring o Terraform, devi compilare questo oggetto.

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

Prima di iniziare

Completa i seguenti passaggi nel progetto Google Cloud che memorizzerà il controllo dei link:

  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 progetto:

    Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

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

  2. Enable the Cloud Monitoring API, Artifact Registry API, Cloud Build API, Cloud Functions API, Cloud Logging API, Pub/Sub API, and Cloud Run Admin API APIs.

    Enable the APIs

  3. Verifica che il tuo 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.

    Nella console Google Cloud , vai alla pagina Service account:

    Vai ad Account di servizio

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

    Se il account di servizio Compute Engine predefinito non esiste, fai clic su Crea service account 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 utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo IAM e amministrazione.

    2. Seleziona Includi concessioni di ruoli fornite da Google.
    3. Se il account di servizio utilizzato dal monitor sintetico non è elencato o se non gli è stato concesso un ruolo che include le autorizzazioni del 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 saperne di più, consulta Creare e gestire i canali di notifica e Creare e gestire i canali di notifica tramite API.

  6. Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    Terraform

    Per utilizzare gli esempi di Terraform in questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Install the Google Cloud CLI.

    2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    3. To initialize the gcloud CLI, run the following command: 

      gcloud init

    4. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale nella documentazione sull'autenticazione Google Cloud .

    REST

    Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

      After installing the Google Cloud CLI, initialize it by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    Per saperne di più, consulta la sezione Autenticarsi per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud .

    Crea un controllo dei link non funzionanti

    Console

    Quando crei un monitor sintetico utilizzando la console, viene eseguito il deployment di una nuova funzione Cloud Run (2ª generazione) e viene creato il monitor per quella funzione Cloud Run. Google Cloud Non puoi creare un monitor sintetico che monitori una funzione Cloud Run esistente.

    1. Assicurati di aver attivato 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. 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. Nella barra degli strumenti della console Google Cloud , seleziona il tuo Google Cloud progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
    4. Seleziona Crea monitoraggio sintetico.
    5. Per il modello, seleziona Controllo link non funzionanti.
    6. Inserisci un nome per il monitor sintetico.

    7. (Facoltativo) Aggiorna il timeout di risposta, la frequenza di controllo e aggiungi etichette definite dall'utente.

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

      1. Fai clic su URI origine e inserisci un URI da testare. Il valore che inserisci deve essere un endpoint HTTP o HTTPS. Ad esempio, potresti 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 elemento HTML, inserisci l'elemento HTML che vuoi abbinare, come elenco separato da virgole. Il valore che inserisci 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 quando vuoi trovare corrispondenze sia per gli ancoraggi che per le immagini.

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

        Per impostazione predefinita, questo campo è impostato su href, che specifica l'URI per il 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 del selettore, il timeout per URI, i tentativi e i codici di stato previsti:

        1. Fai clic su Mostra altre opzioni.

        2. Per configurare il controllo dei link non funzionanti in modo che attenda la visualizzazione di un selettore specifico nell'URI prima di eseguire lo scraping dei link, inserisci i selettori CSS nel campo Attendi selettore elemento. Il valore che inserisci 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 i link vengono selezionati per il test.

        4. Configura i tentativi.

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

          Questo campo specifica il numero di volte in cui il controllo dei link non funzionanti può inviare una richiesta HTTP a un link prima di contrassegnarlo 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 e il timeout previsti per un URI specifico, fai clic su Aggiungi opzione per link e completa la finestra di dialogo.

    9. (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 quelli non superati. Cloud Monitoring utilizza la seguente convenzione per denominare il bucket Cloud Storage:

      gcm-PROJECT_ID-synthetics-LOCATION

      Nell'espressione precedente:

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

      Puoi utilizzare un bucket Cloud Storage esistente.

    10. Rivedi la configurazione e assicurati che sia corretta e completa, poi crea la funzione Cloud Run:

      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 modificare 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, svolgi le seguenti operazioni:

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

        • Esamina le impostazioni predefinite e aggiornale se necessario.

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

      4. Fai clic su Applica funzione.

    11. 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.

    12. Fai clic su Crea.

      La funzione Cloud Run che hai definito viene creata e di cui viene eseguito il deployment come 2ª generazione. e viene creato il monitor sintetico.

    Terraform

    Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per saperne di più, consulta la documentazione di riferimento del fornitore Terraform.

    La procedura di creazione di un controllo di verifica dei link non funzionanti utilizzando Terraform è identica a quella di creazione di qualsiasi altro monitor sintetico. Per informazioni sull'utilizzo di Terraform per creare un monitor sintetico, consulta Creare un monitor sintetico e seleziona la scheda Terraform.

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

    Quando viene definita la struttura options.screenshot_options, il controllo dei link non funzionanti 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 questo bucket. Monitoring utilizza la seguente convenzione per denominare il bucket Cloud Storage:

    gcm-PROJECT_ID-synthetics-LOCATION

    Nell'espressione precedente:

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

    REST

    La procedura di creazione di un controllo dei link non funzionanti utilizzando l'API Cloud Monitoring è identica a quella di creazione di qualsiasi altro monitor sintetico. Per informazioni sull'utilizzo dell'API Cloud Monitoring per creare un monitor sintetico, consulta Creare un monitor sintetico e seleziona la scheda Cloud Monitoring.

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

    Quando viene definita la struttura options.screenshot_options, il controllo dei link non funzionanti 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 questo bucket. Monitoring utilizza la seguente convenzione per denominare il bucket Cloud Storage:

    gcm-PROJECT_ID-synthetics-LOCATION

    Nell'espressione precedente:

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

    Esplora i risultati

    Per ogni esecuzione, il controllo dei link non funzionanti esegue le seguenti operazioni:

    • Genera una tabella in cui ogni riga fornisce informazioni sul test di un URI specifico. Le informazioni di riepilogo includono l'URI di destinazione, la latenza, lo stato e l'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 screenshot, se configurati.

    Per saperne di più su come esplorare i dati raccolti, vedi Esplorare i risultati del monitor sintetico.

    Risoluzione dei problemi

    Questa sezione fornisce informazioni che puoi utilizzare per risolvere i problemi dei tuoi strumenti di controllo dei link non funzionanti.

    Impossibile modificare la configurazione di un controllo dei link non funzionanti

    Hai creato un controllo dei link non funzionanti utilizzando la console Google Cloud e vuoi modificare gli elementi HTML testati oppure vuoi modificare il timeout URI, i tentativi, l'attesa del selettore e le opzioni per link. Tuttavia, quando modifichi il controllo dei link non funzionanti, la Google Cloud console non mostra i campi di configurazione.

    Per risolvere questo errore, procedi nel seguente modo:

    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. Nella barra degli strumenti della console Google Cloud , seleziona il tuo Google Cloud progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
    3. Individua il monitor sintetico da modificare, fai clic su Altre opzioni e poi seleziona Modifica.
    4. Fai clic su Modifica funzione.

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

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

    6. Fai clic su Salva.

    La consoleGoogle Cloud mostra che i salvataggi degli screenshot non vanno a buon fine

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

    • InvalidStorageLocation
    • StorageValidationError
    • BucketCreationError
    • ScreenshotFileUploadError

    Per risolvere questi errori, prova quanto segue:

    • Se visualizzi 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 funzione Cloud Run. Per ulteriori informazioni, vedi Trovare i log.

    • Verifica che il account di servizio utilizzato nella funzione Cloud Run corrispondente disponga di un ruolo Identity and Access Management che gli consenta di creare, accedere e scrivere nei bucket Cloud Storage.

    Passaggi successivi