Como criar e gerenciar rótulos

Nesta página, apresentamos uma breve visão geral dos rótulos e explicamos como criar e gerenciar marcadores usando a API Resource Manager e o Console do Google Cloud.

O que são rótulos?

Um rótulo é um par de chave-valor que ajuda você a organizar seus recursos do Google Cloud. É possível anexar um rótulo a cada recurso e filtrar os recursos com base nesses rótulos. As informações sobre marcadores são encaminhadas ao sistema de faturamento para que você possa desmembrar as cobranças faturadas por marcador.

Os rótulos podem ser usados como anotações de consulta para recursos, mas não podem ser usados para definir condições em políticas. As tags fornecem uma maneira de permitir ou negar políticas condicionalmente se um recurso tiver uma tag específica. Para mais informações, consulte a Visão geral das tags.

Rótulos e tags

As tags são uma ferramenta separada usada para fornecer controle detalhado sobre as políticas. Para mais informações, consulte a Visão geral de tags.

Usos comuns dos rótulos

Não recomendamos a criação de um grande número de rótulos exclusivos, como carimbos de data/hora ou valores individuais para todas as chamadas de API. Veja alguns casos de uso comum de rótulos:

  • Rótulos de centro de custo ou de equipe: adicione rótulos com base na equipe ou no centro de custo para distinguir os recursos pertencentes a equipes diferentes (por exemplo, team:research e team:analytics). É possível usar esse tipo de rótulo para contabilidade de custos ou em orçamentos.

  • Rótulos de componentes: por exemplo, component:redis, component:frontend, component:ingest e component:dashboard.

  • Rótulos de ambientes ou de estágios: por exemplo, environment:production e environment:test.

  • Rótulos de estado: por exemplo, state:active, state:readytodelete e state:archive.

  • Rótulos de máquina virtual: um rótulo pode ser anexado a uma máquina virtual. As tags de máquina virtual definidas no passado serão exibidas como um rótulo sem um valor.

Requisitos para rótulos

Os rótulos aplicados a um recurso precisam atender aos seguintes requisitos:

  • Cada recurso pode ter vários rótulos, até um máximo de 64.
  • Cada rótulo precisa ser um par de chave-valor.
  • As chaves têm comprimento mínimo de 1 e máximo de 63 caracteres. Além disso, elas não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 caracteres.
  • As chaves e os valores contêm apenas letras minúsculas, caracteres numéricos, sublinhados e traços. Todos os caracteres precisam usar a codificação UTF-8, e os caracteres internacionais são permitidos.
  • A parte principal de um rótulo precisa ser exclusiva em um único recurso. No entanto, é possível usar a mesma chave com vários recursos.
  • As chaves precisam começar com uma letra minúscula ou um caractere internacional.

Esses limites se aplicam à chave e ao valor de cada rótulo e aos recursos individuais do Google Cloud que têm rótulos. Não há limite para a quantidade de rótulos que podem ser aplicados a todos os recursos em um projeto.

Permissões

É possível adicionar ou modificar um rótulo chamando o método projects.projects.patch(). Isso exige a permissão resourcemanager.projects.update.

É possível ver o rótulo de um projeto, chamando o método projects.get(). Isso exige a permissão resourcemanager.projects.get.

Criar marcadores

Console

Para adicionar rótulos a um único projeto:

  1. Abra a página Marcadores no console.

    Abrir a página "Marcadores"

  2. Selecione seu projeto na lista suspensa Sel. projeto.

  3. Para adicionar uma nova entrada de rótulo, clique em + Adicionar rótulo e insira a chave e o valor para cada rótulo que você quer adicionar.

  4. Ao terminar de adicioná-los, clique em Salvar.

Para adicionar marcadores a mais de um projeto ao mesmo tempo:

  1. Abra a página Gerenciar recursos no console.

    Abrir a página "Gerenciar recursos"

  2. Na página Gerenciar recursos, selecione os projetos em que você quer adicionar identificadores.

  3. No painel de informações, na guia Identificadores, clique em + Adicionar rótulo e insira um valor e uma chave para cada identificador que você quer adicionar.

  4. Ao terminar de adicioná-los, clique em Salvar.

Depois de adicionar os marcadores, você poderá filtrar os projetos digitando a chave ou o valor do marcador na caixa de filtro acima da lista de projetos. A caixa de filtro faz a sugestão de chaves e valores para que você possa visualizar os resultados.

REST

Para criar um novo projeto com um identificador, defina o campo labels ao criar o projeto.

Solicitação:

POST https://cloudresourcemanager.googleapis.com/v3/projects

{
 "labels": {
  "color": "red"
 },
 "name": "myproject",
 "projectId": "our-project-123"
}

Saída:


{
 "projectNumber": "333197460082",
 "projectId": "our-project-123",
 "lifecycleState": "ACTIVE",
 "name": "myproject",
 "labels": {
  "color": "red"
 },
 "createTime": "2016-01-12T22:18:28.633Z",
}

Para adicionar marcadores a projetos existentes:

Depois de adicionar identificadores, é possível filtrar projetos com base neles. Para detalhes sobre como usar identificadores para filtrar projetos, consulte Como listar projetos.

Python

Para criar um novo projeto com um identificador, defina o campo labels ao criar o projeto usando o método projects.create().

Para adicionar identificadores a um projeto existente, siga estas etapas:

Depois de adicionar identificadores, é possível filtrar projetos com base neles. Para detalhes sobre como usar identificadores para filtrar projetos, consulte Como listar projetos.

Atualizar rótulos

Console

Para atualizar identificadores de um único projeto:

  1. Abra a página Marcadores no console.

    Abrir a página "Marcadores"

  2. Selecione seu projeto na lista suspensa Sel. projeto.

  3. Atualize os identificadores do projeto:

    1. Para editar um identificador, clique na chave ou no valor que você quer editar e faça as alterações pretendidas.
    2. Para excluir um identificador, mantenha o ponteiro do mouse sobre a chave ou o valor e clique em .
  4. Ao terminar de adicioná-los, clique em Salvar.

Para adicionar identificadores a mais de um projeto ao mesmo tempo:

  1. Abra a página Gerenciar recursos no console.

    Abrir a página "Gerenciar recursos"

  2. Na página Gerenciar recursos, selecione os projetos com os identificadores que você quer atualizar.

  3. No painel de informações, clique na guia Identificadores e atualize os identificadores dos projetos selecionados:

    1. Para editar um identificador, clique na chave ou no valor que você quer editar e faça as alterações pretendidas.
    2. Para excluir um identificador, mantenha o ponteiro do mouse sobre a chave ou o valor e clique em .
  4. Ao terminar de adicioná-los, clique em Salvar.

REST

Para atualizar os identificadores de um projeto, faça o seguinte:

  • Consiga o objeto project usando o método projects.get().

  • Modifique os identificadores que você quer atualizar.

  • Chame o métodoprojects.patch

O exemplo a seguir atualiza o identificador color:blue:

O snippet de código a seguir muda o valor do identificador color de blue para red.

Solicitação:

PATCH https://cloudresourcemanager.googleapis.com/v3/{project.name=PROJECT_NAME}
{
  updateMask=labels
}

Em que PROJECT_NAME é o nome do projeto que você quer atualizar.

Solicitar corpo JSON:

{
    "labels":
      {
        "color": "red"
      }
}

Resposta:

{
    "projects": [
    {
        "name": "projects/123456789012",
        "parent": "folders/123456789012",
        "projectId": "my-project",
        "state": "ACTIVE",
        "displayName": "PROJECT_NAME"
        "createTime": "2013-11-13T20:31:53.308Z"
        "updateTime": "2013-11-13T20:35:42.308Z"
        "etag": "BwWUlZ6XEfY="
        "labels": {
            "color": "red"
        },
    }
    ]
}

Python

Para atualizar os identificadores de um projeto, faça o seguinte:

Serviços compatíveis com rótulos

Os seguintes serviços do Google Cloud são compatíveis com rótulos:

  • AI Platform
  • App Engine (ambientes flexível e padrão)
  • Artifact Registry
  • BigQuery
  • Certificate Authority Service
  • Cloud Bigtable
  • Cloud Composer
  • Cloud Deployment Manager
  • Cloud Functions
  • API Cloud Healthcare
  • Cloud Key Management Service
  • Cloud Run
  • Cloud Spanner
  • Cloud SQL
  • Cloud Storage
  • Cloud Translation
  • Compute Engine
  • Dataflow
  • Dataproc
  • Filestore
  • Google Kubernetes Engine
  • Memorystore
  • Rede
  • Pub/Sub
  • reCAPTCHA Enterprise
  • Resource Manager (somente projetos)
  • API Transcoder
  • Vertex AI