Organizar recursos de código com pastas e repositórios

Este documento apresenta uma visão geral conceitual do sistema de pastas e repositórios. Ele também resume os campos e métodos da API Dataform usados para trabalhar com pastas e repositórios.

A API Dataform oferece recursos que podem ser usados para organizar recursos de código em uma estrutura hierárquica semelhante a um sistema de arquivos típico de sistema operacional. Essa estrutura também permite a herança de políticas do Identity and Access Management (IAM), permitindo que as permissões sejam propagadas pelo caminho.

A lista a seguir define os termos-chave usados para descrever o sistema de pastas e repositórios:

Pasta
Uma pasta é o contêiner básico para organizar recursos, semelhante a uma pasta padrão do sistema de arquivos. Ele permite organizar outras pastas e repositórios, além de mover recursos para dentro e para fora das pastas. Você pode conceder permissões no nó da pasta, e elas são propagadas para todo o conteúdo.
Pasta raiz do usuário
Uma pasta raiz do usuário representa o espaço pessoal de um usuário. Ele contém todas as pastas e repositórios que um usuário cria ou acessa. Uma pasta raiz do usuário não faz parte da subárvore de uma pasta de equipe. Uma pasta raiz do usuário é um conceito virtual que não tem um recurso de API associado.
Pasta da equipe
Uma pasta de equipe é semelhante a uma pasta, mas foi projetada para a colaboração em equipe, parecida com um drive compartilhado no Google Drive. Ele oferece um espaço dedicado para recursos de código principais e oferece suporte a permissões de compartilhamento e acesso mais restritas para os recursos principais de uma equipe.
Arquivo
No contexto dessa estrutura de pastas, um arquivo é representado por um recurso de repositório do Dataform. Cada repositório contém um único ativo de arquivo, como um notebook, uma consulta salva, uma tela de dados ou uma preparação de dados.

Funções exigidas

Para receber as permissões necessárias para concluir as tarefas neste documento, peça ao administrador para conceder a você os papéis do IAM adequados no projeto, na pasta ou no recurso.

As permissões concedidas em uma pasta são propagadas para todas as pastas e arquivos contidos nela.

As seguintes funções se aplicam a pastas e arquivos:

Papel Concedido em Permissões e casos de uso
Proprietário do código (roles/dataform.codeOwner) Pasta ou arquivo Concede controle total sobre um recurso para gerenciar recursos de código. Um usuário com essa função pode realizar todas as ações, incluindo excluir o recurso, definir a política do IAM e movê-lo.
Editor de código (roles/dataform.codeEditor) Pasta ou arquivo Permite editar e gerenciar conteúdo. Um usuário com essa função pode adicionar conteúdo a pastas, editar arquivos e receber a política do IAM de uma pasta ou arquivo. Essa função também é necessária na pasta de destino ao mover um recurso.
Comentarista de código (roles/dataform.codeCommenter) Pasta ou arquivo Permite fazer comentários em recursos ou pastas de código.
Visualizador de código (roles/dataform.codeViewer) Pasta ou arquivo Fornece acesso somente leitura. Um usuário com essa função pode consultar o conteúdo de pastas e arquivos.
Criador de código (roles/dataform.codeCreator) Projeto Concede permissão para criar novas pastas e arquivos em um projeto.

As seguintes funções são específicas para gerenciar pastas de equipe:

Papel Concedido em Permissões e casos de uso
Proprietário da pasta de equipe (roles/dataform.teamFolderOwner) Pasta da equipe Concede controle total sobre uma pasta de equipe para gerenciar recursos de código. Um usuário com essa função pode excluir a pasta de equipe e definir a política do IAM dela.
Colaborador da pasta de equipe (roles/dataform.teamFolderContributor) Pasta da equipe Permite o gerenciamento de conteúdo em uma pasta da equipe. Um usuário com essa função pode atualizar uma pasta de grupo.
Comentador da pasta da equipe (roles/dataform.teamFolderCommenter) Pasta da equipe Permite comentar em uma pasta da equipe e nos recursos de código que ela contém.
Leitor de pastas de equipe (roles/dataform.teamFolderViewer) Pasta da equipe Dá acesso somente leitura a uma pasta da equipe e ao conteúdo dela. Um usuário com essa função pode acessar uma pasta de equipe e receber a política do IAM dela.
Criador de pastas de equipe (roles/dataform.teamFolderCreator) Projeto Concede permissão para criar pastas de equipe em um projeto.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para concluir as tarefas neste documento. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

  • Criar uma pasta:
    • folders.create na pasta do usuário principal, na pasta da equipe ou no projeto
    • folders.addContents na pasta principal ou de equipe
  • Recuperar as propriedades de uma pasta: folders.get na pasta
  • Consultar o conteúdo de uma pasta ou pasta de equipe: folders.queryContents na pasta
  • Atualizar uma pasta: folders.update na pasta
  • Excluir uma pasta: folders.delete na pasta
  • Acessar a política do IAM de uma pasta: folders.getIamPolicy na pasta
  • Definir a política do IAM para uma pasta: folders.setIamPolicy na pasta
  • Mover uma pasta:
    • folders.move na pasta que está sendo movida
    • folders.addContents na pasta de destino ou na pasta de equipe (não é necessário se você estiver movendo para uma pasta raiz)
  • Criar uma pasta de equipe: teamFolders.create no projeto
  • Excluir uma pasta de equipe: teamFolders.delete na pasta de equipe
  • Acessar a política do IAM para uma pasta de equipe: teamFolders.getIamPolicy na pasta de equipe
  • Defina a política do IAM para uma pasta de equipe: teamFolders.setIamPolicy na pasta de equipe
  • Recuperar as propriedades de uma pasta de equipe: teamFolders.get na pasta de equipe
  • Atualizar uma pasta de equipe: teamFolders.update na pasta de equipe
  • Crie um repositório:
    • repositories.create na pasta do usuário principal, na pasta da equipe ou no projeto
    • folders.addContents na pasta principal ou de equipe
  • Ler um repositório: repositories.readFile no repositório
  • Gravar em um repositório: repositories.commit no repositório
  • Mover um repositório:
    • repositories.move no repositório que está sendo movido
    • folders.addContents na pasta do usuário pai, na pasta de equipe ou no projeto de destino (não é necessário se a movimentação for para uma pasta raiz)
  • Recupere as propriedades de um repositório: repositories.get no repositório
  • Atualizar um repositório: repositories.update no repositório
  • Excluir um repositório: repositories.delete no repositório

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Para ter acesso total ao gerenciamento dos recursos de código no seu projeto, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Herança de políticas do IAM

O acesso do IAM aos recursos de pasta e repositório usa uma estrutura hierárquica. Essa hierarquia garante que as políticas de acesso sejam herdadas das pastas principais para o conteúdo delas.

Quando uma política do IAM é definida em uma pasta, as permissões concedidas por essa política também se aplicam a todos os repositórios e subpastas aninhadas na subárvore da pasta. Isso tem as seguintes consequências:

  • As permissões são herdadas pela hierarquia de pastas. Quando um usuário recebe um papel específico em uma pasta de alto nível, ele tem as permissões incluídas nesse papel para todos os recursos contidos nessa pasta e nas subpastas dela.
  • As permissões que um usuário tem em um recurso consistem nas políticas definidas diretamente nesse recurso e em todas as políticas herdadas de cada pasta no caminho até a raiz.

Como resultado, você não precisa de permissões no nível do projeto para realizar ações em recursos localizados em uma estrutura de pastas complexa. Você só precisa da permissão adequada em qualquer pasta no caminho até esse recurso. Por exemplo, se você quiser criar um repositório em uma subpasta, precisará das permissões necessárias na subpasta específica ou em qualquer uma das pastas mãe, incluindo a pasta de nível superior.

Confira a seguir as práticas recomendadas para aplicar políticas do IAM a pastas e repositórios:

  • Aplique políticas do IAM à pasta mais alta na hierarquia em que as permissões são necessárias de maneira uniforme. Por exemplo, se uma equipe precisar acessar todos os dados no diretório dela, conceda os papéis necessários no nível da pasta da equipe em vez de no nível das subpastas de projetos individuais.
  • Sempre conceda o conjunto mínimo de permissões necessárias para que usuários ou serviços executem as tarefas. Evite conceder papéis amplos quando for possível usar papéis e permissões mais específicos no nível da pasta.

Papéis do IAM concedidos na criação de recursos

Os seguintes papéis são concedidos automaticamente na criação do recurso:

É possível usar a API Config para conceder uma função específica na criação de recursos.

Você não recebe automaticamente nenhuma função ao criar pastas ou repositórios na subárvore de uma pasta de equipe.

Limitações

As pastas e os repositórios têm as seguintes limitações:

  • Só é possível aninhar pastas em até cinco níveis.
  • Depois de mover um repositório para uma pasta, o repositório e os recursos secundários dele não ficam visíveis no Inventário de recursos do Cloud.
  • No máximo, 100 recursos podem participar de uma única operação de movimentação.
  • Ter um número muito grande de pastas (centenas de milhares) diminui o desempenho ao trabalhar com elas.

Organize recursos

As seções a seguir descrevem como organizar recursos de pasta, pasta de equipe e repositório com a API Dataform.

Recursos de pasta

A tabela a seguir descreve os campos da API para pastas:

Campo Descrição
containing_folder Uma referência à pasta mãe ou ao nome da pasta de equipe. É possível definir como um ID de pasta ou de pasta compartilhada. Se você não definir esse campo, será uma pasta raiz.
display_name O nome visível para o usuário do recurso. O campo display_name precisa ser exclusivo de acordo com as seguintes regras:
  • Na raiz do usuário, todas as pastas precisam ter nomes de exibição exclusivos. No entanto, os nomes de exibição do repositório na raiz do usuário podem entrar em conflito com outros nomes de repositórios e pastas.
  • Em uma pasta, os nomes de exibição precisam ser exclusivos em todas as pastas e repositórios.
  • Em uma pasta de equipe, os nomes de exibição precisam ser exclusivos em todas as pastas e repositórios.
  • Os nomes de exibição das pastas de equipe precisam ser exclusivos no projeto.

A tabela a seguir descreve os principais métodos da API projects.locations.folders:

Método de API Descrição
create Cria uma pasta.
get Recebe as propriedades de uma pasta.
patch Atualiza as propriedades de uma pasta, como o nome.
queryFolderContents Lista os itens em uma pasta.
move Move a pasta e toda a subárvore dela para uma nova pasta. Uma operação de movimentação é atômica, ou seja, ela só é concluída se todos os recursos na subárvore da pasta forem movidos corretamente e não houver falhas parciais.
delete Exclui a pasta. Só será bem-sucedida se a pasta estiver vazia.
setIamPolicy Concede papéis à pasta. Os papéis concedidos são propagados automaticamente para toda a subárvore da pasta.

O exemplo a seguir demonstra como criar uma pasta no nível raiz:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "displayName": "DISPLAY_NAME"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/folders"

Substitua:

  • DISPLAY_NAME: o nome visível para o usuário do recurso.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: o local do repositório do Dataform em que os recursos são criados.

O exemplo a seguir demonstra como criar uma pasta aninhada em outra:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "displayName": "DISPLAY_NAME",
      "containingFolder": "projects/PROJECT_ID/locations/LOCATION/folders/PARENT_FOLDER_ID"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/folders"

Substitua:

  • DISPLAY_NAME: o nome visível para o usuário do recurso.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: o local do repositório do Dataform em que os recursos são criados.
  • PARENT_FOLDER_ID: o ID da pasta em que você quer criar a nova pasta.

O exemplo a seguir demonstra como mover uma pasta para outra:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "destination_containing_folder": "projects/PROJECT_ID/locations/LOCATION/folders/DESTINATION_PARENT_FOLDER_ID"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/folders/FOLDER_ID_TO_MOVE:move"

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: o local do repositório do Dataform.
  • DESTINATION_PARENT_FOLDER_ID: o ID da pasta em que você quer mover a pasta de destino.
  • FOLDER_ID_TO_MOVE: o ID da pasta que você está movendo.

Recursos de pastas de equipe

A tabela a seguir descreve os principais métodos da API projects.locations.teamFolders:

Método de API Descrição
create Cria uma pasta de equipe.
get Recebe as propriedades de uma pasta de equipe.
patch Atualiza as propriedades de uma pasta da equipe, como o nome.
queryContents Lista os itens em uma pasta de equipe.
delete Exclui a pasta de equipe. Só funciona se a pasta da equipe estiver vazia.
setIamPolicy Concede papéis à pasta de equipe. As funções concedidas são propagadas automaticamente para toda a subárvore da pasta de grupo.

O exemplo a seguir mostra como consultar o conteúdo de uma pasta de equipe:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/teamFolders/TEAM_FOLDER_ID:queryContents"

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: o local dos recursos do Dataform.
  • TEAM_FOLDER_ID: o ID da pasta específica da equipe do Dataform que você está consultando.

Recursos do repositório

É possível organizar os recursos do repositório em recursos de pasta e pasta de equipe com o campo containing_folder no nó pasta.

A tabela a seguir descreve os métodos da API para repositórios:

A tabela a seguir descreve os principais métodos da API projects.locations.repositories:

Método de API Descrição
create Cria um novo repositório.
get Recebe as propriedades de um repositório.
patch Atualiza as propriedades de um repositório, como o nome.
move Move o repositório para uma nova pasta.
delete Exclui o repositório.
setIamPolicy Concede papéis ao repositório. As funções concedidas são propagadas automaticamente para toda a subárvore do repositório.

O exemplo a seguir demonstra como criar um repositório no nó raiz do usuário ao definir setAuthenticatedUserAdmin como true:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "displayName": "REPOSITORY_DISPLAY_NAME",
      "setAuthenticatedUserAdmin": true
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/repositories?repositoryId=REPOSITORY_ID"

Substitua:

  • REPOSITORY_DISPLAY_NAME: um nome fácil de usar para o repositório.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: o local do repositório.
  • REPOSITORY_ID: o ID do novo repositório.

O exemplo a seguir demonstra como criar um repositório em uma pasta de equipe:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "containingFolder": "projects/PROJECT_ID/locations/LOCATION/teamFolders/CONTAINING_TEAM_FOLDER_ID"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/repositories?repositoryId=REPOSITORY_ID"

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: o local em que os recursos são criados. Precisa ser o mesmo local do CONTAINING_TEAM_FOLDER_ID.
  • CONTAINING_TEAM_FOLDER_ID: o ID da pasta de equipe específica em que você quer colocar o novo repositório.
  • REPOSITORY_ID: o ID do novo repositório.

O exemplo a seguir demonstra como mover um repositório para a pasta raiz:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "destination_containing_folder": ""
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID:move"

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: o local em que o repositório existe.
  • REPOSITORY_ID: o ID do repositório que você quer mover para o nível raiz.

Recursos ocupados

Uma pasta, pasta de grupo ou repositório está "ocupado" se estiver envolvido em uma operação de movimentação, seja como o objeto que está sendo movido ou o destino da movimentação. Para garantir a integridade dos dados durante a movimentação, o sistema restringe as seguintes ações em recursos ocupados:

  • Ser o objeto de outra operação de movimentação.
  • Ser o destino de outra operação de movimentação.
  • Ser um ancestral de um objeto de movimento.
  • Ser o objeto de uma operação de exclusão.

A seguir