Criar um repositório

Este documento ajuda você a entender o conceito de repositórios no Dataform e como criar um novo.

Sobre os repositórios do Dataform

Cada repositório do Dataform contém uma coleção de arquivos SQLX e JavaScript que formam seu fluxo de trabalho, além de pacotes e arquivos de configuração do Dataform. Você interage com o conteúdo do repositório em um espaço de trabalho de desenvolvimento.

O Dataform mostra seus repositórios na página do Dataform em ordem alfabética de IDs. É possível classificar e filtrar.

• Para conferir seus repositórios, no Google Cloud console, acesse a página Dataform.

  Acesse o Dataform

Cada repositório do Dataform é conectado a um agente de serviço padrão do Dataform ou a uma conta de serviço personalizada. Só é possível selecionar uma conta de serviço personalizada ao criar um repositório. É possível editar a conta de serviço depois.

Por padrão, o Dataform usa um agente de serviço ou uma conta de serviço derivada do número do projeto no seguinte formato:

[e-mail]

O Dataform usa o Git para registrar mudanças e gerenciar versões de arquivos. Cada repositório do Dataform corresponde a um repositório Git. Depois de criar um repositório do Dataform, é possível conectá-lo a um repositório remoto do GitHub, GitLab ou Bitbucket.

Em um repositório do Dataform, o Dataform armazena o código do repositório. Em um repositório conectado, o repositório de terceiros armazena o código do repositório. O Dataform interage com o repositório de terceiros para permitir que você edite e execute o conteúdo dele em um espaço de trabalho de desenvolvimento do Dataform.

A página do repositório do Dataform consiste nos seguintes componentes:

Guia "Espaços de trabalho de desenvolvimento"

Mostra os espaços de trabalho de desenvolvimento criados no repositório.

Guia "Registros de execução do fluxo de trabalho"

Mostra os registros de execução do fluxo de trabalho do Dataform.

Guia "Versões e programação"

Permite inspecionar, criar, editar e excluir configurações de versão e configurações de fluxo de trabalho.

Guia "Configurações"

Mostra o nome e o local do repositório. Para um repositório conectado a um repositório Git de terceiros, mostra a origem do repositório de terceiros, o nome da ramificação padrão e o token secreto. Mostra os botões para conectar o repositório a um repositório Git de terceiros e para editar a conexão Git.

Botão "Criar espaço de trabalho de desenvolvimento"

Permite criar um espaço de trabalho de desenvolvimento.

Depois de criar e inicializar um espaço de trabalho de desenvolvimento, é possível editar o arquivo de configurações do fluxo de trabalho para configurar as seguintes configurações do Dataform no repositório:

• O banco de dados padrão (ID do projetoGoogle Cloud ).
• O esquema padrão (ID do conjunto de dados do BigQuery).
• O local padrão do BigQuery.
• O esquema padrão (ID do conjunto de dados do BigQuery) para asserções.
• O depósito, que precisa ser definido como bigquery.
• Variáveis definidas pelo usuário que são disponibilizadas ao código do projeto durante a compilação.

Importante: os repositórios criados no Dataform não ficam visíveis nos repositórios do BigQuery.

Para mais informações sobre as configurações do repositório do Dataform, consulte IProjectConfig na referência principal do Dataform.

Configurações do repositório

Ao criar um repositório do Dataform, é necessário definir as seguintes configurações:

ID do repositório

Um ID exclusivo do repositório. Os IDs podem incluir apenas números, letras, hifens e sublinhados.

Região

Região do Dataform para armazenar o repositório e o conteúdo dele.

Essa região de armazenamento pode ser diferente da região de processamento em que o Dataform processa seu código e armazena a saída das execuções. Por padrão, a região de processamento é definida como a região padrão do conjunto de dados do BigQuery. É possível editar a região de processamento no arquivo de configurações do fluxo de trabalho depois de criar o repositório. Para mais informações, consulte Configurar as definições de fluxo de trabalho do Dataform.

Agente de serviço ou conta de serviço

O agente de serviço do Dataform ou a conta de serviço personalizada associada ao repositório. Para novos repositórios, é necessário fornecer uma conta de serviço personalizada. É possível selecionar uma conta de serviço associada ao seu projeto do Google Cloud ou inserir manualmente uma conta diferente.

Por padrão, o Dataform usa um agente de serviço ou uma conta de serviço derivada do número do projeto no seguinte formato:

[e-mail]

Você precisa usar uma conta de serviço personalizada para executar fluxos de trabalho no seu repositório, mas o agente de serviço padrão do Dataform ainda é usado para todas as outras operações do repositório.

Modo de simulação restrito

Ativa uma verificação de segurança adicional que exige a permissão iam.serviceAccounts.actAs na conta de serviço. Para novos repositórios, o modo estrito "agir como" é aplicado. Para repositórios atuais, recomendamos usar contas de serviço personalizadas e ativar o modo "agir como" estrito para garantir um modelo de permissões mais seguro e previsível.

Criptografia

Método de criptografia do repositório. É possível usar a criptografia padrão, uma chave de criptografia do Cloud KMS gerenciada pelo cliente ou uma chave CMEK padrão do Dataform. Para mais informações sobre o uso de chaves de criptografia gerenciadas pelo cliente (CMEK) no Dataform, consulte Usar chaves de criptografia gerenciadas pelo cliente.

Depois de criar um repositório, você pode conectá-lo ao GitHub ou GitLab.

Importante: para criar um repositório do Dataform conectado a um repositório Git remoto que não está na lista de permissões da política dataform.restrictGitRemotes, primeiro adicione o repositório Git remoto à lista allowedValues na política. Em seguida, crie um repositório do Dataform e conecte-o ao repositório remoto. Para mais informações, consulte Restringir repositórios remotos.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Dataform APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Dataform APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. Para usar a criptografia CMEK no repositório, ative a criptografia CMEK dos repositórios do Dataform.

Importante: antes de criar um repositório do Dataform que você quer conectar a um repositório Git remoto, verifique se sua organização ou projeto restringe repositórios Git remotos com a Política da organização dataform.restrictGitRemotes. Se a política estiver em vigor, verifique se o repositório remoto está na lista de permissões antes de criar o repositório do Dataform e conectá-lo ao repositório remoto. Para mais informações, consulte Restringir repositórios remotos

Funções exigidas

Para receber as permissões necessárias para criar e excluir um repositório, peça ao administrador para conceder os seguintes papéis do IAM nos repositórios:

• Administrador do Dataform (roles/dataform.admin): o projeto
• Usuário da conta de serviço (roles/iam.serviceAccountUser): a conta de serviço personalizada

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.

Conceder os papéis necessários

Para executar fluxos de trabalho no seu repositório do Dataform e no BigQuery, use uma conta de serviço personalizada ou sua Conta do Google.

Sua conta de serviço personalizada precisa ter os seguintes papéis obrigatórios:

• Editor de dados do BigQuery (roles/bigquery.dataEditor) em projetos ou conjuntos de dados específicos do BigQuery a que o Dataform precisa de acesso de leitura e gravação. Isso geralmente inclui o projeto que hospeda seu repositório do Dataform.
• Leitor de dados do BigQuery (roles/bigquery.dataViewer) em projetos ou conjuntos de dados específicos do BigQuery a que o Dataform precisa de acesso somente leitura.
• Usuário de jobs do BigQuery (roles/bigquery.jobUser) no projeto que hospeda seu repositório do Dataform.

Para permitir que o Dataform use sua conta de serviço personalizada, o agente de serviço padrão do Dataform precisa ter os seguintes papéis no recurso da conta de serviço personalizada:

• Criador do token da conta de serviço (roles/iam.serviceAccountTokenCreator)
• Usuário da conta de serviço (roles/iam.serviceAccountUser)

Para conceder esses papéis, siga estas etapas:

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

   Acessar IAM

2. Clique em Conceder acesso.

3. No campo Novos principais, insira o ID da sua conta de serviço personalizada.

4. No menu Selecionar um papel, selecione os seguintes papéis um por um, usando Adicionar outro papel para cada papel adicional:

   • Editor de dados do BigQuery
   • Visualizador de dados do BigQuery
   • Usuário de jobs do BigQuery

5. Clique em Salvar.

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

   Acesse as Contas de serviço

7. Selecione sua conta de serviço personalizada.

8. Acesse Principais com acesso e clique em Conceder acesso.

9. No campo Novos principais, insira o ID do agente de serviço padrão do Dataform.

   O ID do agente de serviço padrão do Dataform está no seguinte formato:

   [e-mail]
   

   Substitua PROJECT_NUMBER pelo ID numérico do seu projeto do Google Cloud . Encontre o ID do projeto Google Cloud no painel do consoleGoogle Cloud . Para mais informações, consulte Identificar projetos.

10. Na lista Selecionar um papel, adicione os seguintes papéis:

    • Usuário da conta de serviço
    • Criador do token da conta de serviço

11. Clique em Salvar.

Para mais informações sobre como conceder papéis, consulte Conceder ao Dataform o acesso necessário.

Criar um repositório

Para criar um repositório do Dataform, siga estas etapas:

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

   Acesse o Dataform

2. Clique em Criar repositório.

3. Na página Criar repositório, no campo ID do repositório, insira um ID exclusivo.

   Os IDs podem incluir apenas números, letras, hifens e sublinhados.

4. Na lista suspensa Região, selecione uma região do Dataform para armazenar o repositório e o conteúdo dele. Selecione a região do Dataform mais próxima de você.

   Para uma lista de regiões disponíveis do Dataform, consulte Locais. A região do repositório não precisa corresponder ao local dos seus conjuntos de dados do BigQuery.

   No arquivo workflow_settings.yaml, é possível definir a região de processamento em que o Dataform processa seu código e armazena a saída das execuções. A região de processamento precisa corresponder ao local dos conjuntos de dados do BigQuery, mas não precisa corresponder à região do repositório. Para mais informações, consulte Configurar as definições de fluxo de trabalho do Dataform.

5. No menu Conta de serviço, selecione uma conta de serviço personalizada para o repositório.

   Importante: não é possível selecionar o agente de serviço padrão do Dataform ao criar um repositório. Você precisa usar uma conta de serviço personalizada para o repositório.

   No menu, selecione uma conta de serviço personalizada associada ao projeto Google Cloud a que você tem acesso. As contas de serviço personalizadas são usadas apenas para a execução do fluxo de trabalho. Todas as outras operações do repositório são realizadas pelo agente de serviço padrão do Dataform.

   1. Opcional: para selecionar uma conta de serviço que não aparece no menu (por exemplo, se você não tiver a permissão iam.serviceAccounts.list necessária para ver a lista de papéis), clique em Inserir manualmente e digite o ID da conta de serviço.
   Observação: a permissão iam.serviceAccounts.list está disponível no papel "Visualizar contas de serviço" (roles/iam.serviceAccountViewer).

6. Na seção Verificações de permissão actAs, aplique as verificações de permissão nas ações do usuário no repositório. Para mais detalhes sobre essas verificações, consulte Usar o modo estrito "agir como".

7. Configure o mecanismo de criptografia selecionado para o repositório:

   Atenção: não é possível mudar o mecanismo de criptografia de um repositório do Dataform depois que ele é criado. Para mais informações, consulte Restrições da CMEK do Dataform

   Chave CMEK padrão

   O Dataform mostra e seleciona por padrão a caixa de seleção Usar a chave padrão do KMS.

   • Para criptografar o repositório com a chave CMEK padrão do Dataform, deixe a caixa de seleção Usar a chave padrão do KMS marcada.

   Atenção: se você marcar a caixa de seleção Usar a chave KMS padrão, mas nenhuma chave CMEK padrão do Dataform estiver definida para seu projeto, o Dataform aplicará a criptografia em repouso ao repositório. Use chaves de criptografia gerenciadas pelo cliente.

   Chave CMEK exclusiva

   Para criptografar o repositório com uma chave CMEK exclusiva, faça o seguinte:

   1. Se a caixa de seleção Usar a chave padrão do KMS estiver marcada por padrão, desmarque-a.
   2. Na seção Criptografia, selecione a opção Chaves de criptografia gerenciadas pelo cliente (CMEK).
   3. No menu suspenso Selecionar uma chave gerenciada pelo cliente, selecione uma chave CMEK exclusiva.

   Criptografia em repouso

   • Para usar a criptografia padrão, na seção Criptografia, selecione a opção Google-managed encryption key.

   Atenção: se uma chave CMEK padrão do Dataform estiver definida para a região do seu repositório, use a criptografia CMEK. Não selecione a opção Google-managed encryption key. Para mais informações, consulte Restrições da CMEK do Dataform.

8. Clique em Criar e em Acessar repositórios.

Editar a conta de serviço

Você precisa associar uma conta de serviço personalizada a um repositório do Dataform para execução do fluxo de trabalho. Todas as outras operações de repositório ainda são realizadas pelo agente de serviço padrão do Dataform.

Para editar a conta de serviço de um repositório do Dataform, siga estas etapas:

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

   Acesse o Dataform

2. Selecione um repositório e clique em Configurações.

   Observação: a lista de repositórios do Dataform inclui apenas repositórios criados para o desenvolvimento de fluxos de trabalho do Dataform. Os repositórios de recursos do BigQuery Studio, como notebooks ou consultas salvas, são gerenciados separadamente e não aparecem nessa lista.

3. Ao lado do campo Conta de serviço, clique em Editar conta de serviço.

4. No menu Conta de serviço, selecione uma conta de serviço para o repositório.

   No menu, selecione uma conta de serviço personalizada associada ao projeto Google Cloud a que você tem acesso.

   1. Opcional: para selecionar uma conta de serviço que não aparece no menu, clique em Inserir manualmente e digite um ID da conta de serviço.

5. Clique em Salvar.

Excluir um repositório.

Para excluir um repositório e todo o conteúdo dele, siga estas etapas:

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

   Acesse o Dataform

2. Ao lado do repositório que você quer excluir, clique no menu Mais e selecione Excluir.

3. Na janela Excluir repositório, insira o nome do repositório para confirmar a exclusão.

4. Clique em Excluir.

A seguir

• Para saber como conectar um repositório do Dataform a um repositório Git de terceiros, consulte Conectar a um repositório Git de terceiros.
• Para saber mais sobre como o tamanho do repositório afeta o desenvolvimento no Dataform, consulte Visão geral do tamanho do repositório.
• Para saber mais sobre como dividir um repositório no Dataform, consulte Introdução à divisão de repositórios.
• Para saber como configurar as opções de processamento do Dataform, consulte Configurar as opções de fluxo de trabalho do Dataform.
• Para saber como criar e inicializar um espaço de trabalho, consulte Criar um espaço de trabalho.