Programar pipelines

Neste documento, descrevemos como programar pipelines do BigQuery, incluindo como programar pipelines e inspecionar execuções programadas.

Os pipelines são gerados pelo Dataform. Cada programação de pipeline é executada usando as credenciais de usuário da sua Conta do Google ou uma conta de serviço personalizada que você seleciona ao configurar a programação.

As mudanças feitas em um pipeline são salvas automaticamente, mas ficam disponíveis apenas para você e para os usuários com a função de administrador do Dataform no projeto. Para atualizar a programação com uma nova versão do pipeline, é necessário implantar o pipeline. A implantação atualiza a programação para usar a versão atual do pipeline. Os agendamentos sempre executam a versão implantada mais recente.

As programações de pipelines que contêm notebooks usam uma especificação de ambiente de execução padrão. Durante uma execução programada de um pipeline que contém notebooks, o BigQuery grava a saída do notebook no bucket do Cloud Storage selecionado durante a criação da programação.

Antes de começar

Antes de começar, crie um pipeline.

Ativar a programação de pipelines

Para programar pipelines, conceda o seguinte papel à conta de serviço personalizada que você planeja usar para programações de pipeline:

Usuário da conta de serviço (roles/iam.serviceAccountUser)

Siga Conceder uma única função em uma conta de serviço para adicionar a conta de serviço como principal a si mesma. Em outras palavras, adicione a conta de serviço como principal à mesma conta de serviço. Em seguida, conceda o papel de usuário da conta de serviço a esse principal.

Se o pipeline tiver consultas SQL, conceda os seguintes papéis à conta de serviço que você planeja usar para programações de pipeline:

Usuário de jobs do BigQuery (roles/bigquery.jobUser)

Siga Conceder um único papel em um projeto para conceder a função de usuário do job do BigQuery à sua conta de serviço em projetos de onde seus pipelines leem dados.

Visualizador de dados do BigQuery (roles/bigquery.dataViewer)

Siga Conceder um único papel em um projeto para conceder o papel de leitor de dados do BigQuery à sua conta de serviço em projetos em que seus pipelines leem dados.

Editor de dados do BigQuery (roles/bigquery.dataEditor)

Siga Conceder um único papel em um projeto para conceder o papel de Editor de dados do BigQuery à sua conta de serviço em projetos para os quais seus pipelines gravam dados.

Se o pipeline tiver notebooks, conceda os seguintes papéis à conta de serviço que você planeja usar para programações de pipeline:

Usuário Executor do notebook (roles/aiplatform.notebookExecutorUser)

Siga Conceder um único papel em um projeto para conceder a função de usuário de executor de notebooks à sua conta de serviço no projeto selecionado.

Administrador do Storage (roles/storage.admin)

Siga as instruções em Adicionar um principal a uma política no nível do bucket para adicionar a conta de serviço como um principal ao bucket do Cloud Storage que você planeja usar para armazenar a saída de notebooks executados em execuções de pipeline programadas e conceda o papel de administrador do Storage a esse principal.

Além disso, é necessário conceder os seguintes papéis ao agente de serviço padrão do Dataform:

Criador do token da conta de serviço (roles/iam.serviceAccountTokenCreator)

Siga as instruções em Conceder acesso à criação de tokens a uma conta de serviço para adicionar o agente de serviço padrão do Dataform como principal à sua conta de serviço e conceder o papel "Criador de token da conta de serviço" a esse principal.

Usuário da conta de serviço (roles/iam.serviceAccountUser)

Siga Conceder ou revogar vários papéis do IAM usando o Google Cloud console para conceder o papel de usuário da conta de serviço ao agente de serviço padrão do Dataform na conta de serviço personalizada.

Para saber mais sobre contas de serviço no Dataform, consulte Sobre as contas de serviço no Dataform.

Funções exigidas

Para receber as permissões necessárias para gerenciar pipelines, peça ao administrador que conceda a você os seguintes papéis do IAM:

• Excluir pipelines: Administrador do Dataform (roles/dataform.Admin) no pipeline
• Criar, editar, executar e excluir programações de pipeline:
  • Administrador do Dataform (roles/dataform.Admin) no pipeline
  • Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço personalizada
• Conferir e executar pipelines: Leitor do Dataform (roles/dataform.Viewer) no projeto
• Conferir programações de pipeline: Editor do Dataform (roles/dataform.Editor) 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 usando papéis personalizados ou outros papéis predefinidos.

Para aumentar a segurança do agendamento, consulte Implementar permissões de agendamento aprimoradas.

Para mais informações sobre o IAM do Dataform, consulte Controlar o acesso com o IAM.

Para usar modelos de ambiente de execução de notebook do Colab ao programar pipelines, você precisa da função de usuário do ambiente de execução de notebook (roles/aiplatform.notebookRuntimeUser).

Criar uma programação de pipeline

Dica: também é possível usar a página Pipelines e conexões para programar um pipeline do Dataform usando um fluxo de trabalho simplificado específico do BigQuery. Esse recurso está em pré-lançamento.

Para criar uma programação de pipeline, siga estas etapas:

Painel Explorer

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Explorer, expanda seu projeto, clique em Pipelines e selecione um pipeline.

4. Clique em Programação.

5. No painel Programar pipeline, no campo Nome da programação, insira um nome para a programação.

6. Na seção Autenticação, autorize o pipeline com as credenciais de usuário da sua Conta do Google ou uma conta de serviço.

   • Para usar as credenciais de usuário da sua Conta do Google (Prévia), selecione Executar com minhas credenciais de usuário.
   • Para usar uma conta de serviço, selecione Executar com a conta de serviço selecionada e escolha uma conta.

7. Se o pipeline tiver um notebook, na seção Opções de notebook, no campo Modelo de execução, selecione um modelo de ambiente de execução do notebook do Colaboratory ou as especificações de ambiente de execução padrão. Para detalhes sobre como criar um modelo de ambiente de execução de notebook do Colab, consulte Criar um modelo de ambiente de execução.

   Observação: um modelo de ambiente de execução de notebook precisa estar na mesma região que o pipeline.
   Observação: se você não tiver a função necessária para usar modelos de ambiente de execução de notebook do Colab, ainda será possível executar e programar pipelines com as especificações de ambiente de execução padrão.

8. Se o pipeline tiver um notebook, na seção Opções de notebook, no campo Bucket do Cloud Storage, clique em Procurar e selecione ou crie um bucket do Cloud Storage para armazenar a saída dos notebooks no pipeline.

   A conta de serviço selecionada precisa receber o papel do IAM "Administrador de armazenamento" no bucket selecionado. Para mais informações, consulte Ativar a programação de pipelines.

9. Em Tipo de configuração, selecione Programação (recorrência com base em tempo).

10. Em Frequência de programação, faça o seguinte:

    1. No menu Repetições, selecione a frequência de execução do pipeline programado.
    2. No campo Em horário, insira o horário das execuções programadas do pipeline.
    3. No menu Fuso horário, selecione o fuso horário da programação.

11. Defina a prioridade do job de consulta do BigQuery com a opção Executar como job interativo com alta prioridade (padrão). Por padrão, o BigQuery executa consultas como jobs de consulta interativos, que são projetados para começar a ser executados o mais rápido possível. Desmarcar essa opção executa as consultas como jobs de consulta em lote, que têm prioridade mais baixa.

12. Clique em Criar programação. Se você selecionou Executar com minhas credenciais de usuário como método de autenticação, autorize sua Conta do Google (Prévia).

Quando você cria a programação, a versão atual do pipeline é implantada automaticamente. Para atualizar a programação com uma nova versão do pipeline, implante o pipeline.

A versão mais recente implantada do pipeline é executada no horário e na frequência selecionados.

Observação: se uma execução programada de pipeline não for concluída antes do início da próxima execução programada, ela será ignorada e marcada com um erro.

Página Programação

1. No console Google Cloud , acesse a página Programação.

   Acessar "Programação"

2. Clique em Criar e selecione Programação de pipeline no menu.

3. No painel Programar pipeline, selecione um pipeline para programar.

4. No campo Nome da programação, insira um nome para a programação.

5. Na seção Autenticação, autorize o pipeline com as credenciais de usuário da sua Conta do Google ou uma conta de serviço.

   • Para usar as credenciais de usuário da sua Conta do Google (Prévia), selecione Executar com minhas credenciais de usuário.
   • Para usar uma conta de serviço, selecione Executar com a conta de serviço selecionada e escolha uma conta.

6. Se o pipeline tiver um notebook, na seção Opções de notebook, no campo Modelo de execução, selecione um modelo de execução de notebook do Colab ou as especificações de execução padrão. Para detalhes sobre como criar um modelo de notebook do Colab, consulte Criar um modelo de ambiente de execução.

   Observação: um modelo de ambiente de execução do notebook precisa estar na mesma região que o pipeline.
   Observação: se você não tiver a função necessária para usar modelos de ambiente de execução do notebook do Colab, ainda será possível executar e programar pipelines com as especificações de ambiente de execução padrão.

7. Se o pipeline tiver um notebook, no campo Bucket do Cloud Storage, clique em Procurar e selecione ou crie um bucket do Cloud Storage para armazenar a saída dos notebooks no pipeline.

   A conta de serviço selecionada precisa receber o papel do IAM "Administrador de armazenamento" no bucket selecionado. Para mais informações, consulte Ativar a programação de pipelines.

8. Em Tipo de configuração, selecione Programação (recorrência com base em tempo).

9. Em Frequência de programação, faça o seguinte:

   1. No menu Repetições, selecione a frequência de execução do pipeline programado.
   2. No campo Em horário, insira o horário das execuções programadas do pipeline.
   3. No menu Fuso horário, selecione o fuso horário da programação.

10. Defina a prioridade do job de consulta do BigQuery com a opção Executar como job interativo com alta prioridade (padrão). Por padrão, o BigQuery executa consultas como jobs de consulta interativos, que são projetados para começar a ser executados o mais rápido possível. Desmarcar essa opção executa as consultas como jobs de consulta em lote, que têm prioridade mais baixa.

11. Clique em Criar programação. Se você selecionou Executar com minhas credenciais de usuário como método de autenticação, autorize sua Conta do Google (Prévia).

Observação: se uma execução programada de pipeline não for concluída antes do início da próxima execução programada, ela será ignorada e marcada com um erro.

Autorizar sua Conta do Google

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção "Termos Gerais de Serviço" dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: para solicitar suporte ou enviar feedback sobre esse recurso, entre em contato com [e-mail].

Para autenticar o recurso com suas credenciais de usuário da Conta do Google, conceda permissão manualmente para que os pipelines do BigQuery recebam o token de acesso da sua Conta do Google e acessem os dados de origem em seu nome. É possível conceder aprovação manual com a interface da caixa de diálogo do OAuth.

Observação: as políticas de Acesso baseado no contexto (CAA), incluindo as baseadas em IP, geolocalização e conformidade do dispositivo, não são compatíveis ao executar ou programar pipelines do BigQuery com credenciais de usuário de uma Conta do Google, porque as solicitações de token se originam da infraestrutura do Google. As políticas de CAA bloqueiam essas execuções, a menos que o ID do cliente OAuth do Dataform seja dispensado das políticas.

Você só precisa conceder permissão aos pipelines do BigQuery uma vez.

Para revogar a permissão concedida, siga estas etapas:

1. Acesse a página da sua Conta do Google.
2. Clique em Pipelines do BigQuery.
3. Clique em Remover acesso.

Aviso: a revogação de permissões de acesso impede que execuções de pipeline futuras sejam realizadas pela Conta do Google em todas as regiões.

Alterar o proprietário da programação do pipeline atualizando as credenciais também requer aprovação manual se o novo proprietário da Conta do Google nunca tiver criado uma programação antes.

Se o pipeline tiver um notebook, você também precisará conceder manualmente permissão para que o Colab Enterprise receba o token de acesso da sua Conta do Google e acesse os dados de origem em seu nome. Você só precisa conceder permissão uma vez. É possível revogar essa permissão na página da Conta do Google.

Programação baseada em gatilhos

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: para receber suporte ou enviar feedback sobre esse recurso, entre em contato com [e-mail].

É possível configurar pipelines do BigQuery para acionar automaticamente execuções com base em atualizações de tabelas especificadas do BigQuery. Você pode criar programações baseadas em gatilhos para automatizar as execuções de pipeline em resposta a mudanças nos seus dados do BigQuery, em vez de uma programação fixa.

Quando o pipeline detecta mudanças na tabela ou nas tabelas especificadas, ele aciona uma nova execução do fluxo de trabalho associado. É possível definir condições com base em atualizações de uma única tabela, de todas as tabelas de um conjunto ou de qualquer tabela de um conjunto.

Também é possível ajustar as configurações opcionais dos seus programações baseadas em gatilhos para controlar o intervalo mínimo entre eles. Por exemplo, ajuste o valor de Duração mínima da execução para garantir que os programações baseadas em acionadores não sejam ativadas com mais frequência do que o pretendido. Você também pode ajustar o valor de Duração máxima de espera para garantir que o agendamento baseado em gatilho seja ativado uma vez dentro desse período, mesmo que nenhuma atualização de tabela tenha sido detectada.

Limitações

As programações baseadas em gatilhos estão sujeitas às seguintes limitações:

• As programações baseadas em gatilhos não são instantâneas. Ao configurar uma programação baseada em gatilho, o pipeline verifica o status da tabela do BigQuery aproximadamente uma vez a cada três minutos. Esse período é chamado de intervalo de sondagem e pode resultar em um atraso entre uma modificação de tabela e a ativação do gatilho.
• Cada tabela monitorada resulta em chamadas de API para o BigQuery durante todos os intervalos de pesquisa. Monitorar um número muito grande de tabelas pode contribuir para o consumo de cota da API BigQuery.

Criar um gatilho

Para criar um gatilho, siga estas etapas:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Explorer, expanda seu projeto, clique em Pipelines e selecione um pipeline.

4. Clique em Gatilho.

5. No campo Gatilho, insira um nome para o gatilho.

6. Na seção Autenticação, autorize o pipeline com as credenciais de usuário da sua Conta do Google ou uma conta de serviço.

   • Para usar as credenciais de usuário da sua Conta do Google (Prévia), selecione Executar com minhas credenciais de usuário.
   • Para usar uma conta de serviço, selecione Executar com a conta de serviço selecionada e escolha uma conta.

7. Se o pipeline tiver um notebook, na seção Opções de notebook, no campo Modelo de execução, selecione um modelo de ambiente de execução do notebook do Colaboratory ou as especificações de ambiente de execução padrão. Para detalhes sobre como criar um modelo de ambiente de execução de notebook do Colab, consulte Criar um modelo de ambiente de execução.

   Observação: um modelo de ambiente de execução de notebook precisa estar na mesma região que o pipeline.
   Observação: se você não tiver a função necessária para usar modelos de ambiente de execução de notebook do Colab, ainda será possível executar e programar pipelines com as especificações de ambiente de execução padrão.

8. Se o pipeline tiver um notebook, na seção Opções de notebook, no campo Bucket do Cloud Storage, clique em Procurar e selecione ou crie um bucket do Cloud Storage para armazenar a saída dos notebooks no pipeline.

   A conta de serviço selecionada precisa receber o papel do IAM "Administrador de armazenamento" no bucket selecionado. Para mais informações, consulte Ativar a programação de pipelines.

9. Em Tipo de configuração, selecione Acionador (execução baseada em eventos).

10. No campo Pesquisar tabelas, adicione uma ou mais tabelas para monitorar o acionador.

11. Em Condição de acionamento, selecione uma das seguintes opções:

    • Aguarde a atualização de TODAS as tabelas: acione o fluxo de trabalho somente quando todas as tabelas listadas forem atualizadas desde a última verificação.
    • Acione se QUALQUER tabela for atualizada: acione esse fluxo de trabalho se alguma das tabelas listadas for atualizada desde a última verificação.

12. (Opcional) Em Duração máxima de espera, insira uma duração para forçar a ativação de um gatilho se nenhuma atualização de tabela for detectada nesse período. Aceita valores entre 1 segundo e 7 dias. Se não for especificado, o fluxo de trabalho só será executado se a tabela monitorada for atualizada e a duração mínima de execução for atendida.

13. (Opcional) Em Duração mínima da execução, selecione uma duração para evitar que os acionadores sejam ativados com mais frequência do que essa duração mínima. Aceita valores entre 3 minutos e 24 horas. Se não for especificado, o valor padrão será de 3 minutos.

14. Clique em Criar programação. Se você selecionou Executar com minhas credenciais de usuário como método de autenticação, autorize sua Conta do Google (Prévia).

Solução de problemas de programações baseadas em gatilhos

Esta seção descreve problemas comuns com programações baseadas em gatilhos e como resolvê-los.

Problema: o gatilho não está ativando

Resolução:tente uma das seguintes etapas:

• Verifique se as credenciais do usuário ou a conta de serviço têm todas as permissões necessárias.
• Verifique se a tabela especificada do BigQuery está sendo modificada.
• Verifique se o gatilho não está sendo afetado pelo intervalo de pesquisa.
• Verifique se a duração mínima da execução ou o valor Duração mínima da execução está impedindo execuções mais frequentes. É possível diminuir esse valor para aumentar a frequência de ativação do gatilho.
• Verifique se a opção de condição de acionamento (ALL ou ANY) está afetando a ativação do acionador.
• Examine os registros de auditoria para verificar se há erros quando o Dataform tenta chamar a API BigQuery para verificar o status da tabela monitorada.

Problema: o gatilho está sendo ativado com muita frequência

Resolução:ajuste a duração mínima da execução ou o valor de Duração mínima da execução. É possível aumentar esse valor para diminuir a frequência de ativação do gatilho.

Implantar um pipeline

A implantação de um pipeline atualiza a programação com a versão atual dele. Os agendamentos executam a versão implantada mais recente do pipeline.

Para implantar um pipeline, siga estas etapas:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda seu projeto, clique em Pipelines e selecione um pipeline.

4. Clique em Implantar.

A programação correspondente é atualizada com a versão atual do pipeline. A versão mais recente implantada do pipeline é executada no horário programado.

Desativar uma programação

Para pausar as execuções programadas de um pipeline selecionado sem excluir a programação, desative a programação.

Para desativar uma programação de um pipeline selecionado, siga estas etapas:

Painel Explorer

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda seu projeto, clique em Pipelines e selecione um pipeline.

4. Clique em Ver programação.

5. Na tabela de detalhes da programação, na linha Estado da programação, clique no botão A programação está ativada.

Página Programação

1. No console Google Cloud , acesse a página Programação.

   Acessar "Programação"

2. Clique no nome do pipeline selecionado.

3. Na página Detalhes da programação, clique em Desativar.

Ativar uma programação

Para retomar as execuções programadas de uma programação de pipeline desativada, siga estas etapas:

Painel Explorer

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda seu projeto, clique em Pipelines e selecione um pipeline.

4. Clique em Ver programação.

5. Na tabela de detalhes da programação, na linha Estado da programação, clique no botão A programação está desativada.

Página Programação

1. No console Google Cloud , acesse a página Programação.

   Acessar "Programação"

2. Clique no nome do pipeline selecionado.

3. Na página Detalhes da programação, clique em Ativar.

Executar manualmente um pipeline implantado

Quando você executa manualmente um pipeline implantado em uma programação selecionada, o BigQuery executa o pipeline implantado uma vez, independente da programação.

Para executar manualmente um pipeline implantado, siga estas etapas:

1. No console Google Cloud , acesse a página Programação.

   Acessar "Programação"

2. Clique no nome da programação de pipeline selecionada.

3. Na página de detalhes da programação, clique em Executar.

Conferir todas as programações de pipeline

Para conferir todas as programações de pipeline no seu projeto Google Cloud , siga estas etapas:

1. No console Google Cloud , acesse a página Programação.

   Acessar "Programação"

2. Opcional: para mostrar outras colunas com detalhes da programação do pipeline, clique em Opções de exibição de colunas, selecione as colunas e clique em OK.

Conferir detalhes da programação do pipeline

Para conferir os detalhes de uma programação de pipeline selecionada, siga estas etapas:

Painel Explorer

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda seu projeto, clique em Pipelines e selecione um pipeline.

4. Clique em Ver programação.

Página Programação

1. No console Google Cloud , acesse a página Programação.

   Acessar "Programação"

2. Clique no nome da programação de pipeline selecionada.

Conferir execuções programadas anteriores

Para conferir as execuções anteriores de uma programação de pipeline selecionada, siga estas etapas:

Painel Explorer

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda seu projeto, clique em Pipelines e selecione um pipeline.

4. Clique em Execuções.

5. Opcional: para atualizar a lista de execuções anteriores, clique em Atualizar.

Página Programação

1. No console Google Cloud , acesse a página Programação.

   Acessar "Programação"

2. Clique no nome do pipeline selecionado.

3. Na página Detalhes da programação, na seção Execuções anteriores, inspecione as execuções anteriores.

4. Opcional: para atualizar a lista de execuções anteriores, clique em Atualizar.

Editar uma programação de pipeline

Para editar uma programação de pipeline, siga estas etapas:

Painel Explorer

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

3. No painel Explorer, expanda seu projeto, clique em Pipelines e selecione um pipeline.

4. Clique em Ver programação e em Editar.

5. Na caixa de diálogo Programar pipeline, edite a programação e clique em Atualizar programação.

Página Programação

1. No console Google Cloud , acesse a página Programação.

   Acessar "Programação"

2. Clique no nome do pipeline selecionado.

3. Na página Detalhes da programação, clique em Editar.

4. Clique em Ver programação e em Editar.

5. Na caixa de diálogo Programar pipeline, edite a programação e clique em Atualizar programação.

Excluir uma programação de pipeline

Para excluir permanentemente uma programação de pipeline, siga estas etapas:

1. No console Google Cloud , acesse a página Programação.

   Acessar "Programação"

2. Realize uma das seguintes ações:

   • Clique no nome da programação de pipeline selecionada e, na página Detalhes da programação, clique em Excluir.

   • Na linha que contém a programação de pipeline selecionada, clique em Ver ações na coluna Ações e em Excluir.

3. Na caixa de diálogo exibida, clique em Excluir.

A seguir

• Saiba mais sobre pipelines no BigQuery.
• Saiba como criar pipelines.