Consultar um conjunto de dados vinculado do BigQuery

Este documento descreve como criar um conjunto de dados vinculado a um bucket de registro e como consultar e visualizar registros nesse conjunto de dados. Por exemplo, é possível criar um conjunto de dados vinculado para executar consultas na Análise de dados de registros usando seus slots reservados do BigQuery. Da mesma forma, talvez você queira um conjunto de dados vinculado para poder escrever consultas no BigQuery ou no Looker Studio que mesclem seus dados de registro com outros dados de negócios.

Não é possível criar um conjunto de dados vinculado do BigQuery para uma visualização de análise.

Se você não conhece a Análise de Registros, consulte a Visão geral da Análise de Registros.

Quando você precisa de um conjunto de dados vinculado

Não é necessário ter um conjunto de dados vinculado do BigQuery para emitir consultas em uma visualização de registro na página Análise de registros quando você usa o serviço padrão do Cloud Logging. Você pode salvar e compartilhar suas consultas e salvar os resultados em um painel personalizado.

Você precisa de um conjunto de dados do BigQuery vinculado quando quiser fazer o seguinte:

Um conjunto de dados vinculado do BigQuery para um bucket de registros permite que o BigQuery leia os dados no bucket.

Se você executar consultas em slots reservados do BigQuery, elas estarão sujeitas aos preços de computação de capacidade. Além disso, se você consultar seus dados usando um serviço diferente do Log Analytics, suas consultas poderão estar sujeitas a outras cobranças com base nesse serviço. Consulte a página de preços do serviço que você está usando.

Como os buckets de registro e as visualizações de registro são mapeadas para objetos do BigQuery

Quando você cria um conjunto de dados vinculado do BigQuery para um bucket de registros, um novo conjunto de dados fica disponível para o BigQuery. Você especifica o nome do conjunto de dados vinculado durante o processo de vinculação. Todas as visualizações de registro no bucket de registro são mapeadas automaticamente para visualizações virtuais no conjunto de dados. O nome de uma visualização virtual é o mesmo da visualização de registro correspondente.

Por exemplo, suponha que o projeto my_project tenha um bucket de registro chamado example e que esse bucket tenha uma visualização de registro chamada _AllLogs. Se você criar um conjunto de dados vinculado para esse bucket de registro com o nome my_dataset, a página Explorer do BigQuery vai mostrar uma entrada my_project. Uma criança da entrada my_project é um conjunto de dados com o nome my_dataset, e esse conjunto de dados lista uma visualização virtual chamada _AllLogs.

Implicações do controle de acesso ao usar conjuntos de dados vinculados

Quando um principal consulta uma visualização em um conjunto de dados vinculado do BigQuery, essa consulta é executada pela camada de permissões do BigQuery, não pela camada de permissões do Cloud Logging. Portanto, os papéis e as permissões do BigQuery concedidos ao principal no conjunto de dados vinculado determinam se ele pode consultar o conjunto de dados.

Não é possível restringir um principal a uma visualização virtual específica em um conjunto de dados vinculado. Quando um principal recebe acesso ao conjunto de dados vinculado, ele pode consultar todas as visualizações nesse conjunto.

Antes de começar

Esta seção descreve as etapas que você precisa concluir antes de usar a Análise de registros.

Configurar buckets de registros

Verifique se os buckets de registro foram atualizados para usar a Análise de registros:

  1. No console do Google Cloud, acesse a página Armazenamento de registros:

    Acessar o armazenamento de registros

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

  2. Para cada bucket de registro que tenha uma visualização de registro que você quer consultar, verifique se a coluna Log Analytics disponível mostra Aberto. Se a opção Upgrade for exibida, clique em Upgrade e conclua a caixa de diálogo.

Configurar papéis e permissões do IAM

Esta seção descreve os papéis ou as permissões do IAM necessários para usar o Log Analytics:

  • Para receber as permissões necessárias para usar a análise de registros e as visualizações de registro de consulta, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    É possível restringir um principal a uma visualização de registro específica adicionando uma condição do IAM à concessão de função de acessador de visualização de registros feita no nível do projeto ou adicionando uma vinculação do IAM ao arquivo de política da visualização de registro. Para mais informações, consulte Controlar o acesso a uma visualização de registro.

    Essas são as mesmas permissões necessárias para visualizar entradas de registro na página Análise de registros. Para informações sobre outros papéis necessários para consultar visualizações em buckets definidos pelo usuário ou para consultar a visualização _AllLogs do bucket de registros _Default, consulte Papéis do Cloud Logging.

  • Para receber as permissões necessárias para criar e consultar conjuntos de dados vinculados, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto que armazena o bucket de registros:

Verificar sua edição do BigQuery

Se você quiser consultar seus dados de registro na página Análise de registros usando slots reservados do BigQuery e se estiver usando projetos com controles de serviço de nuvem privada virtual (VPC), verifique se está usando a edição Enterprise do BigQuery. Para mais informações, consulte Noções básicas sobre as edições do BigQuery.

Quando você quiser usar os recursos do BigQuery para analisar seus dados de registro, faça upgrade de um bucket de registro para usar a Análise de dados de registros e crie um conjunto de dados vinculado. Com essa configuração, o Logging armazena seus dados de registro, mas o BigQuery pode ler esses dados.

Console do Google Cloud

Para criar um link para um conjunto de dados do BigQuery em um bucket de registros existente, faça o seguinte:

  1. No console do Google Cloud, acesse a página Armazenamento de registros:

    Acessar o armazenamento de registros

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

  2. Localize o bucket de registro e verifique se a coluna Log Analytics disponível mostra Aberto.

    Se essa coluna mostrar Upgrade, o bucket de registros não foi atualizado para usar a Análise de dados de registros. Configure a Análise de dados de registros:

    1. Clique em Fazer upgrade.
    2. Clique em Confirmar na caixa de diálogo.

    Depois que o upgrade for concluído, prossiga para a próxima etapa.

  3. No bucket de registro, clique em Mais e em Editar bucket.

    A caixa de diálogo Edit log bucket é aberta.

  4. Selecione Criar um novo conjunto de dados do BigQuery vinculado a este bucket e insira o nome do novo conjunto de dados.

    O nome do conjunto de dados precisa ser exclusivo para cada projeto do Google Cloud. Se você inserir o nome de um conjunto de dados existente, receberá o seguinte erro: Dataset name must be unique in the selected region.

  5. Clique em Concluído e em Atualizar bucket.

    Depois que o Logging mostra o nome do conjunto de dados vinculado na página Logs Storage, pode levar alguns minutos até que o BigQuery reconheça o conjunto de dados.

gcloud

Para criar um conjunto de dados vinculado a um bucket de registros atualizado para usar a Análise de dados de registros, execute o comando gcloud logging links create:

gcloud logging links create LINK_ID --bucket=BUCKET_ID --location=LOCATION

O LINK_ID fornecido é usado como o nome do conjunto de dados do BigQuery, e o valor desse campo precisa ser exclusivo para seu projeto do Google Cloud.

O comando links create é assíncrono. O retorno de um método assíncrono é um objeto Operation e contém informações sobre o progresso do método. Quando o método é concluído, o objeto Operation contém o status. Para mais informações, consulte Métodos de API assíncrona.

O comando links create leva alguns minutos para ser concluído.

Por exemplo, o comando a seguir cria um conjunto de dados vinculado chamado mylink para o bucket de registro my-bucket:

gcloud logging links create mylink --bucket=my-bucket --location=global

O nome do conjunto de dados precisa ser exclusivo para cada projeto do Google Cloud. Se você tentar criar um conjunto de dados com o mesmo nome de um conjunto de dados existente, o seguinte erro será exibido:

BigQuery dataset with name "LINK_ID" already exists.

Se você tentar criar um conjunto de dados vinculado para um bucket de registros que não foi atualizado para usar a Análise de dados de registros, o seguinte erro será informado:

A link can only be created for an analytics-enabled bucket.

REST

Para criar um conjunto de dados do BigQuery vinculado a um bucket de registros atualizado, use a Análise de dados de registros. Chame o método assíncrono projects.locations.buckets.links.create da API Cloud Logging.

Prepare os argumentos do método da seguinte maneira:

  1. Crie o corpo da solicitação para o comando create. O corpo da solicitação é formatado como um objeto Link.
  2. Para o parâmetro de consulta do comando, use linkId=LINK_ID. O LINK_ID fornecido é usado como o nome do conjunto de dados do BigQuery, e o valor desse campo precisa ser exclusivo para seu projeto do Google Cloud.

A resposta aos métodos assíncronos é um objeto Operation. Esse objeto contém informações sobre o progresso do método. Quando o método é concluído, o objeto Operation contém o status. Para mais informações, consulte Métodos de API assíncrona.

O método links.create leva alguns minutos para ser concluído.

O nome do conjunto de dados precisa ser exclusivo para cada projeto do Google Cloud. Se você tentar criar um conjunto de dados com o mesmo nome de um conjunto de dados existente, o seguinte erro será exibido:

BigQuery dataset with name "LINK_ID" already exists.

Se você tentar criar um conjunto de dados vinculado para um bucket de registros que não foi atualizado para usar a Análise de dados de registros, o seguinte erro será informado:

A link can only be created for an analytics-enabled bucket.

Executar consultas do BigQuery

Quando você tem um bucket de registro que usa a Análise de dados de registros e conjuntos de dados vinculados, é possível acessar e consultar esses conjuntos na página BigQuery Studio. Com essa configuração, é possível analisar seus conjuntos de dados usando comandos, fluxos de trabalho e conjuntos de dados disponíveis apenas no BigQuery Studio.

Para abrir o BigQuery na Análise de dados de registros e consultar o conjunto de dados vinculado, faça o seguinte:

  1. Verifique se há um conjunto de dados vinculado para o bucket de registro que hospeda a visualização de registro que você quer consultar:

    1. No console do Google Cloud, acesse a página Armazenamento de registros:

      Acessar o armazenamento de registros

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

    2. Localize o bucket de registros e verifique se a coluna Conjunto de dados vinculado do BigQuery mostra um URL. Se a entrada estiver vazia, crie um conjunto de dados vinculado. Para mais informações sobre essas etapas, consulte Criar um conjunto de dados vinculado do BigQuery.

  2. No console do Google Cloud, acesse a página Análise de dados de registros:

    Acesse Análise de registros

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

  3. Na lista Visualizações de registro, encontre a visualização de registro e selecione Consulta. O painel Consulta é preenchido com uma consulta padrão. Você também pode inserir uma consulta no painel Consulta ou editar uma consulta exibida.

  4. Na barra de ferramentas, expanda o botão Run query ou Run on BigQuery e selecione Open in BigQuery.

    A página do BigQuery Studio é aberta. A instrução FROM da consulta é modificada para especificar o caminho para a visualização de registro no conjunto de dados vinculado usando a sintaxe de caminho de tabela do BigQuery.

    Também é possível editar a consulta exibida.

  5. Na página do BigQuery Studio, clique em Executar consulta.

Executar consultas da Análise de Registros nos seus slots reservados do BigQuery

Quando você quiser minimizar o tempo de execução das consultas da Análise de registros, execute-as nos slots reservados do BigQuery. A página Análise de dados de registros é pré-configurada para usar o serviço padrão da Análise de dados de registros, o que significa que suas consultas precisam competir pelo espaço limitado do slot com outras consultas. Quando não há slots disponíveis, a execução da consulta é adiada. É possível eliminar esses atrasos executando suas consultas em slots reservados do BigQuery.

Para emitir uma consulta SQL para uma visualização de registro, faça o seguinte:

  1. Verifique se há um conjunto de dados vinculado para o bucket de registro que hospeda a visualização de registro que você quer consultar:

    1. No console do Google Cloud, acesse a página Armazenamento de registros:

      Acessar o armazenamento de registros

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

    2. Localize o bucket de registros e verifique se a coluna Conjunto de dados vinculado do BigQuery mostra um URL. Se a entrada estiver vazia, crie um conjunto de dados vinculado. Para mais informações sobre essas etapas, consulte Criar um conjunto de dados vinculado do BigQuery.

  2. Verifique se você configurou os slots reservados do BigQuery:

    1. Criar uma reserva com slots dedicados
    2. Criar atribuições de reserva

  3. Configure a Análise de registros para executar consultas nos seus slots reservados do BigQuery:

    1. No console do Google Cloud, acesse a página Análise de dados de registros:

      Acesse Análise de registros

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

    2. Na lista Visualizações de registro, encontre a visualização e selecione Consulta ou insira uma consulta.

      Se o painel de consulta mostrar uma mensagem de erro que faz referência à instrução FROM, a tabela não poderá ser resolvida para uma visualização de registro específica. Para informações sobre como resolver essa falha, consulte Erro FROM clause must contain exactly one log view.

    3. Acesse a barra de ferramentas e verifique se o botão Run on BigQuery está sendo exibido.

      Se a barra de ferramentas mostrar Executar consulta, clique em Configurações e selecione BigQuery.

      Se o botão Run on BigQuery estiver desativado, você precisa criar um conjunto de dados vinculado.

    4. Execute a consulta.

      Você pode usar as opções da barra de ferramentas para formatar, limpar a consulta e abrir a documentação de referência do SQL do BigQuery.

A seguir