BigQuery

Use o conetor do BigQuery para realizar operações de inserção, eliminação, atualização e leitura em dados do Google BigQuery. Também pode executar consultas SQL personalizadas em dados do BigQuery. Pode usar o conetor do BigQuery para integrar dados de vários serviços do Google Cloud ou outros serviços de terceiros, como o Cloud Storage ou o Amazon S3.

Antes de começar

No seu projeto do Google Cloud, faça as seguintes tarefas:

• Certifique-se de que a conetividade de rede está configurada. Para obter informações sobre padrões de rede, consulte o artigo Conetividade de rede.
• Conceda a função IAM roles/connectors.admin ao utilizador que está a configurar o conetor.
• Conceda a função de IAM roles/bigquery.dataEditor à conta de serviço que quer usar para o conector. Se não tiver uma conta de serviço, tem de criar uma. O conector e a conta de serviço têm de pertencer ao mesmo projeto.
• Ative os seguintes serviços:
  • secretmanager.googleapis.com (Secret Manager API)
  • connectors.googleapis.com (API Connectors)

  Para saber como ativar serviços, consulte o artigo Ativar serviços. Se estes serviços ou autorizações não tiverem sido ativados anteriormente para o seu projeto, é-lhe pedido que os ative quando configurar o conector.

Crie uma associação do BigQuery

Uma associação é específica de uma origem de dados. Isto significa que, se tiver muitas origens de dados, tem de criar uma associação separada para cada origem de dados. Para criar uma associação, faça o seguinte:

1. Na Cloud Console, aceda à página Integration Connectors > Ligações e, de seguida, selecione ou crie um projeto do Google Cloud.

   Aceda à página Ligações

2. Clique em + CRIAR NOVO para abrir a página Criar associação.
3. Na secção Localização, selecione uma localização na lista Região e, de seguida, clique em SEGUINTE.

   Para ver a lista de todas as regiões suportadas, consulte o artigo Localizações.

4. Na secção Detalhes da associação, faça o seguinte:
   1. Selecione BigQuery na lista Conetor.
   2. Selecione uma versão do conetor na lista Versão do conetor.
   3. No campo Nome da associação, introduza um nome para a instância da associação. O nome da associação pode conter letras minúsculas, números ou hífenes. O nome tem de começar com uma letra e terminar com uma letra ou um número, e não pode exceder os 49 carateres.
   4. Opcionalmente, ative o Registo na nuvem e, em seguida, selecione um nível de registo. Por predefinição, o nível do registo está definido como Error.
   5. Conta de serviço: selecione uma conta de serviço que tenha as funções necessárias.
   6. (Opcional) Configure as definições do nó de associação.
   • Número mínimo de nós: introduza o número mínimo de nós de ligação.
   • Número máximo de nós: introduza o número máximo de nós de ligação.

   Um nó é uma unidade (ou uma réplica) de uma ligação que processa transações. São necessários mais nós para processar mais transações para uma ligação e, inversamente, são necessários menos nós para processar menos transações. Para compreender como os nós afetam os preços dos conectores, consulte o artigo Preços dos nós de ligação. Se não introduzir valores, por predefinição, os nós mínimos são definidos como 2 (para uma melhor disponibilidade) e os nós máximos são definidos como 50.

   Nota: só pode personalizar os valores do nó de associação se for cliente de pagamento por utilização.
   7. ID do projeto: o ID do projeto do Google Cloud onde os dados residem.
   8. ID do conjunto de dados: o ID do conjunto de dados do BigQuery.
   9. Para suportar o tipo de dados de matriz do BigQuery, selecione Suportar tipos de dados nativos. Os seguintes tipos de matriz são suportados: Varchar, Int64, Float64, Long, Double, Bool e Timestamp. As matrizes aninhadas não são suportadas.
   10. (Opcional) Para configurar um servidor proxy para a ligação, selecione Usar proxy e introduza os detalhes do proxy.
   • Esquema de autenticação de proxy: selecione o tipo de autenticação para autenticar com o servidor proxy. Os seguintes tipos de autenticação são suportados:
     • Básica: autenticação HTTP básica.
     • Resumo: autenticação HTTP de resumo.
   • Utilizador do proxy: um nome de utilizador a ser usado para autenticação com o servidor proxy.
   • Palavra-passe do proxy: o segredo do Secret Manager da palavra-passe do utilizador.
   • Tipo de SSL do proxy: o tipo de SSL a usar quando se liga ao servidor proxy. Os seguintes tipos de autenticação são suportados:
     • Automático: predefinição. Se o URL for um URL HTTPS, é usada a opção Túnel. Se o URL for um URL HTTP, é usada a opção NUNCA.
     • Sempre: a ligação está sempre ativada com SSL.
     • Nunca: a ligação não tem o SSL ativado.
     • Túnel: a ligação é feita através de um proxy de túnel. O servidor proxy abre uma ligação ao anfitrião remoto e o tráfego flui em ambas as direções através do proxy.
   • Na secção Servidor proxy, introduza os detalhes do servidor proxy.
     1. Clique em + Adicionar destino.
     2. Selecione um Tipo de destino.
        • Endereço do anfitrião: especifique o nome do anfitrião ou o endereço IP do destino.

          Se quiser estabelecer uma ligação privada ao seu sistema de back-end, faça o seguinte:

          • Crie uma associação de serviço do PSC.
          • Crie uma associação de ponto final e, em seguida, introduza os detalhes da associação de ponto final no campo Endereço do anfitrião.
   11. Clique em SEGUINTE.
5. Na secção Autenticação, introduza os detalhes de autenticação.
   1. Selecione se quer autenticar com o código de autorização do OAuth 2.0 ou continuar sem autenticação.

      Para saber como configurar a autenticação, consulte o artigo Configure a autenticação.

   2. Clique em SEGUINTE.
6. Reveja os detalhes da ligação e da autenticação e, de seguida, clique em Criar.

Configure a autenticação

Introduza os detalhes com base na autenticação que quer usar.

• Sem autenticação: selecione esta opção se não precisar de autenticação.
• OAuth 2.0 – Código de autorização: selecione esta opção para autenticar através de um fluxo de início de sessão do utilizador baseado na Web. Especifique os seguintes detalhes:
• ID do cliente: o ID do cliente necessário para estabelecer ligação ao seu serviço Google de back-end.
• Âmbitos: uma lista separada por vírgulas dos âmbitos pretendidos. Para ver todos os âmbitos do OAuth 2.0 suportados para o serviço Google necessário, consulte a secção relevante na página Âmbitos do OAuth 2.0 para APIs Google.
• Segredo do cliente: selecione o segredo do Secret Manager. Tem de ter criado o Secret do Secret Manager antes de configurar esta autorização.
• Versão do Secret: versão do Secret do Secret Manager para o segredo do cliente.

Para o tipo de autenticação Authorization code, depois de criar a associação, tem de autorizar a associação.

Autorize a associação

Se usar o código de autorização do OAuth 2.0 para autenticar a associação, conclua as seguintes tarefas depois de criar a associação.

1. Na página Ligações, encontre a ligação criada recentemente.

   Tenha em atenção que o Estado do novo conetor é Autorização necessária.

2. Clique em Autorização obrigatória.

   É apresentado o painel Editar autorização.

3. Copie o valor do URI de redirecionamento para a sua aplicação externa.
4. Valide os detalhes da autorização.
5. Clique em Autorizar.

   Se a autorização for bem-sucedida, o estado da ligação é definido como Ativo na página Ligações.

Nova autorização para o código de autorização

Se estiver a usar o tipo de autenticação Authorization code e tiver feito alterações de configuração no BigQuery, tem de voltar a autorizar a ligação ao BigQuery. Para autorizar novamente uma associação, siga estes passos:

1. Clique na associação necessária na página Associações.

   É apresentada a página de detalhes da associação.

2. Clique em Editar para editar os detalhes da associação.
3. Valide os detalhes de OAuth 2.0 – Código de autorização na secção Autenticação.

   Se necessário, faça as alterações necessárias.

4. Clique em Guardar. Esta ação direciona para a página de detalhes da associação.
5. Clique em Editar autorização na secção Autenticação. É apresentado o painel Autorizar.
6. Clique em Autorizar.

   Se a autorização for bem-sucedida, o estado da ligação é definido como Ativo na página Ligações.

Use a ligação do BigQuery numa integração

Depois de criar a ligação, esta fica disponível no Apigee Integration e no Application Integration. Pode usar a ligação numa integração através da tarefa Conectores.

• Para compreender como criar e usar a tarefa Connectors no Apigee Integration, consulte o artigo Tarefa Connectors.
• Para compreender como criar e usar a tarefa Connectors na integração de aplicações, consulte o artigo Tarefa Connectors.

Ações

Esta secção descreve as ações disponíveis no conetor do BigQuery.

Os resultados de todas as operações de entidades e ações vão estar disponíveis como uma resposta JSON no parâmetro de resposta connectorOutputPayload da tarefa Connectors depois de executar a integração.

Nota: todas as entidades e ações têm um esquema associado. Por exemplo, um esquema de ação tem os detalhes dos parâmetros, como os nomes dos parâmetros e o respetivo tipo de dados. O esquema (metadados) para entidades e ações é obtido pela ligação em tempo de execução a partir do seu back-end. Se existirem atualizações ao esquema, estas não são automaticamente refletidas nas suas associações existentes. Tem de atualizar manualmente o esquema. Para atualizar o esquema de uma associação, abra a página Detalhes da associação da associação e, de seguida, clique em Atualizar esquema da associação.

Ação CancelJob

Esta ação permite-lhe cancelar uma tarefa do BigQuery em execução.

A tabela seguinte descreve os parâmetros de entrada da ação CancelJob.

Nome do parâmetro	Tipo de dados	Descrição
JobId	String	O ID da tarefa que quer cancelar. Este é um campo obrigatório.
Região	String	A região onde a tarefa está a ser executada atualmente. Isto não é necessário se o emprego for na região dos EUA ou da UE.

Ação GetJob

Esta ação permite-lhe obter as informações de configuração e o estado de execução de uma tarefa existente.

A tabela seguinte descreve os parâmetros de entrada da ação GetJob.

Nome do parâmetro	Tipo de dados	Descrição
JobId	String	O ID da tarefa para a qual quer obter a configuração. Este é um campo obrigatório.
Região	String	A região onde a tarefa está a ser executada atualmente. Isto não é necessário se o emprego for na região dos EUA ou da UE.

Ação InsertJob

Esta ação permite-lhe inserir uma tarefa do BigQuery, que pode ser selecionada posteriormente para obter os resultados da consulta.

A tabela seguinte descreve os parâmetros de entrada da ação InsertJob.

Nome do parâmetro	Tipo de dados	Descrição
Consulta	String	A consulta a enviar para o BigQuery. Este é um campo obrigatório.
IsDML	String	Deve ser definido como true se a consulta for uma declaração DML ou false caso contrário. O valor predefinido é false.
DestinationTable	String	A tabela de destino da consulta, no formato DestProjectId:DestDatasetId.DestTable.
WriteDisposition	String	Especifica como escrever dados na tabela de destino, como truncar resultados existentes, anexar resultados existentes ou escrever apenas quando a tabela está vazia. Seguem-se os valores suportados: WRITE_TRUNCATE WRITE_APPEND WRITE_EMPTY O valor predefinido é WRITE_TRUNCATE.
DryRun	String	Especifica se a execução da tarefa é um teste.
MaximumBytesBilled	String	Especifica o número máximo de bytes que podem ser processados pela tarefa. O BigQuery cancela a tarefa se esta tentar processar mais bytes do que o valor especificado.
Região	String	Especifica a região onde o trabalho deve ser executado.

Ação InsertLoadJob

Esta ação permite-lhe inserir uma tarefa de carregamento do BigQuery, que adiciona dados do Google Cloud Storage a uma tabela existente.

A tabela seguinte descreve os parâmetros de entrada da ação InsertLoadJob.

Nome do parâmetro	Tipo de dados	Descrição
SourceURIs	String	Uma lista de URIs do Google Cloud Storage separados por espaços.
SourceFormat	String	O formato de origem dos ficheiros. Seguem-se os valores suportados: AVRO NEWLINE_DELIMITED_JSON DATASTORE_BACKUP PARQUET ORC CSV
DestinationTable	String	A tabela de destino da consulta, no formato DestProjectId.DestDatasetId.DestTable.
DestinationTableProperties	String	Um objeto JSON que especifica o nome amigável, a descrição e a lista de etiquetas da tabela.
DestinationTableSchema	String	Uma lista JSON que especifica os campos usados para criar a tabela.
DestinationEncryptionConfiguration	String	Um objeto JSON que especifica as definições de encriptação do KMS para a tabela.
SchemaUpdateOptions	String	Uma lista JSON que especifica as opções a aplicar quando atualiza o esquema da tabela de destino.
TimePartitioning	String	Um objeto JSON que especifica o tipo e o campo de partição de tempo.
RangePartitioning	String	Um objeto JSON que especifica o campo de partição de intervalo e os contentores.
Clustering	String	Um objeto JSON que especifica os campos a usar para o clustering.
Deteção automática	String	Especifica se as opções e o esquema devem ser determinados automaticamente para ficheiros JSON e CSV.
CreateDisposition	String	Especifica se a tabela de destino tem de ser criada se ainda não existir. Seguem-se os valores suportados: CREATE_IF_NEEDED CREATE_NEVER O valor predefinido é CREATE_IF_NEEDED.
WriteDisposition	String	Especifica como escrever dados na tabela de destino, como truncar resultados existentes, anexar resultados existentes ou escrever apenas quando a tabela está vazia. Seguem-se os valores suportados: WRITE_TRUNCATE WRITE_APPEND WRITE_EMPTY O valor predefinido é WRITE_APPEND.
Região	String	Especifica a região onde o trabalho deve ser executado. Os recursos do Google Cloud Storage e o conjunto de dados do BigQuery têm de estar na mesma região.
DryRun	String	Especifica se a execução da tarefa é um teste. O valor predefinido é false.
MaximumBadRecords	String	Especifica o número de registos que podem ser inválidos antes de toda a tarefa ser cancelada. Por predefinição, todos os registos têm de ser válidos. O valor predefinido é 0.
IgnoreUnknownValues	String	Especifica se os campos desconhecidos têm de ser ignorados no ficheiro de entrada ou tratados como erros. Por predefinição, são tratados como erros. O valor predefinido é false.
AvroUseLogicalTypes	String	Especifica se os tipos lógicos AVRO têm de ser usados para converter dados AVRO em tipos do BigQuery. O valor predefinido é true.
CSVSkipLeadingRows	String	Especifica o número de linhas a ignorar no início dos ficheiros CSV. Normalmente, esta opção é usada para ignorar linhas de cabeçalho.
CSVEncoding	String	Tipo de codificação dos ficheiros CSV. Seguem-se os valores suportados: ISO-8859-1 UTF-8 O valor predefinido é UTF-8.
CSVNullMarker	String	Se for fornecida, esta string é usada para valores NULL em ficheiros CSV. Por predefinição, os ficheiros CSV não podem usar NULL.
CSVFieldDelimiter	String	O caráter usado para separar colunas em ficheiros CSV. O valor predefinido é uma vírgula (,).
CSVQuote	String	O caráter usado para campos entre aspas em ficheiros CSV. Pode ser definido como vazio para desativar a indicação de aspas. O valor predefinido são as aspas duplas (").
CSVAllowQuotedNewlines	String	Especifica se os ficheiros CSV podem conter novas linhas em campos entre aspas. O valor predefinido é false.
CSVAllowJaggedRows	String	Especifica se os ficheiros CSV podem conter campos em falta. O valor predefinido é false.
DSBackupProjectionFields	String	Uma lista JSON de campos a carregar a partir de uma cópia de segurança do Cloud Datastore.
ParquetOptions	String	Um objeto JSON que especifica as opções de importação específicas do Parquet.
DecimalTargetTypes	String	Uma lista JSON que indica a ordem de preferência aplicada aos tipos numéricos.
HivePartitioningOptions	String	Um objeto JSON que especifica as opções de partição do lado da origem.

Executar consulta SQL personalizada

Para criar uma consulta personalizada, siga estes passos:

1. Siga as instruções detalhadas para adicionar uma tarefa de conetores.
2. Quando configurar a tarefa do conetor, no tipo de ação que quer realizar, selecione Ações.
3. Na lista Ação, selecione Executar consulta personalizada e, de seguida, clique em Concluído.

   

4. Expanda a secção Entrada de tarefas e, de seguida, faça o seguinte:
   1. No campo Tempo limite após, introduza o número de segundos a aguardar até que a consulta seja executada.

      Valor predefinido: 180 segundos.

   2. No campo Número máximo de linhas, introduza o número máximo de linhas a devolver da base de dados.

      Valor predefinido: 25.

   3. Para atualizar a consulta personalizada, clique em Editar script personalizado. É apresentada a caixa de diálogo Editor de scripts.

      

   4. Na caixa de diálogo Editor de scripts, introduza a consulta SQL e clique em Guardar.

      Pode usar um ponto de interrogação (?) numa declaração SQL para representar um único parâmetro que tem de ser especificado na lista de parâmetros de consulta. Por exemplo, a seguinte consulta SQL seleciona todas as linhas da tabela Employees que correspondem aos valores especificados para a coluna LastName:

      SELECT * FROM Employees where LastName=?

      Nota: as declarações de linguagem de manipulação de dados (DML) e linguagem de definição de dados (DDL) são suportadas.
   5. Se usou pontos de interrogação na sua consulta SQL, tem de adicionar o parâmetro clicando em + Adicionar nome do parâmetro para cada ponto de interrogação. Durante a execução da integração, estes parâmetros substituem os pontos de interrogação (?) na consulta SQL sequencialmente. Por exemplo, se adicionou três pontos de interrogação (?), tem de adicionar três parâmetros por ordem de sequência.

      

      Para adicionar parâmetros de consulta, faça o seguinte:

      1. Na lista Tipo, selecione o tipo de dados do parâmetro.
      2. No campo Valor, introduza o valor do parâmetro.
      3. Para adicionar vários parâmetros, clique em + Adicionar parâmetro de consulta.

   A ação Executar consulta personalizada não suporta variáveis de matriz.

Use o Terraform para criar associações

Pode usar o recurso do Terraform para criar uma nova associação.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform.

Para ver um modelo do Terraform de exemplo para a criação de ligações, consulte o modelo de exemplo.

Quando criar esta associação através do Terraform, tem de definir as seguintes variáveis no ficheiro de configuração do Terraform:

Nome do parâmetro	Tipo de dados	Obrigatória	Descrição
project_id	STRING	True	O ID do projeto que contém o conjunto de dados do BigQuery. Por exemplo, myproject.
dataset_id	STRING	Falso	ID do conjunto de dados do BigQuery sem o nome do projeto. Por exemplo, mydataset.
proxy_enabled	BOOLEAN	Falso	Selecione esta caixa de verificação para configurar um servidor proxy para a ligação.
proxy_auth_scheme	ENUM	Falso	O tipo de autenticação a usar para autenticar no proxy ProxyServer. Os valores suportados são: BASIC, DIGEST, NONE
proxy_user	STRING	Falso	Um nome de utilizador a ser usado para autenticar no proxy ProxyServer.
proxy_password	SECRET	Falso	Uma palavra-passe a usar para autenticar no proxy ProxyServer.
proxy_ssltype	ENUM	Falso	O tipo de SSL a usar quando se liga ao proxy ProxyServer. Os valores suportados são: AUTO, ALWAYS, NEVER, TUNNEL

Limitações do sistema

O conetor do BigQuery pode processar um máximo de 8 transações por segundo, por nó e limita todas as transações que excedam este limite. Por predefinição, os Integration Connectors atribuem 2 nós (para uma melhor disponibilidade) a uma ligação.

Para informações sobre os limites aplicáveis aos Integration Connectors, consulte Limites.

Nota: o número de nós de conectores de integração é dimensionado automaticamente de forma dinâmica com base na sua utilização. No entanto, se quiser reservar capacidade para grandes volumes sem esperar pela escalabilidade automática, pode ajustar o valor mínimo de nós para uma ligação. São necessários mais nós para processar mais transações para uma associação. Por outro lado, são necessários menos nós se uma associação processar menos transações. Para configurar os valores dos nós, faça o seguinte:

• Se for cliente de pagamento conforme o uso, configure o valor mínimo e máximo do nó na página de edição da associação.
• Se for cliente com base numa subscrição, contacte o apoio técnico.

O número máximo de transações que um nó pode processar depende de vários fatores. Assim, antes de ajustar os nós mínimos para um melhor débito, é recomendável verificar se os seus sistemas de back-end estão configurados de forma ideal para processar o tráfego necessário.

Tipos de dados suportados

Seguem-se os tipos de dados suportados para este conector:

• ARRAY
• BIGINT
• BINARY
• BIT
• BOOLEAN
• CHAR
• DATA
• DECIMAL
• DOUBLE
• FLOAT
• INTEGER
• LONGN VARCHAR
• LONG VARCHAR
• NCHAR
• NUMERIC
• NVARCHAR
• REAL
• SMALL INT
• HORA
• TIMESTAMP
• TINY INT
• VARBINARY
• VARCHAR

Limitações conhecidas

• O conetor do BigQuery não suporta a chave primária numa tabela do BigQuery. Significa que não pode realizar as operações de entidades Get, Update e Delete através de um entityId. Em alternativa, pode usar a cláusula filter para filtrar registos com base num ID.

• Quando obtém dados pela primeira vez, pode sentir uma latência inicial de cerca de 6 segundos. Devido ao armazenamento em cache, não existe latência para pedidos subsequentes. Esta latência pode ocorrer novamente após a expiração da cache.

Obtenha ajuda da comunidade do Google Cloud

Pode publicar as suas perguntas e discutir este conector na comunidade do Google Cloud nos Fóruns do Cloud.

O que se segue?

• Compreenda como suspender e retomar uma associação.
• Compreenda como monitorizar a utilização do conector.
• Compreenda como ver os registos do conetor.