Como criar e gerenciar pastas

As pastas são nodes no Cloud Platform Resource Hierarchy. Uma pasta pode conter projetos, outras pastas ou uma combinação de ambos. Os recursos da organização podem usar pastas para agrupar projetos no nó de recursos da organização em uma hierarquia. Por exemplo, o recurso da sua organização pode conter vários departamentos, cada um com o próprio conjunto de recursos do Google Cloud. Com as pastas, você pode agrupar esses recursos por departamento ou agrupar recursos que compartilham políticas comuns do IAM. Cada pasta pode conter várias pastas ou recursos. No entanto, uma determinada pasta ou recurso pode ter somente um pai.

No diagrama abaixo, o recurso da organização, "Company", tem pastas que representam dois departamentos, "Dept X" e "Dept Y", e uma pasta "Shared Infrastructure" para itens que podem ser comuns a ambos os departamentos. Em "Dept Y", eles se organizam em duas equipes e, dentro das pastas de equipe, eles organizam por produtos. A pasta para o "Product 1" contém três projetos, cada um com os recursos necessários para o projeto. Isso oferece uma grande flexibilidade na atribuição de políticas de IAM às políticas da Organização no nível de granularidade ideal.

Você pode usar políticas de IAM de nível de pasta para controlar o acesso aos recursos que a pasta contém. Por exemplo, se um usuário receber o papel Administrador da instância do Compute em uma pasta, esse usuário terá o papel Administrador da instância do Compute em todos os projetos na pasta.

Antes de começar

A funcionalidade de pasta está disponível apenas para clientes do Google Workspace e do Cloud Identity que tenham um recurso de organização. Para mais informações sobre como adquirir um recurso Organização, consulte Como criar e gerenciar organizações.

Se você estiver explorando a melhor maneira de usar as pastas, recomendamos que você:

1. Leia o tópico Controle de acesso para pastas usando o IAM. Ele descreve como controlar quem tem acesso às pastas e aos recursos que elas contêm.
2. Saiba como definir permissões de pasta. As pastas são compatíveis com vários papéis de IAM diferentes. Se você quiser configurar as permissões de forma ampla para que os usuários possam ver a estrutura dos projetos, conceda ao domínio inteiro os papéis de Visualizador da organização e Visualizador de pastas no nível do recurso da organização. Conceda o papel Visualizador de pastas nas pastas que quiser que os usuários vejam. Dessa forma, a visibilidade é restrita a partes da hierarquia da pasta.
3. Crie pastas. Ao planejar a organização dos recursos no Cloud, recomendamos que você comece com uma única pasta, como um sandbox. Assim, é possível decidir qual é a melhor hierarquia para o recurso da sua organização. Imagine que as pastas são como limites de isolamento entre os recursos e pontos de conexão para políticas de acesso e configuração. Para delegar esse privilégio, é possível criar pastas para recursos de diferentes departamentos e atribuir papéis de Administrador em pastas. As pastas também podem ser usadas para agrupar recursos que pertencem a aplicativos ou ambientes diferentes, como desenvolvimento, produção e teste. Use pastas aninhadas para modelar esses cenários diferentes.

Uma situação comum é criar pastas que, por sua vez, contêm outros projetos ou pastas, conforme mostrado na imagem acima. Essa estrutura é conhecida como hierarquia de pastas. Ao criar esse tipo de hierarquia, lembre-se do seguinte:

• Você pode aninhar pastas em até 10 (dez) níveis de profundidade.
• Uma pasta pai não pode conter mais do que 300 pastas. Isso se refere somente a pastas filho diretas. Essas pastas filho podem, por sua vez, conter outros projetos ou pastas.
• Os nomes de exibição das pastas precisam ser exclusivos dentro do mesmo nível da hierarquia.

Configurar permissões para gerenciar pastas

Para acessar e gerenciar pastas, atribua papéis de IAM específicos da pasta a grupos específicos de usuários. Para saber mais sobre esses papéis, consulte Controle de acesso para pastas que usam o IAM. Também recomendamos que você leia nossas práticas recomendadas para ajudar a identificar a melhor configuração para suas permissões de pasta.

Para gerenciar pastas em todo o recurso da organização, é preciso ter o papel de Administrador de pastas. Ele dá autorização ao usuário para criar, editar, excluir, mover e alterar permissões de IAM em pastas, bem como para mover projetos entre elas.

Inicialmente, somente o administrador da organização pode atribuir o papel de administrador de pastas ao recurso da organização. As contas subsequentes que tiverem esse papel poderão concedê-lo a outras contas.

Para configurar as permissões de pasta, siga estas etapas:

Console

1. No Console do Google Cloud, abra a página Gerenciar recursos.

   Acesse "Gerenciar recursos"

2. Se o painel de informações não estiver aberto, clique em Mostrar painel de informações.
3. Na tabela Resources, expanda a organização que contém a pasta.
4. Na lista de recursos da organização, selecione a pasta que você quer gerenciar.
5. No painel de informações, clique em Adicionar participante.
6. No campo Add principals, insira o endereço de e-mail a quem você quer conceder permissões.
7. No menu Selecionar um papel, selecione a categoria Resource Manager e, em seguida, selecione o papel que você quer conceder, como Administrador de pastas.
8. Clique em Salvar para conceder o novo papel.

gcloud

Para conceder a função de administrador de pastas a um principal usando a Google Cloud CLI, execute o seguinte comando:

    gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
    --member=user:USER_ID \
    --role=roles/resourcemanager.folderAdmin

API

A solicitação JSON:

request_json= '{ policy: { version: "1", bindings: [ { role: "roles/folderAdmin",
members: [ "user:[e-mail]", ] }, { role: "roles/folderCreator",
members: [   "user:[e-mail]", ] } , { role: "roles/folderMover",
members: [ "user:[e-mail]", ] } , ] } }'

A solicitação curl:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ${bearer_token}" \
-d "$request_json" \
https://cloudresourcemanager.googleapis.com/v3/ORGANIZATION_NAME:setIamPolicy

Substitua ORGANIZATION_NAME pelo nome da organização cuja política de IAM está sendo definida, por exemplo, organizations/123.

Como criar pastas

Para criar pastas, você precisa ter o papel Administrador de pasta ou Criador de pastas no nível pai. Por exemplo, para criar pastas no nível da organização, você precisa ter um desses papéis nesse nível.

Como parte da criação de uma pasta, você precisa atribuir um nome a ela. Os nomes de pasta precisam atender aos seguintes requisitos:

• O nome pode conter letras, dígitos, espaços, hifens e sublinhados.
• O nome de exibição da pasta precisa começar e terminar com uma letra ou um dígito.
• O nome precisa ter entre 3 e 30 caracteres.
• O nome precisa ser distinto de todas as outras pastas que compartilhem o mesmo pai.

Para criar uma pasta:

Console

As pastas podem ser criadas na IU usando a seção "Gerenciar projetos e pastas".

1. Acesse a página Gerenciar recursos no console do Google Cloud:

   Abrir a página "Gerenciar recursos"

2. Verifique se o nome do recurso da sua organização está selecionado na lista suspensa de organizações na parte de cima da página.

3. Clique em Criar pasta e selecione uma das seguintes opções:

   • Pasta padrão: um recurso de pasta padrão.
   • Pasta em conformidade: uma pasta do Assured Workloads, que oferece controles regulatórios, regionais ou soberanos adicionais para recursos do Google Cloud. Ao selecionar essa opção, você vai acessar o Assured Workloads para criar uma pasta.

4. Na caixa Nome da pasta, insira o nome da nova pasta.

5. Em Destino, clique em Procurar e selecione o recurso ou a pasta da organização em que você quer criar a nova pasta.

   1. Clique em Criar.

gcloud

É possível criar pastas de maneira programática usando a Google Cloud CLI.

Para criar uma pasta no recurso da organização usando a ferramenta de linha de comando gcloud, execute o seguinte comando:

gcloud resource-manager folders create \
   --display-name=[DISPLAY_NAME] \
   --organization=[ORGANIZATION_ID]

Para criar uma pasta cujo pai é outra pasta:

gcloud resource-manager folders create \
   --display-name=[DISPLAY_NAME] \
   --folder=[FOLDER_ID]

Em que:

• [DISPLAY_NAME] é o nome de exibição da pasta. Pastas com o mesmo pai não podem ter o mesmo nome de exibição. O nome de exibição precisa começar e terminar com uma letra ou um dígito, pode conter letras, dígitos, espaços, hifens e sublinhados e não pode ter mais de 30 caracteres;
• [ORGANIZATION_ID] é o ID do recurso de organização pai, se o pai for um recurso de organização.
• [FOLDER_ID] é o código da pasta pai, se o pai for uma pasta.

API

É possível criar pastas com uma solicitação de API.

A solicitação JSON:

request_json= '{
  display_name: DISPLAY_NAME,
  parent: ORGANIZATION_NAME
}'

A solicitação curl Criar pasta:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ${bearer_token}" \
-d "$request_json" \
https://cloudresourcemanager.googleapis.com/v3/folders

Em que:

• [DISPLAY_NAME] é o nome de exibição da pasta nova. Por exemplo, "Minha pasta maravilhosa";
• [ORGANIZATION_NAME] é o nome do recurso da organização em que a pasta está sendo criada, por exemplo, organizations/123.

A resposta Criar pasta:

{
  "name": "operations/fc.123456789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  }
}

A solicitação curl Receber operação:

curl -H "Authorization: Bearer ${bearer_token}" \
https://cloudresourcemanager.googleapis.com/v3/operations/fc.123456789

A resposta Receber operação:

{
  "name": "operations/fc.123456789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.Folder",
    "name": "folders/12345",
    "parent": "organizations/123",
    "displayName": "[DISPLAY_NAME]",
    "lifecycleState": "ACTIVE",
    "createTime": "2017-07-19T23:29:26.018Z",
    "updateTime": "2017-07-19T23:29:26.046Z"
  }
}

Adicionar tags durante a criação de pastas

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" 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.

As tags são uma maneira de criar anotações para recursos. É possível adicionar tags ao criar pastas. Para isso, é necessário conceder o papel de Usuário de tags. Para mais informações sobre as permissões contidas nessa função, consulte Gerenciar tags em recursos. Só é possível adicionar o namespace para os pares de chave-valor da tag de uma destas formas:

gcloud

Para adicionar tags durante a criação de pastas, execute o seguinte comando:

  gcloud resource-manager folders create \
  --display-name=DISPLAY_NAME \
  --organization=ORGANIZATION_ID
  --tags=KEY_VALUE_PAIRS

Substitua:

• DISPLAY_NAME é o nome de exibição da pasta.
• ORGANIZATION_ID é o identificador exclusivo do recurso organização pai.
• KEY_VALUE_PAIRS é uma lista de pares de chave-valor separados por vírgulas que pode ser atribuída ao seu recurso. Um exemplo de pares de chave-valor separados por vírgulas é 123/environment=production, 456/create=testresource.

API

O snippet a seguir é uma solicitação JSON que cria uma pasta e adiciona tags a ela.

  POST https://cloudresourcemanager.googleapis.com/v3/projects/
  Authorization: *************
  Content-Type: application/json

  {
    "display_name": "our-folder-456",
    "parent": "organizations/123",
    "tags": {
      "key": "123/environment"
      "value": "production"
    },
"tags": {
      "key": "123/costCenter"
      "value": "marketing"
    }
  }

Como configurar o acesso às pastas

Para configurar o acesso às pastas, você precisa ter o papel Administrador de pastas do IAM ou Administrador de pasta no nível pai.

Console

1. No console do Google Cloud, abra a página Gerenciar recursos.

   Abrir a página "Gerenciar recursos"

2. Clique na lista suspensa Organização no canto superior esquerdo e selecione o recurso da organização.

3. Marque a caixa de seleção ao lado do projeto em que você quer mudar as permissões.

   1. No Painel de informações ao lado direito, em Permissões, insira os endereços de e-mail dos membros que você quer adicionar.

   2. Na lista suspensa Selecionar papel, escolha o papel que você quer conceder a esses membros.

   3. Clique em Adicionar. Uma notificação vai aparecer para confirmar a adição ou atualização do novo papel dos membros.

gcloud

É possível configurar o acesso a pastas de modo programático usando a Google Cloud CLI ou a API.

gcloud resource-manager folders \
  add-iam-policy-binding [FOLDER_ID] \
  --member=user:[e-mail] \
  --role=roles/resourcemanager.folderEditor

gcloud resource-manager folders \
  add-iam-policy-binding [FOLDER_ID] \
  --member=user:[e-mail] \
  --role=roles/resourcemanager.folderViewer

Como alternativa:

gcloud resource-manager folders \
  set-iam-policy [FOLDER_ID] [POLICY_FILE]

Em que:

• [FOLDER_ID] é o código da nova pasta.
• [POLICY_FILE] é o caminho para um arquivo de política para a pasta.

API

O método setIamPolicy define a política de controle de acesso em uma pasta, substituindo qualquer política atual. O campo resource precisa ser o nome do recurso da pasta. Por exemplo, folders/1234.

 request_json= '{
   policy: {
     version: "1",
     bindings: [
       {
         role: "roles/resourcemanager.folderEditor",
         members: [
           "user:[e-mail]",
           "user:[e-mail]",
         ]
       }
     ]
   }
 }'

A solicitação curl:

   curl -X POST -H "Content-Type: application/json" \
   -H "Authorization: Bearer ${bearer_token}" \
   -d "$request_json" \
   https://cloudresourcemanager.googleapis.com/v3/[FOLDER_NAME]:setIamPolicy

Em que:

• [FOLDER_NAME] é o nome da pasta com a política do IAM que está sendo definida. Por exemplo, folders/123.

Como criar um projeto em uma pasta

Para criar um projeto em uma pasta, é preciso ter o papel Criador de projetos (roles/resourcemanager.projectCreator) na pasta. Esse papel pode ser herdado de uma pasta pai.

Console

1. No console do Google Cloud, abra a página "Gerenciar recursos".

   Abrir o console do Google Cloud

2. Acesse a página "Gerenciar recursos"
3. Selecione o recurso da organização no menu suspenso Organização, na parte de cima esquerda da página.
4. Clique em Criar projeto.
5. Digite o Nome do projeto.

6. Na caixa Destino, clique em Procurar para selecionar a pasta na qual você quer criar o projeto.

7. Clique em Criar.

gcloud

  gcloud projects create PROJECT_ID --folder FOLDER_ID

Substitua:

• PROJECT_ID é o ID do projeto a ser criado.
• FOLDER_ID é o ID da pasta em que o projeto precisa ser criado.

API

A solicitação JSON:

   request_json= '{
      name: DISPLAY_NAME, projectId: PROJECT_ID, parent: {id: PARENT_ID, type: PARENT_TYPE}
   }'

A solicitação curl:

   curl -X POST -H "Content-Type: application/json" \
   -H "Authorization: Bearer ${bearer_token}" \
   -d "$request_json" \
   https://cloudresourcemanager.googleapis.com/v3/projects

Substitua:

• PROJECT_ID é o identificador exclusivo do projeto que está sendo criado. Por exemplo, my-awesome-proj-123.
• DISPLAY_NAME é o nome de exibição do projeto que está sendo criado.
• PARENT_ID é o identificador exclusivo do pai em que ele está sendo criado. Por exemplo, 123.
• PARENT_TYPE é o tipo de pai, como folder ou organization.

Não inclua informações sensíveis no nome da pasta ou em outros nomes de recursos. Qualquer referência à pasta ou aos recursos relacionados expõe o nome da pasta e o nome do recurso.

Como mover um projeto para uma pasta

Considere cuidadosamente as implicações de política antes de mover um projeto para ou dentro de uma pasta. As políticas do Identity and Access Management definidas no nível do projeto serão movidas com o projeto, mas as políticas herdadas de um recurso pai não serão.

Observação: as instruções a seguir são apenas para mover um projeto dentro de um recurso de organização. Para informações sobre como migrar um projeto entre recursos da organização, consulte Como migrar projetos.

Quando você move um projeto, todas as políticas de gerenciamento de identidade e acesso ou políticas da organização anexadas diretamente serão movidas com ele. No entanto, um projeto na hierarquia de recursos também é afetado pelas políticas herdadas de recursos pai. Se um projeto herdar um papel do IAM que forneça aos usuários permissão para usar um determinado serviço, os usuários não terão acesso a esse serviço no destino, a menos que ele herde a permissão no destino também.

Por exemplo, considere que uma conta de serviço tem o papel de criador de objetos do Storage vinculado a um usuário na Pasta A. A conta de serviço tem permissões para fazer upload de dados para o Cloud Storage em qualquer projeto na Pasta A. Se você moveu um desses projetos para a Pasta B, que não tem as mesmas permissões herdadas, a conta de serviço desse projeto perde a capacidade de fazer upload de dados, resultando em uma interrupção do serviço.

Essas mesmas considerações se aplicam se as políticas da Organização estiverem definidas nas pastas de origem e de destino. Assim como as políticas de IAM, as da Organização são herdadas. Portanto, você precisa garantir que as políticas da Organização sejam consistentes entre as pastas de origem e de destino.

Para saber mais sobre políticas da Organização, consulte Introdução ao serviço de Política de Organização.

Para mover um projeto, você precisa do papel do IAM do Transportador de projetos (roles/resourcemanager.projectMover) na pasta de origem e na pasta de destino. Se o recurso não estiver em uma pasta, você precisará dessa função no recurso da organização.

Esses papéis concedem as seguintes permissões exigidas:

• resourcemanager.projects.update no projeto
• Se o recurso estiver em uma pasta:resourcemanager.projects.move na pasta de origem e na de destino
• Se o recurso não estiver em uma pasta:resourcemanager.projects.move no recurso da organização

Também é possível receber essas permissões com papéis personalizados ou outros papéis predefinidos.

Console

Para mover um projeto, siga estas etapas:

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

   Acesse "Gerenciar recursos"

2. Selecione a organização na lista suspensa Organização, na parte superior esquerda da página.

3. Clique na linha do projeto para selecioná-lo na lista de recursos. Não clique no nome do projeto, porque isso leva você até a página do IAM do projeto.

4. Clique no menu de opções (as reticências verticais) da linha e clique em Mover.

5. Clique em Procurar para selecionar a pasta para que você quer mover o projeto.

6. Clique em Mover.

gcloud

Para mover um projeto, execute o comando gcloud beta projects move:

gcloud beta projects move PROJECT_ID \
--DESTINATION_TYPE DESTINATION_ID

Em que:

• PROJECT_ID é o ID ou o número do projeto que você quer mover.

• DESTINATION_TYPE é organization ou folder.

• DESTINATION_ID é o ID do recurso ou da pasta da organização para onde você quer mover o projeto. Só é possível especificar um destino.

API

Use o método v3 projects.move para mover um projeto.

Solicitação:

POST https://cloudresourcemanager.googleapis.com/v3/{name=PROJECT_NAME}:move
{
  "destinationParent": DESTINATION_PARENT
}

Em que:

• PROJECT_NAME é o nome da visualização que você quer atualizar. Por exemplo, projects/415104041262

• DESTINATION_PARENT é o novo recurso ou pasta da organização mãe para onde você quer mover o projeto. Por exemplo: organizations/12345678901

Se for bem-sucedida, a solicitação retornará uma Operação que pode ser usada para rastrear a movimentação do projeto.

Como mover uma pasta para outra

Para mover uma pasta para outra, é necessário ter a permissão resourcemanager.folders.move para as pastas de origem e de destino.

Console

O processo de transferência de uma pasta para outras pastas no console é semelhante ao de projetos.

1. No console do Google Cloud, abra a página "Gerenciar recursos".

   Abrir o console do Google Cloud

2. Selecione o recurso da organização no menu suspenso Organização, na parte de cima esquerda da página.
3. Clique na linha da pasta para selecioná-la na lista de projetos e pastas.
4. Clique no menu de opções (as reticências verticais) da linha e em Mover.
5. Clique em Procurar para selecionar a pasta para que você quer mover a pasta.
6. Clique em Mover.

gcloud

Para mover uma pasta do recurso Organização, execute o seguinte comando na Google Cloud CLI:

gcloud resource-manager folders move [FOLDER_ID] \
  --organization=[PARENT_ID]

Para mover uma pasta para outra pasta:

gcloud resource-manager folders move [FOLDER_ID] \
  --folder=[PARENT_ID]

Substitua:

• [FOLDER_ID] é o código da pasta a ser movida;
• [PARENT_ID] é o ID do recurso ou da pasta da organização mãe.

API

A solicitação JSON:

request_json= '{
   destinationParent: "folders/[DESTINATION_FOLDER_ID]"
}'

A solicitação curl Mover pasta:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ${bearer_token} \
-d "$request_json" \
https://cloudresourcemanager.googleapis.com/v3/folders/[DISPLAY_NAME]:move

Substitua:

• [DESTINATION_FOLDER_ID] é o código da pasta para onde você está movendo outra pasta. Por exemplo, 98765;
• [DISPLAY_NAME] é o nome de exibição da pasta que está sendo movida. Por exemplo, "Minha pasta maravilhosa".

A resposta Mover pasta:

{
  "name": "operations/fm.1234567890",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "MOVE"
  }
}

A solicitação curl Receber operação:

curl -H "Authorization: Bearer ${bearer_token}" \
https://cloudresourcemanager.googleapis.com/v3/operations/fm.1234567890

A resposta Receber operação:

{
  "name": "operations/fm.1234567890",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "MOVE"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.Folder",
    "name": "folders/12345",
    "parent": "folders/98765",
    "displayName": "[DISPLAY_NAME]",
    "lifecycleState": "ACTIVE",
    "createTime": "2017-07-19T23:29:26.018Z",
    "updateTime": "2017-07-20T00:54:44.295Z"
  }
}

Como visualizar ou listar pastas e projetos

Para visualizar ou listar pastas, você precisa ter os papéis de Leitor da organização e Leitor de pastas.

Para visualizar ou listar pastas e projetos:

Console

1. No console do Google Cloud, abra a página "Gerenciar recursos".

   Abrir a página "Gerenciar recursos"

2. No seletor de projetos na parte de cima da página, selecione o recurso da sua organização. As pastas precisam ser criadas antes de aparecerem nessa lista.

   Observação: até 4.000 recursos podem ser exibidos no seletor de projetos. Se um recurso que deveria aparecer não estiver aparecendo, acesse a página Gerenciar recursos e filtre a lista usando o nome dele.

3. Selecione qualquer linha na árvore para realizar operações específicas de pasta ou de projeto.

   Observação: o menu de opções (reticências verticais) na coluna direita exibe as opções para operações permitidas.

4. Digite o nome da pasta/código ou do projeto na pesquisa para filtrar a lista.

gcloud

Para conferir detalhes de uma pasta, use o comando resource-manager folders describe.

gcloud resource-manager folders describe FOLDER_ID

Substitua FOLDER_ID pelo ID da pasta que você quer visualizar.

Para listar as pastas filhas de um recurso de organização, use o comando resource-manager folders list.

gcloud resource-manager folders list \
  --organization ORGANIZATION_ID

Substitua ORGANIZATION_ID pelo ID do recurso da organização que contém as pastas filhas que você quer listar.

Para listar as pastas filhas de um recurso de pasta, use o comando resource-manager folders list.

gcloud resource-manager folders list \
  --folder FOLDER_ID

Substitua FOLDER_ID pelo ID do recurso de pasta que você quer consultar.

Para listar os projetos em uma organização ou pasta, use o comando projects list com o argumento filter.

gcloud projects list \
  --filter=" parent.id: 'RESOURCE_ID' "

Substitua RESOURCE_ID pelo ID do recurso de organização ou pasta que contém os projetos filhos que você quer listar.

API

A solicitação curl para receber pastas:

curl -X GET -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${bearer_token}" \
  https://cloudresourcemanager.googleapis.com/v3/[FOLDER_NAME]

Substitua FOLDER_NAME pelo nome da pasta, como folders/123.

A solicitação curl para listar pastas:

curl -X GET -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${bearer_token}" \
  https://cloudresourcemanager.googleapis.com/v3/folders?parent=[PARENT_NAME]

Substitua PARENT_NAME pelo nome do recurso pai em que você está criando a pasta, como organizations/123 ou folders/123.

Como usar o Google Cloud CLI

Os comandos para interagir com a API Folders com a ferramenta de linha de comando gcloud estão disponíveis no grupo de comandos gcloud resource-manager folders.

Criar

Para criar uma nova pasta, use gcloud resource-manager folders create com sinais que definem o nome da pasta e o ID do recurso ou da pasta da organização em que você quer criá-la.

gcloud resource-manager folders create \
  --display-name="Super Fantastic Folder" \
  --organization=2518

Created Folder 245321.

Ver

Para visualizar uma pasta, use gcloud resource-manager folders describe com o código da pasta que você quer visualizar.

gcloud resource-manager folders describe 245321
name: folders/245321
parent: organizations/2518
display_name: Super Fantastic Folder
lifecycle_state: ACTIVE
create_time: <timestamp info …>
update_time: <timestamp info …>

Listar

Para listar as pastas sob outra pasta, use gcloud resource-manager folders list, passando o código da pasta na sinalização --folder. O comando também pode listar as pastas de nível superior em um recurso da organização, usando a flag --organization.

gcloud resource-manager folders list --folder 245321
<table output showing the folders underneath the folder with the specified ID>

gcloud resource-manager folders list --organization 2518
<table output showing folders in this Organization but not in any folder>

Para incluir pastas para as quais a exclusão é solicitada na lista, adicione a flag --show-deleted

gcloud beta resource-manager folders list --folder 245321 --show-deleted
<table output showing all the folders including the delete requested ones underneath the folder with the specified ID>

Observação: no momento, a flag --show-deleted é compatível apenas com as versões Alpha e Beta do comando.

Você pode listar projetos usando o comando gcloud projects list, passando o ID do recurso da pasta pai ou da organização na flag --filter.

gcloud projects list --filter=" parent.id: '245321' "
<table output showing the projects underneath the resource with the specified ID>

Para mais informações sobre como as permissões e os filtros interagem com os comandos de lista, consulte Como listar todos os recursos em sua hierarquia.

Observação: a listagem de projetos e pastas retornará apenas os descendentes diretos do recurso de destino e não mostrará os filhos derivados.

Pesquisar

Para pesquisar pastas que correspondem à consulta especificada, use gcloud alpha resource-manager folders search, transmitindo a condição na flag --query. O escopo da pesquisa é todas as pastas para as quais o usuário tem permissão de visualização.

gcloud alpha resource-manager folders search --query="name:vij*"
<table output showing the folders with names starting from vij eg. vijeta, vijay-folder>

gcloud alpha resource-manager folders search --query="state:DELETE_REQUESTED"
<table output showing folders for which delete has been requested>

Todas as pastas em que o usuário tem permissão de visualização podem ser mostradas usando o comando gcloud folders search.

gcloud folders search
<table output showing all viewable folders>

Observação: o comando de pesquisa está na versão Alfa e pode ser alterado sem aviso prévio.

Atualizar

As pastas podem ser atualizadas com o comando gcloud resource-manager folders update. Atualmente, apenas o campo display_name de uma pasta pode ser atualizado.

gcloud resource-manager folders update \
  --display-name="Mega Incredible Folder" 245321
name: folders/245321
parent: organizations/2518
display_name: Mega Incredible Folder
lifecycle_state: ACTIVE
create_time: <timestamp info …>
update_time: <recent timestamp info …>

Excluir

É possível excluir pastas e cancelar a exclusão delas a partir da linha de comando. Um usuário precisa ter o papel Administrador de pastas ou Editor de pastas para fazer isso. Você só pode excluir pastas vazias.

gcloud resource-manager folders delete 245321
name: folders/245321
parent: organizations/2518
display_name: Mega Incredible Folder
lifecycle_state: DELETE_REQUESTED
create_time: <timestamp info …>
update_time: <recent timestamp info …>

gcloud resource-manager folders undelete 245321
name: folders/245321
parent: organizations/2518
display_name: Mega Incredible Folder
lifecycle_state: ACTIVE
create_time: <timestamp info …>
update_time: <recent timestamp info …>

Mover projeto

Os projetos podem ser criados em pastas e movidos para pastas usando os comandos existentes gcloud projects create e gcloud projects move. As pastas também podem ser movidas usando gcloud resource-manager folders move.

gcloud projects create --folder=245321 fancy-folder-project
project_id: fancy-folder-project
project_number: 905283
parent:
  type: "folder"
  id: 245321
other fields …

gcloud projects move --folder=245321 soon-to-be-fancy-project
project_id: soon-to-be-fancy-project
project_number: 428714
parent:
  type: "folder"
  id: 245321
other fields …

Operações de longa duração

Algumas operações, como a criação de pastas, podem demorar muito tempo. Para facilitar a realização simultânea de várias tarefas, alguns comandos de pasta permitem que você os execute de maneira assíncrona. Esses comandos aceitam uma sinalização --async para ativar o comportamento assíncrono. Assim, eles retornam uma operação de longa duração imediatamente, em vez de esperar que a operação seja concluída. É possível pesquisar essa operação com o comando gcloud beta resource-manager operations describe. Atualmente, apenas os comandos folders create e folders move permitem o uso assíncrono.

gcloud resource-manager folders create \
  --display-name="Awe-Inspiring Async Folder" \
  --organization=2518 \
  --async

name: operations/fc.8572
metadata:
  operation_type: CREATE
  display_name: Awe-Inspiring Async Folder
  destination_parent: organizations/2518
done: false

[wait for some time …]

gcloud beta resource-manager operations describe fc.8572
name: operations/fc.8572
metadata:
  operation_type: CREATE
  display_name: Awe-Inspiring Async Folder
  destination_parent: organizations/2518
done: true
response:
  name: folders/6428
  parent: organizations/2518
  display_name: Awe-Inspiring Async Folder
  lifecycle_state: ACTIVE
  create_time: <recent timestamp info …>
  update_time: <recent timestamp info …>