BigQuery: inserir linha

Use BigQuery: inserir linha para transmitir uma linha para uma tabela do BigQuery a partir de uma etapa da jornada, através da API de inserção por streaming. Assim como em Google Sheets: adicionar linha, este ponto se autentica através da conta do Google conectada uma vez para toda a conta. Não há campo de token no próprio ponto.

Usos típicos:

• Alimentar uma tabela de relatórios: insira uma linha por etapa da jornada alcançada, para um painel ou consulta agendada posteriormente.
• Registrar eventos à medida que acontecem: transmita dados brutos da jornada para o BigQuery em vez de esperar por uma exportação em lote.
• Juntar com dados existentes: insira um valor de dispositivo ou Tag que suas tabelas do BigQuery possam juntar com seus próprios conjuntos de dados.

Antes de começar

Conecte uma conta do Google em Configurações > Integrações de terceiros > Google. Esta é a mesma conexão que Google Sheets: adicionar linha usa. Depois de conectar o Google, instale a integração para que o ponto apareça no construtor de jornadas.

Este não é o card Google BigQuery nessa página. Esse é a integração do BigQuery: ele transmite cada evento de mensagem de um aplicativo para um esquema fixo em uma chave de conta de serviço. Este ponto escreve uma linha que você define, na etapa em que você o coloca, e não utiliza uma chave própria.

Cuidado

Se você conectou o Google antes do suporte ao BigQuery ser adicionado, reconecte-o uma vez. Uma conexão mantém as permissões que foram concedidas, então uma conexão mais antiga pode escrever no Sheets, mas não no BigQuery, e o ponto falha com um 403.

Duas coisas também precisam estar configuradas no lado do Google Cloud, ou a solicitação falhará:

• O conjunto de dados e a tabela já devem existir. Este ponto escreve linhas. Ele nunca cria uma tabela.
• A conta do Google conectada precisa da função Editor de Dados do BigQuery (ou qualquer função que conceda bigquery.tables.updateData) nesse conjunto de dados.

Configure o ponto

1. Arraste BigQuery: inserir linha da seção Integrações do painel esquerdo para a tela.
2. Dê um duplo clique no ponto e insira um Nome da Etapa.
3. Em ID do Projeto, insira o ID do projeto do Google Cloud. Use o id, não o nome de exibição, por exemplo, my-analytics-prod.

4. Em Conjunto de dados, insira o nome do conjunto de dados.

5. Em Tabela, insira o nome da tabela.

6. Em Colunas, adicione uma linha para cada coluna do BigQuery a ser escrita. Insira o nome da coluna e o valor. Os nomes não devem estar vazios e devem ser únicos. Cada coluna que você listar deve existir no esquema da tabela. Um valor pode ser um texto fixo ou uma macro do viajante, como {{tag:Name}}, as mesmas macros de um corpo de Webhook. Ou clique em Inserir Valor Dinâmico para escolher um atributo que uma etapa anterior nesta jornada produziu, por exemplo, uma resposta de LLM ou um valor de Webhook mapeado.

Exemplo

Com Conjunto de dados definido como marketing e Tabela como journey_events, definir Colunas como device_id com o ID do dispositivo do viajante ({{device:hwid}}) escreve uma linha na coluna device_id dessa tabela.

7. Clique em Salvar.

Resposta

O viajante continua para qualquer etapa que você conectar a seguir na tela.

Atributos após a execução da etapa

Este ponto não retorna um atributo em caso de sucesso. Se o BigQuery rejeitar uma linha, o erro é escrito em bigquery_insert_error. Veja Falhas e respostas inesperadas.

Falhas e respostas inesperadas

Abra o Registro de chamadas na gaveta do ponto e verifique a resposta:

• 401 — a conexão do Google está ausente ou expirou. Reconecte-a em Configurações > Integrações de terceiros.
• 403 com accessDenied: Streaming insert is not allowed in the free tier — o projeto não tem uma conta de faturamento associada. Inserções por streaming, que é o que este ponto usa, não fazem parte do sandbox do BigQuery. Habilite o faturamento no projeto e a mesma solicitação será processada.
• 403 com accessDenied ou insufficientPermissions — a conexão foi concedida antes da adição do suporte ao BigQuery (reconecte-a), ou a conta do Google não tem acesso de escrita ao conjunto de dados.
• 403 com quotaExceeded ou rateLimitExceeded — a cota de inserção por streaming do projeto foi esgotada. Não há nada a reconectar. A jornada precisa enviar menos, ou a cota precisa ser aumentada no Google Cloud.
• 404 — o nome do projeto, conjunto de dados ou tabela não corresponde a nada.

Cuidado

Uma linha que o BigQuery rejeita (uma coluna desconhecida ou um valor que não se encaixa no tipo da coluna) retorna como 200 com um corpo insertErrors, e não como um status de erro. O viajante prossegue como se a escrita tivesse sido bem-sucedida. A primeira mensagem desse tipo é escrita no atributo do viajante bigquery_insert_error. A divisão de condição não pode ramificar com base nela diretamente, então salve-a em uma Tag com Atualizar perfil do usuário primeiro, e depois ramifique com base nessa Tag com uma Divisão de condição. O corpo completo está no Registro de chamadas.

Uma solicitação com falha remove o viajante da jornada. Veja Erros e solicitações com falha.

Cenário de exemplo: Alimentando uma tabela de relatórios do BigQuery

Uma equipe deseja a atividade da jornada no mesmo conjunto de dados do BigQuery que seus relatórios agendados já consultam.

1. Adicione BigQuery: inserir linha logo após a etapa que você deseja registrar. Defina Conjunto de dados como marketing e Tabela como journey_events. Em Colunas, defina device_id como {{device:hwid}}.
2. Clique em Salvar.

Uma vez que isso é executado, a linha é inserida na mesma tabela que a consulta agendada lê, então a próxima execução do relatório já a incluirá.