Criar um verificador de links corrompidos

Este documento descreve como configurar um teste periódico dos links contidos em um URI criando um monitor sintético. Você especifica as opções para o teste, como o URI de origem, o número de links testados e o número de novas tentativas, e implanta uma função pré-configurada do Cloud Run. Para ajudar nos seus esforços de depuração e solução de problemas, os monitores sintéticos salvam informações detalhadas sobre cada teste, incluindo capturas de tela. Com as capturas de tela, é possível ver a resposta exata que os clientes do seu aplicativo recebem.

Para saber mais sobre monitores sintéticos, consulte Sobre monitores sintéticos.

Esse recurso só é compatível com projetos Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

Sobre verificadores de links corrompidos

Cada verificador de links quebrados testa os links em série, e há um tempo limite sintético geral, que é configurável.

Por padrão, um verificador de links corrompidos faz o seguinte:

  • Pesquisa no URI de origem elementos de âncora HTML com atributos href.
  • Testa os 10 primeiros links encontrados no URI de origem.
  • Para cada link, o verificador emite uma solicitação e aguarda no máximo 30 segundos por uma resposta. Quando uma resposta é recebida, o verificador verifica se o status da resposta HTTP é 200, o que indica uma resposta bem-sucedida. O verificador não faz novas tentativas.

Você especifica o URI de origem. É possível configurar quais elementos HTML o verificador de links quebrados pesquisa, o número máximo de elementos testados, o tempo limite por teste e se as novas tentativas são realizadas. Também é possível configurar verificadores de links quebrados para aguardar o aparecimento de um seletor.

Os verificadores de links quebrados usam o modelo broken-links-ok. A configuração de um verificador de links quebrados é especificada pelo objeto options do arquivo index.js. Se você criar o verificador usando o Google Cloud console, vai receber uma solicitação para cada opção de configuração e a função do Cloud Run será atualizada para você. No entanto, se você usar a API Cloud Monitoring ou o Terraform, será necessário preencher esse objeto.

Depois de criar um verificador de links quebrados, para modificar a configuração, atualize o objeto options e reimplemente a função do Cloud Run.

Antes de começar

Conclua as etapas a seguir no projeto Google Cloud que vai armazenar o verificador de links:

  1. Para ter as permissões necessárias para visualizar e modificar monitores sintéticos usando o console Google Cloud , peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

  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. Verifique se o projeto Google Cloud contém a conta de serviço padrão do Compute Engine. Essa conta de serviço é criada quando você ativa a API Compute Engine e tem um nome semelhante a [email protected].

    No console Google Cloud , acesse a página Contas de serviço:

    Acesse Contas de serviço

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo IAM e administrador.

    Se a conta de serviço padrão do Compute Engine não existir, clique em Criar conta de serviço e preencha a caixa de diálogo.

  4. Verifique se a conta de serviço padrão do Compute Engine ou a conta de serviço criada recebeu o papel de Editor (roles/editor).

    Para conferir os papéis concedidos à sua conta de serviço, faça o seguinte:

    1. No console Google Cloud , acesse a página IAM:

      Acesse o IAM

      Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo IAM e administrador.

    2. Selecione Incluir concessões de papel fornecidas pelo Google.
    3. Se a conta de serviço usada pelo monitor sintético não estiver listada ou se ela não tiver recebido um papel que inclua as permissões do papel de agente do Cloud Trace (roles/cloudtrace.agent), conceda esse papel à conta de serviço.
  5. Configure os canais de notificação que você quer usar para receber notificações. Recomendamos que você crie vários tipos de canais de notificação. Para mais informações, consulte Criar e gerenciar canais de notificação e Criar e gerenciar canais de notificação por 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

    Para usar os exemplos do Terraform nesta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

      Instale a CLI do Google Cloud.

      Se você estiver usando um provedor de identidade externo (IdP), primeiro faça login na CLI gcloud com sua identidade federada.

      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.

    Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

    REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

      Instale a CLI do Google Cloud.

      Se você estiver usando um provedor de identidade externo (IdP), primeiro faça login na CLI gcloud com sua identidade federada.

    Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud .

    Criar um verificador de links corrompidos

    Console

    Ao criar um monitor sintético usando o console Google Cloud , uma nova função do Cloud Run (2ª geração) é implantada e o monitor dessa função é criado. Não é possível criar um monitor sintético que monitore uma função do Cloud Run.

    1. Verifique se você ativou as APIs necessárias, se o projeto tem uma conta de serviço padrão do Compute Engine e se essa conta recebeu o papel de Editor (roles/editor). Para mais informações, consulte Antes de começar.

    2. No console Google Cloud , acesse a página  Monitoramento sintético:

      Acessar Monitoramento sintético

      Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

    3. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
    4. Selecione Criar monitor sintético.
    5. Para o modelo, selecione Verificador de links quebrados.
    6. Insira um nome para o monitor sintético.

    7. Opcional: atualize o Tempo limite de resposta, a Frequência de verificação e adicione rótulos definidos pelo usuário.

    8. Configure o URI e os elementos a serem testados:

      1. Clique em URI de origem e insira um URI que você quer testar. O valor inserido precisa ser um endpoint HTTP ou HTTPS. Por exemplo, você pode digitar https://mywebsite.example.com.

      2. Opcional: em Número de links a seguir, atualize o número máximo de links testados. O valor padrão desse campo é 10.

      3. Opcional: no campo Seletor de elementos HTML, insira o elemento HTML que você quer corresponder como uma lista separada por vírgulas. O valor inserido é convertido em uma string e transmitido ao método Document: querySelectorAll().

        Por padrão, esse campo é definido como a, que corresponde a âncoras. É possível inserir valores como a, img quando quiser corresponder âncoras e imagens.

      4. Opcional: no campo Atributos HTML a serem seguidos, insira os atributos HTML que você quer corresponder. Os valores separados por vírgula inseridos são transmitidos individualmente ao método getAttribute().

        Por padrão, esse campo é definido como href, que especifica o URI do link. É possível inserir vários atributos, por exemplo, href, src. Neste exemplo, o código procura o atributo href e depois o atributo src.

      5. Opcional: configure a espera pelo seletor, o tempo limite por URI, as novas tentativas e os códigos de status esperados:

        1. Clique em Mostrar mais opções.

        2. Para configurar o verificador de links quebrados para aguardar um seletor específico aparecer no URI antes de qualquer link ser extraído, insira os seletores de CSS no campo Aguardar seletor de elementos. O valor inserido é convertido em uma string e transmitido ao método page.waitForSelector().

          Se o seletor não aparecer antes do tempo limite expirar, a falha será registrada nos registros.

        3. Atualize a ordem em que os links são selecionados para teste.

        4. Configure novas tentativas.

          Por padrão, uma solicitação é enviada para cada link. Se a solicitação inicial falhar por qualquer motivo, por exemplo, se o comando atingir o tempo limite ou se o código de status HTTP não for 200, o link será marcado como falho.

          Esse campo especifica o número de vezes que o verificador de links quebrados pode emitir uma solicitação HTTP para um link antes de marcá-lo como falho.

        5. Configure um tempo limite que se aplique a cada URI. Por padrão, esse valor é definido como 30 segundos.

        6. Para especificar o código de status e o tempo limite esperados para um URI específico, clique em Adicionar opção por link e preencha a caixa de diálogo.

    9. Opcional: configure se as capturas de tela das respostas serão coletadas e salvas. Se você usar as configurações padrão, as capturas de tela não serão salvas. Se você ativar a coleta de capturas de tela, poderá coletar capturas de tela para todos os testes ou apenas para os que falharam. O Cloud Monitoring usa a seguinte convenção para nomear o bucket do Cloud Storage:

      gcm-PROJECT_ID-synthetics-LOCATION

      Na expressão anterior:

      • PROJECT_ID: o ID do seu projeto do Google Cloud .
      • LOCATION: o local do bucket do Cloud Storage.

      Você pode usar um bucket do Cloud Storage.

    10. Revise a configuração e verifique se ela está correta e completa. Em seguida, crie a função do Cloud Run:

      1. Clique em Criar função.

        Os valores nos campos Configuração de URI são copiados para o objeto Options no arquivo index.js quando você clica em Criar função. Depois de clicar em Criar função, edite o objeto Options para mudar a configuração.

      2. Insira um nome de exibição e selecione uma região. Os nomes precisam ser exclusivos em uma região.

      3. Na seção Configurações de ambiente de execução, build, conexões e segurança, faça o seguinte:

        • Na guia Conexões, verifique se a opção Permitir todo o tráfego está selecionada.

        • Revise as configurações padrão e atualize-as quando necessário.

        • No campo Conta de serviço de tempo de execução, selecione uma conta de serviço.

      4. Clique em Aplicar função.

    11. Configure a política de alertas:

      1. Opcional: atualize o nome da política de alertas e a duração da falha antes do envio das notificações.

      2. Adicione os canais de notificação.

    12. Clique em Criar.

      A função do Cloud Run definida é criada e implantada como 2ª geração, e o monitor sintético é criado.

    Terraform

    Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

    O processo de criação de um verificador de links corrompidos usando o Terraform é idêntico ao processo de criação de qualquer outro monitor sintético. Para informações sobre como usar o Terraform para criar um monitor sintético, consulte Criar um monitor sintético e selecione a guia "Terraform".

    Os verificadores de links quebrados usam o modelo broken-links-ok. A configuração de um verificador de links quebrados é especificada pelo objeto options do arquivo index.js.

    Quando a estrutura options.screenshot_options é definida, o verificador de links corrompidos coleta capturas de tela e as salva em um bucket do Cloud Storage. Se o campo screenshot_options.storage_location não estiver definido ou se o valor for uma string vazia, o Monitoring vai criar um bucket do Cloud Storage e salvar as capturas de tela nele. O Monitoring usa a seguinte convenção para nomear o bucket do Cloud Storage:

    gcm-PROJECT_ID-synthetics-LOCATION

    Na expressão anterior:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • LOCATION: o local do bucket do Cloud Storage.

    REST

    O processo de criação de um verificador de links corrompidos usando a API Cloud Monitoring é idêntico ao processo de criação de qualquer outro monitor sintético. Para informações sobre como usar a API Cloud Monitoring para criar um monitor sintético, consulte Criar um monitor sintético e selecione a guia "Cloud Monitoring".

    Os verificadores de links quebrados usam o modelo broken-links-ok. A configuração de um verificador de links quebrados é especificada pelo objeto options do arquivo index.js.

    Quando a estrutura options.screenshot_options é definida, o verificador de links corrompidos coleta capturas de tela e as salva em um bucket do Cloud Storage. Se o campo screenshot_options.storage_location não estiver definido ou se o valor for uma string vazia, o Monitoring vai criar um bucket do Cloud Storage e salvar as capturas de tela nele. O Monitoring usa a seguinte convenção para nomear o bucket do Cloud Storage:

    gcm-PROJECT_ID-synthetics-LOCATION

    Na expressão anterior:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • LOCATION: o local do bucket do Cloud Storage.

    Analisar os resultados

    Para cada execução, um verificador de links quebrados faz o seguinte:

    • Gera uma tabela em que cada linha fornece informações sobre o teste de um URI específico. As informações do resumo incluem o URI de destino, a latência, o status e o identificador do elemento HTML. Por exemplo, essa coluna lista a quando um elemento de âncora HTML é testado. Quando a linha corresponde ao URI de origem, o valor do identificador do elemento HTML é -.

    • Coleta métricas, dados de rastreamento e dados de registro.

    • Coleta capturas de tela, quando configurado.

    Para mais informações sobre como analisar os dados coletados, consulte Analisar os resultados de monitores sintéticos.

    Resolver problemas

    Nesta seção, você encontra informações para ajudar a resolver problemas com seus verificadores de links quebrados.

    Não é possível editar a configuração de um verificador de links quebrados

    Você criou um verificador de links quebrados usando o console Google Cloud e quer mudar os elementos HTML testados ou modificar o tempo limite de URI, as novas tentativas, a espera pelo seletor e as opções por link. No entanto, ao editar o verificador de links quebrados, o console Google Cloud não mostra os campos de configuração.

    Para resolver essa falha, faça o seguinte:

    1. No console Google Cloud , acesse a página  Monitoramento sintético:

      Acessar Monitoramento sintético

      Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

    2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
    3. Localize o monitor sintético que você quer editar, clique em Mais opções e selecione Editar.
    4. Clique em Editar função.

    5. Edite o objeto options no arquivo index.js e clique em Aplicar função.

      Para informações sobre os campos e a sintaxe desse objeto, consulte broken-links-ok/index.js.

    6. Clique em Salvar.

    Google Cloud o console mostra que as capturas de tela não foram salvas

    Você criou um verificador de links corrompidos e o configurou para salvar capturas de tela. No entanto, o console Google Cloud está mostrando uma das seguintes mensagens de aviso com informações mais detalhadas:

    • InvalidStorageLocation
    • StorageValidationError
    • BucketCreationError
    • ScreenshotFileUploadError

    Para resolver essas falhas, tente o seguinte:

    • Se você encontrar a mensagem InvalidStorageLocation, verifique a existência do bucket do Cloud Storage especificado no campo options.screenshot_options.storage_location.

    • Confira os registros relacionados à sua função do Cloud Run. Para mais informações, consulte Como encontrar registros.

    • Verifique se a conta de serviço usada na função correspondente do Cloud Run tem um papel do Identity and Access Management que permite criar, acessar e gravar em buckets do Cloud Storage.

    A seguir