创建和管理标记

本指南介绍如何创建和管理标记。标记是一种可附加到 Google Cloud 资源的键值对。您可以将代码用于
根据受支持的资源是否具有
特定标记。

准备工作

如需详细了解标记及其工作原理，请参阅标记概览。

所需权限

您需要的权限取决于您需要执行的操作。

如需获得这些权限，请让您的管理员在资源层次结构的适当级层授予建议的角色。

查看标记

如需查看标记定义和附加到资源的标记，您需要 Tag Viewer 角色 (roles/resourcemanager.tagViewer) 或包含以下权限的其他角色：

所需权限

• resourcemanager.tagKeys.get
• resourcemanager.tagKeys.list
• resourcemanager.tagValues.list
• resourcemanager.tagValues.get
• 相应资源类型的 listTagBindings。例如，用于查看附加到 Compute Engine 实例的标记的 compute.instances.listTagBindings。
• listEffectiveTags

相应的资源类型。例如，compute.instances.listEffectiveTags 用于查看附加到 Compute Engine 实例或由 Compute Engine 实例继承的所有标记。

如需查看组织级层的标记，您需要具有组织资源的 Organization Viewer 角色 (roles/resourcemanager.organizationViewer)。

管理标记

如需创建、更新和删除标记定义，您需要拥有 Tag Administrator 角色 (roles/resourcemanager.tagAdmin) 或具备以下权限的其他角色：

所需权限

• resourcemanager.tagKeys.create
• resourcemanager.tagKeys.update
• resourcemanager.tagKeys.delete
• resourcemanager.tagKeys.list
• resourcemanager.tagKeys.get
• resourcemanager.tagKeys.getIamPolicy
• resourcemanager.tagKeys.setIamPolicy
• resourcemanager.tagValues.create
• resourcemanager.tagValues.update
• resourcemanager.tagValues.delete
• resourcemanager.tagValues.list
• resourcemanager.tagValues.get
• resourcemanager.tagValues.getIamPolicy
• resourcemanager.tagValues.setIamPolicy

如需管理组织级层标记，您需要具有组织资源的 Organization Viewer 角色 (roles/resourcemanager.organizationViewer)。

管理资源上的标记

如需添加和移除附加至资源的标记，您需要对标记值以及您要附加标记值的资源都具有 Tag User 角色 (roles/resourcemanager.tagUser) 或具有同等权限的其他角色。Tag User 角色包含以下权限：

所需权限

• 您要将标记值附加到的资源所需的权限
• 特定于资源的 createTagBinding 权限，例如 Compute Engine 实例的 compute.instances.createTagBinding。
• 特定于资源的 deleteTagBinding 权限，例如 Compute Engine 实例的 compute.instances.deleteTagBinding。
• 标记值所需的权限：
• resourcemanager.tagValueBindings.create
• resourcemanager.tagValueBindings.delete
• 可让您查看项目和标记定义的权限：
• resourcemanager.tagValues.get
• resourcemanager.tagValues.list
• resourcemanager.tagKeys.get
• resourcemanager.tagKeys.list
• resourcemanager.projects.get

创建和定义新标记

标记由键值对组成，并附加到
Google Cloud 层次结构。如需创建新标记，您必须先创建标记键
来描述您要创建的代码例如，您可能希望通过创建一个名为 environment 的键，为资源层次结构中的资源指定生产、测试和开发环境。

然后，您可以创建键可以具有的不同值。如果您创建了名为 environment 的标记键，则可能需要指定有三个可能的环境，然后为每个环境创建一个值：production、development、和 test。

您最多可以在给定组织下创建 1000 个密钥，或者
项目中，您总共可以为每个键创建 1000 个值。

最后，您可以将这些值关联到层次结构中的资源，后者随键值对携带关联。例如，您可以将 test 关联到组织中的多个测试环境文件夹，每个文件夹都将采用 environment: test 键值对。

创建标记

首先，您需要创建一个标记键。

标记键的 shortName 的长度上限为 256 个字符。通过
shortName 的允许字符集包括 UTF-8 编码的 Unicode
除单引号 (')、双引号以外的字符
(")、反斜杠 (\) 和正斜杠
(/).

shortName 创建后便无法更改，而且必须如此设置
在同一个命名空间内是唯一的

控制台

如需创建标记键，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 从页面顶部的范围选择器中，选择
   您要在其中创建标记键的组织或项目。

3. 点击 add 创建。

4. 在标记键框中，输入标记键的显示名称。它会成为标记的命名空间名称的一部分。

5. 在标记键说明框中，输入标记键的说明。

6. 如果要向此键添加标记值，请为您要创建的每个标记值点击 add 添加值。

7. 在标记值框中，输入标记值的显示名。它会成为标记的命名空间名称的一部分。

8. 在标记值说明框中，输入标记值的说明。

9. 添加完标记值后，点击创建标记键。

gcloud

如需创建标记键，请使用 gcloud resource-manager tags keys create 命令：

gcloud resource-manager tags keys create  \
    --parent=

其中：

您应该会看到如下所示的响应：

Creating tag key environment in organization 1234567890...
<blocking wait until creation completes>
name: tagKeys/123456789012
short_name: environment
namespaced_name: 123456789012/environment
parent: organizations/123456789012

Terraform

使用 google_tags_tag_key 资源。

在使用 Terraform 创建代码键之前，请先启用 Cloud Resource Manager API。

以下示例会创建名为 env 和 department 的标记键：

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

1. 启动 Cloud Shell。

2. 设置要在其中应用 Terraform 配置的默认 Google Cloud 项目。

   您只需为每个项目运行一次以下命令，即可在任何目录中运行它。

   export GOOGLE_CLOUD_PROJECT=

   如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

1. 在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本课中，
   因此该文件称为 main.tf。

   mkdir  && cd  && touch main.tf

2. 如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

   将示例代码复制到新创建的 main.tf 中。

   （可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。

3. 查看和修改要应用到您的环境的示例参数。
4. 保存更改。
5. 初始化 Terraform。您只需为每个目录执行一次此操作。

   terraform init

   （可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：

   terraform init -upgrade

应用更改

1. 查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：

   terraform plan

   根据需要更正配置。

2. 通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：

   terraform apply

   等待 Terraform 显示“应用完成！”消息。

3. 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

注意：Terraform 示例通常假定您的 Google Cloud 项目中启用了所需的 API。

API

如需创建标记键，请创建该键的 JSON 表示法。如需详细了解标记键的格式，请参阅 TagKey 参考文档。

然后使用 tagKeys.create 方法：

POST https://cloudresourcemanager.googleapis.com/v3/tagKeys/ -d

请求 JSON 正文：

{
    "parent": ,
    "shortName": ,
    "description": ,
}

其中：

• 是标记键的显示名，例如 environment。

• 是此标记键的父级组织或项目资源的 ID，例如 organizations/123456789012、projects/test-project123 或 projects/234567890123。要了解如何获取您的组织 ID，请参阅
  创建和管理组织。
  如需了解如何获取项目 ID，请参阅创建和管理项目。

• 是键的说明，长度不超过 256 个字符。

创建键后，您可以找到一个名为 namespacedName 的唯一人类可读的显示名称，该名称在其父级资源中具有命名空间，以及一个名为 name 的全局唯一永久 ID。

查看标记键

您可以使用创建时所显示的永久 ID 或命名空间名称来查找特定标记键的信息。

控制台

如需查看已创建的标记，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 从页面顶部的范围选择器中，选择
   组织或项目。

3. 所选组织或项目中的所有标记都会显示在列表中。点击要查看其标记键的代码。

gcloud

如需显示与给定标记键相关的信息，请使用 gcloud resource-manager tags keys describe 命令：

gcloud resource-manager tags keys describe 

是永久 ID 或命名空间型
您希望显示其信息的标记键的名称；例如：
tagKeys/123456789012 或 project-id/environment。

您应该会看到如下所示的响应：

name: tagKeys/123456789012
short_name: environment
namespaced_name: 123456789012/environment
parent: organizations/123456789012

API

如需显示与指定标记键相关的信息，请使用 tagKeys.get 方法：

GET https://cloudresourcemanager.googleapis.com/v3/{name=}

是标记键的永久 ID
要显示的信息；例如：
tagKeys/123456789012。

如需使用标记键的命名空间名称显示与给定标记键相关的信息，请使用 tagKeys.getNamespaced 方法：

GET https://cloudresourcemanager.googleapis.com/v3/tagKeys/namespaced?name={}

是标记的命名空间名称
键，格式为 parentNamespace/tagKeyShortName。

添加标记值

创建标记键后，您就可以为该键添加接受的值。

您的标记值的 shortName 必须满足以下要求：

• shortName 的长度不得超过 256 个字符。

• shortName 必须以字母数字字符开头。

• shortName 可以包含 UTF-8 编码的 Unicode 字符，但单个
  引号 (')、双引号 (")、反斜杠
  (\) 和正斜杠 (/)。

• shortName 一旦创建便无法更改，并且在同一命名空间内必须是唯一的。

控制台

如需创建标记值，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 在页面顶部的范围选择器中，选择要在其下创建代码值的组织或项目。

3. 在标记列表中，点击要添加新值的标记。

4. 点击 add 添加值。

5. 在标记值框中，输入标记值的显示名。它会成为标记的命名空间名称的一部分。

6. 在标记值说明框中，输入标记值的说明。

7. 点击保存。

gcloud

如需创建标记键，请使用 gcloud resource-manager tags values
create 命令。您必须指定创建此值所基于的键：

gcloud resource-manager tags values create  \
    --parent=

其中：

您应该会看到如下所示的响应：

Creating tag value production in tag key 123456789012/environment...
<blocking wait until creation completes>
name: tagValues/7890123456
short_name: production
namespaced_name: 123456789012/environment/production
parent: tagKeys/123456789012

Terraform

使用 google_tags_tag_value 资源。

在使用 Terraform 创建代码值之前，请启用 Cloud Resource Manager API。

以下示例会创建名为 prod 和 sales 的标记值：

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

1. 启动 Cloud Shell。

2. 设置要在其中应用 Terraform 配置的默认 Google Cloud 项目。

   您只需为每个项目运行一次以下命令，即可在任何目录中运行它。

   export GOOGLE_CLOUD_PROJECT=

   如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

1. 在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本课中，
   因此该文件称为 main.tf。

   mkdir  && cd  && touch main.tf

2. 如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

   将示例代码复制到新创建的 main.tf 中。

   （可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。

3. 查看和修改要应用到您的环境的示例参数。
4. 保存更改。
5. 初始化 Terraform。您只需为每个目录执行一次此操作。

   terraform init

   （可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：

   terraform init -upgrade

应用更改

1. 查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：

   terraform plan

   根据需要更正配置。

2. 通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：

   terraform apply

   等待 Terraform 显示“应用完成！”消息。

3. 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

注意：Terraform 示例通常假定您的 Google Cloud 项目中启用了所需的 API。

API

如需创建标记值，请创建该值的 JSON 表示法。如需详细了解标记值的格式，请参阅 TagValue 参考。

然后使用 tagValues.create 方法：

POST https://cloudresourcemanager.googleapis.com/v3/tagValues/ -d

请求 JSON 正文：

{
    "parent": ,
    "shortName": ,
    "description": ,
}

其中：

• 是父标记键的永久 ID，例如 tagKeys/4567890123。

• 是标记值的显示名，例如 environment。

• 是值的描述，
  超过 256 个字符。
  创建值后，您可以找到一个名为 namespacedName 的唯一人类可读的显示名称，该名称在其父级资源中具有命名空间，以及一个名为 name 的全局唯一永久 ID。

检索标记值

您可以使用创建时所显示的永久 ID 或命名空间名称来查找特定标记值的信息。

控制台

如需查看已创建的标记，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 从页面顶部的范围选择器中，选择
   组织或项目。

3. 您在此组织或项目下创建的所有标记都将显示在
   列表。点击您要查看其代码值的代码。

gcloud

如需显示与给定标记值相关的信息，请使用 gcloud resource-manager tags values describe 命令：

gcloud resource-manager tags values describe 

是永久 ID，或者
标记值的命名空间名称；例如：
tagValues/4567890123 或 123456789012/environment/production。

您应该会看到如下所示的响应：

name: tagValues/456789012345
short_name: production
namespaced_name: 123456789012/environment/production
parent: tagKeys/123456789012

API

如需显示与给定标记值相关的信息，请使用 tagValues.get 方法：

GET https://cloudresourcemanager.googleapis.com/v3/{name=}

是代码的永久 ID
value;例如 tagValues/4567890123。

使用命名空间型指定标记值显示与指定标记值相关的信息
请使用
tagValues.getNamespaced 方法配置命名空间：

GET https://cloudresourcemanager.googleapis.com/v3/tagValues/namespaced?name={}

是标记值的命名空间名称，格式为 parentNamespace/tagKeyShortName/tagValueShortName。

使用 Google Cloud CLI 引用标记时，您可以针对标记键和值使用命名空间名称或永久 ID。调用 API（getNamespaced 除外）只应使用永久 ID。如需详细了解标记使用的标识符类型，请参阅标记定义和标识符。

更新现有标记

您可以通过更新与标记关联的键或值来修改现有标记。您可以更新标记说明，但无法更新简称。

控制台

如需更新标记键的说明，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 从页面顶部的范围选择器中选择组织
   或项目中包含您的标记键。

3. 点击要更新的标记键旁边的 more_vert 操作，然后点击查看详情。

4. 点击屏幕顶部附近的说明旁边的 edit 修改。

5. 更新标记键的说明。

6. 点击保存。

gcloud

要修改标记键说明，请使用 gcloud resource-manager tags keys update 命令：

gcloud resource-manager tags keys update  \
    --description=

其中：

您应该会看到如下所示的响应：

name: tagKeys/123456789012
short_name: environment
namespaced_name: 123456789012/environment
description: "new description"
parent: organizations/123456789012

API

如需修改标记键说明，请使用 tagKeys.patch 方法：

PATCH https://cloudresourcemanager.googleapis.com/v3/{tagKey.name=} -d

请求 JSON 正文：

{
    "description": ,
}

其中：

您还可以更改标记值的说明。

控制台

如需更新标记值的说明，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 从页面顶部的范围选择器中选择组织
   或项目中包含您的标记值。

3. 点击要更新的值的标记键旁边的 more_vert 操作，然后点击查看详情。

4. 点击您要更新的标记值旁边的 more_vert 操作，然后点击查看详情。

5. 点击屏幕顶部附近的说明旁边的 edit 修改。

6. 更新标记值的说明。

7. 点击保存。

gcloud

要修改标记值说明，请使用 gcloud resource-manager tags values update 命令：

gcloud resource-manager tags values update  \
    --description=""

其中：

您应该会看到如下所示的响应：

short_name: production
namespaced_name: 123456789012/environment/production
parent: tagKeys/123456789012
description: "new description"

API

如需修改标记键说明，请使用 tagValues.patch 命令：

PATCH https://cloudresourcemanager.googleapis.com/v3/{tagKey.name=} -d

请求 JSON 正文：

{
    "description": ,
}

其中：

列出标记键

您可以使用 Google Cloud 控制台、gcloud CLI 或 API 调用来列出与特定组织或项目资源关联的所有标记键。

控制台

如需查看所有标记，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 从页面顶部的范围选择器中选择组织
   或项目中包含您的代码。

3. 您在此组织或项目下创建的所有标记都将显示在
   列表。

gcloud

如需返回在组织或项目资源下创建的所有标记键的列表，请使用 gcloud resource-manager tags keys list 命令：

gcloud resource-manager tags keys list --parent=

是组织的 ID 或
您要为其查找附加标记键的项目资源。

• 组织或项目 ID 应以如下格式提供：
  organizations/ 或
  projects/;
  例如 organizations/123456789012 和
  projects/test-project123。如需了解如何获取您的组织 ID，
  请参阅
  创建和管理组织。
  如需了解如何获取项目 ID，请参阅
  创建和管理项目。
  您应该会看到如下所示的响应：

NAME                     SHORT_NAME      DESCRIPTION
tagKeys/123456789012     environment     description of tag key

API

如需返回给定资源的所有标记键的列表，请使用 tagKeys.list 方法，并在查询中指定父资源：

GET https://cloudresourcemanager.googleapis.com/v3/tagKeys

{
    "parent": ""
}

是您要查找其关联标记键的组织或项目资源的 ID，例如 organizations/123456789012 和 projects/test-project123。

列出标记值

您可以使用
Google Cloud 控制台或 gcloud CLI，或者通过 API 调用来安装。

控制台

如需查看附加到某个标记键的所有标记值，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 在页面顶部的范围选择器中，选择包含您的代码键的组织或项目。

3. 点击包含要查找的标记值的标记键旁边的 more_vert 操作，然后点击查看详情。

4. 列在此标记键下创建的所有标记值都会显示在列表中。

gcloud

如需返回关联到键的所有标记值的列表，请使用 gcloud resource-manager tags values list 命令：

gcloud resource-manager tags values list --parent=

是永久 ID 或命名空间型
您要查找其附加值的标记键的名称；例如：
tagKeys/123456789012 或 1234567/environment。

您应该会看到如下所示的响应：

NAME                     SHORT_NAME
tagValues/123456789012   production

API

如需返回关联到键的所有标记值的列表，请使用 tagValues.list 方法，并在查询中指定父标记键：

GET https://cloudresourcemanager.googleapis.com/v3/tagValues

{
    "parent": ""
}

是标记键的永久 ID 名称，例如 tagKeys/123456789012。

管理对标记的访问权限

您可以授予用户特定权限，允许其管理标记以及将标记值附加到
管理资源如需与标记相关的角色及其包含的权限的列表，请参阅所需权限。

标记键

如需管理使用标记键的用户的访问权限，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 从页面顶部的范围选择器中选择组织
   或项目（包含您要管理其访问权限的标记键）或项目。

3. 点击要管理其访问权限的标记旁边的复选框。

4. 点击 person 管理访问权限。

5. 如需向主账号添加角色，请点击 person_add 添加主账号。

   1. 在新的主账号文本框中，输入要授予新角色的主账号的电子邮件地址。

   2. 从选择角色下拉菜单中选择角色。如果要添加多个角色，请点击 add 添加其他角色。

   3. 点击保存。

6. 要修改主账号的角色，请点击要修改的主账号旁边的 edit 修改。

   1. 您可以点击角色下拉菜单并选择新角色，以更改在此标记上分配给主账号的任何角色。

   2. 如果要添加更多角色，请点击 add 添加其他角色。

   3. 如需在此标记上删除此主账号的角色，请点击要删除的角色旁边的 delete 删除角色。

   4. 点击保存。

7. 如需删除主账号的角色，请点击要删除的角色旁边的 delete 删除角色。

   1. 点击移除。

标记值

如需管理使用标记值的用户，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 在页面顶部的范围选择器中，选择包含您要管理访问权限的代码键的组织或项目。

3. 点击要管理其访问权限的值所对应的标记键旁边的 more_vert 操作，然后点击查看详细信息。

4. 点击 person 管理访问权限。

5. 如需向主账号添加角色，请点击 person_add 添加主账号。

   1. 在新的主账号文本框中，输入要授予新角色的主账号的电子邮件地址。

   2. 从选择角色下拉菜单中选择角色。如果要添加多个角色，请点击 add 添加其他角色。

   3. 点击保存。

6. 要修改主账号的角色，请点击要修改的主账号旁边的 edit 修改。

   1. 您可以点击角色下拉菜单并选择新角色，以更改在此标记上分配给主账号的任何角色。

   2. 如果要添加更多角色，请点击 add 添加其他角色。

   3. 如需在此标记上删除此主账号的角色，请点击要删除的角色旁边的 delete 删除角色。

   4. 点击保存。

7. 如需删除主账号的角色，请点击要删除的角色旁边的 delete 删除角色。

   1. 点击移除。

将标记关联到资源

创建标记并为该标记和资源授予访问权限后，该标记可以键值对的形式关联到 Google Cloud 资源。对于给定键，只能将一个值关联到资源。例如，如果关联了 environment: development，则不能关联 environment: production 或 environment: test。每个资源最多可以关联 50 个键值对。

通过创建与资源相关联的标记绑定资源，将标记附加到资源
添加到 Google Cloud 资源的值。以下工作流介绍了如何
将标记附加到组织、文件夹或项目资源。如需详细了解
如何将标记附加到其他类型的资源，请参阅相关文档
位于
支持代码的服务。

控制台

要将标记附加到组织、文件夹或项目资源，请执行以下操作：
以下：

1. 在 Google Cloud 控制台中打开管理资源页面。

   打开“管理资源”页面

2. 点击要与标记关联的组织、文件夹或项目。

3. 点击label_important标记。

4. 在标记面板中，点击选择范围。

5. 选择包含您的代码的组织或项目，然后点击打开。

6. 在标记面板中，选择添加标记。

7. 在键字段中，选择要从哪个键附加代码
   列表。您可以通过输入关键字来过滤列表。

8. 在值字段中，从列表中选择要附加的标记的值。您可以通过输入关键字来过滤列表。

9. 如果您想附加更多标签，请点击
   add 添加标签，然后选择
   键和值

10. 点击保存。

11. 在确认对话框中，点击确认以附加标记。

12. 系统会显示一条通知，确认您的代码已更新。新标签会显示在
    管理资源页面上的标记列。

gcloud

如需将标记关联到资源，您必须使用 gcloud resource-manager tags bindings create 命令创建标记绑定资源：

gcloud resource-manager tags bindings create \
--tag-value= \
--parent= \
--location=

其中：

• 是永久 ID，或者
  要附加的标记值的命名空间名称；例如：
  tagValues/4567890123 或
  12345678/environment/production。

• 是资源的完整 ID，包括用于标识资源类型的 API 域名 (//cloudresourcemanager.googleapis.com/)。例如，如需将标记关联到 projects/7890123456，则完整 ID 将为 //cloudresourcemanager.googleapis.com/projects/7890123456。

• 是资源的位置。如果要将标记附加到全球性资源（例如文件夹或项目），则应省略此标志。如需将标记附加到区域级资源（例如 Compute Engine 实例），则必须指定位置，例如 us-central1。

API

如需将标记附加到资源，您必须先创建 JSON 表示法
标记绑定的名称，并且该绑定的永久 ID 或命名空间名称
标记值和资源的永久 ID。如需详细了解标记绑定的格式，请参阅 TagBinding 参考文档。

如果要将标记附加到全球性资源（例如组织），请使用带有全球端点主机名的 tagBindings.create 方法：

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

如需将标记附加到区域级资源（例如 Compute Engine 实例），请使用 tagBindings.create 方法并使用资源所在的区域端点。

POST https://-cloudresourcemanager.googleapis.com/v3/tagBindings

请求 JSON 正文：

{
    "parent": ,
    "tagValue": ,
}

或

{
    "parent": ,
    "tagValueNamespacedName": ,
}

其中：

• 是资源的完整 ID，包括用于标识资源类型的 API 域名 (//cloudresourcemanager.googleapis.com/)。例如，如需将标记关联到 projects/7890123456，则完整 ID 将为 //cloudresourcemanager.googleapis.com/projects/7890123456。

• 是所附加的标记值的永久 ID，例如 tagValues/4567890123。

• 是
  附加的标记值，格式为：
  parentNamespace/tagKeyShortName/tagValueShortName。

您可以获取关联到某个资源的所有标记的列表，包括继承的标记和直接附加的标记。

控制台

要查看附加到资源或由资源继承的所有标记，请执行以下操作：
以下：

1. 在 Google Cloud 控制台中打开管理资源页面。

   打开“管理资源”页面

2. 在资源列表中查找您的组织、文件夹或项目。

3. 附加到资源的标记会显示在标记列下。继承的代码会被标记为lan继承。

gcloud

如需获取直接附加到资源的标记绑定列表，请使用 gcloud resource-manager tags bindings list 命令。如果添加 --effective 标志，您还会返回此资源继承的标记列表。

gcloud resource-manager tags bindings list \
    --parent= \
    --location=

其中：

您应该会看到如下所示的响应：

name: tagBindings/%2F%2Fcloudresourcemanager.googleapis.com%2Fprojects%2F7890123456/tagValues/567890123456
tagValue: tagValues/567890123456
resource: //cloudresourcemanager.googleapis.com/projects/7890123456

如果将 --effective 标志添加到 tags bindings list 命令，则也将返回此资源继承的所有标记的列表。您应该
会收到类似于以下内容的响应：

namespacedTagKey: 961309089256/environment
namespacedTagValue: 961309089256/environment/production
tagKey: tagKeys/417628178507
tagValue: tagValues/247197504380
inherited: true

如果资源上评估的所有标记都直接附加，则 inherited 字段为 false 且被省略。

API

获取直接附加到全球性资源的标记绑定列表，例如
使用
tagBindings.list
方法，在查询中指定父资源：

GET https://cloudresourcemanager.googleapis.com/v3/tagBindings

{
    "parent": ""
}

如需列出附加到区域级资源（例如 Compute Engine 实例）的标记绑定，请使用 tagBindings.list 方法并使用资源所在的区域端点。

GET https://-cloudresourcemanager.googleapis.com/v3/tagBindings

{
    "parent": ""
}

其中：

如果成功，则响应正文应包含 TagBinding 对象的列表。例如：

name: tagBindings/cloudresourcemanager.googleapis.com/projects/7890123456/567890123456
tagValue: tagValues/567890123456
resource: //cloudresourcemanager.googleapis.com/projects/7890123456

从资源分离标记

您可以通过删除标记绑定资源，从资源分离标记。

控制台

要从组织、文件夹或项目资源中分离标记，请执行以下操作：
以下：

1. 在 Google Cloud 控制台中打开管理资源页面。

   打开“管理资源”页面

2. 点击要从中分离标记的组织、文件夹或项目。

3. 点击label_important标记。

4. 在标记面板中，点击要分离的标记旁边的 delete删除项。

5. 点击保存。

6. 在确认对话框中，点击确认以分离标记。

7. 系统会显示一条通知，确认您的代码已更新。更新后的标记列表会显示在管理资源页面上的标记列下。

gcloud

如需删除标记绑定，请使用 gcloud resource-manager tags bindings delete 命令：

gcloud resource-manager tags bindings delete \
--tag-value= \
--parent= \
--location=

其中：

• 是所附加的标记值的永久 ID 或命名空间名称，例如 tagValues/567890123456。

• 是资源的完整 ID。例如 //cloudresourcemanager.googleapis.com/projects/7890123456

• 是资源的位置。如果要删除附加到全球性资源（例如文件夹或项目）的标记绑定，则应省略此标志。如需删除附加到区域级资源（例如 Compute Engine 实例）的标记绑定，则必须指定位置，例如 us-central1。

API

如需删除附加到全球性资源（例如组织）的标记绑定，请使用 tagBindings.delete 方法：

DELETE https://cloudresourcemanager.googleapis.com/v3/{name=}

如需删除附加到区域级资源（例如 Compute Engine 实例）的标记绑定，请使用 tagBindings.delete 方法并使用资源所在的区域端点。

DELETE https://-cloudresourcemanager.googleapis.com/v3/{name=}

其中：

标记保留是您可以创建的一种资源，用于防止标记值被删除。如果标记值有标记保留，用户将无法删除该标记值，除非先删除标记保留。

创建代码保留

您可以使用 gcloud CLI 或 API 手动创建标记保留。

gcloud

如需创建代码保留，请使用 gcloud resource-manager tags holds create gcloud CLI 命令：

  gcloud resource-manager tags holds create  \
  --holder= \
  --location=

其中：

• 是应为其创建此标记保留的标记值的永久 ID 或命名空间名称，例如 tagValues/567890123456。

• 是资源的名称，
  附加的标记值。不得超过 200 个字符。

• 是资源的位置。如果
  您要为全球性资源（例如
  Google Cloud 项目中，则应省略此标志。如果您
  创建标记保全时必须指定区域或可用区级资源
  地理位置；例如：us-central1。

API

要为标记值创建标记保全，您必须先创建 JSON
表示标记保全。此 JSON 引用必须包含对标记值所附加资源的引用。如需详细了解标记保留的格式，请参阅 TagHolds 参考文档。

如果您要为附加到全球性资源（例如组织）的标记值创建标记保留，请使用带有全球端点主机名的 tagHolds.create 方法：

POST https://cloudresourcemanager.googleapis.com/v3/tagValues//tagHolds

如果您要为附加到区域级的标签值创建标记保全，请执行以下操作：
例如 Compute Engine 实例）
将 tagHolds.create 方法替换为您资源所在的区域端点
。

POST https://-cloudresourcemanager.googleapis.com/v3//tagHolds

请求 JSON 正文：

{
    "holder":,
    "origin":
}

其中：

• 是所附加的标记值的永久 ID，例如 tagValues/4567890123。

• 是关联标记值的资源的名称。不得超过 200 个字符。

• 是可选的字符串，表示
  相应请求的来源此字段应包含人类可理解的信息，以便区分各个来源。必须少于 200 个字符。

商品详情标记保留

您可以使用 gcloud CLI 或 API 列出特定标记值下的所有标记保留。

API

要获取某个标记值下的标记保全列表，请使用
tagHolds
GET 方法，指定网址中的父标记值：

GET https://cloudresourcemanager.googleapis.com/v3/{TAGVALUE_NAME}/tagHolds

其中：

• 是永久 ID 或命名空间型
  标记值的名称；例如 tagValues/567890123456。

移除标记保全

您可以使用
gcloud CLI 或 API。

某些资源会向附加到该资源的标记值添加标记保留。如果您将一个标记附加到此类资源，该资源会创建一个标记保全，
将阻止用户删除附加的标记值。

您可以使用 gcloud CLI 或 API 删除标记保留。

gcloud

要删除标记保全，请使用
gcloud resource-manager tags holds delete
gcloud CLI 命令：

  gcloud resource-manager tags holds delete  \
  --location=

其中：

• 是标记的命名空间名称
  使用 list 命令可找到该保全。
  例如：tagValues/1012910994523/tagHolds/d1c8f5e2-2954-43d6-8f46-5f812ab48c37。

• 是资源的位置。如果要删除附加到全球性资源（例如文件夹或项目）的标记值下的标记保留，则应省略此标志。如果要删除通过区域级或可用区级流程创建的标记保留，则必须指定位置，例如：us-central1。

API

如需删除标记值，请使用 tagHolds.delete 方法：

DELETE https://cloudresourcemanager.googleapis.com/v3/{TAGVALUE_NAME}/tagHolds/{TAGHOLD_NAME}

其中：

删除标记

如需删除标记，必须删除其定义的每个组件。首先，您必须删除将此标记关联到层次结构中资源的所有标记绑定。如需了解如何删除标记绑定，请参阅从资源分离标记。

标记已被其他资源使用，或者用户已手动创建标记
保全，您可能需要先移除标记保全和标记绑定，
您可以删除标记值如需了解如何移除标记保全，请参阅
移除代码保全。

一旦您想要删除的标记值没有标记绑定，就可以删除这些值。

控制台

如需删除标记值，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 从页面顶部的范围选择器中选择组织
   或项目中包含您的标记值。

3. 点击包含要删除的标记值的标记键旁边的 more_vert 操作，然后点击查看详情。

4. 在与此标记键关联的标记值列表中，点击要删除的标记值。

5. 点击要删除的标记值旁边的复选框，然后点击 delete 删除值。

6. 点击确认。

gcloud

如需删除标记值，请使用 gcloud resource-manager tag values delete 命令：

gcloud resource-manager tags values delete 

是您要删除的标记值的永久 ID 或命名空间名称，例如 tagValues/567890123456。

API

如需删除标记值，请使用 tagValues.delete 方法：

DELETE https://cloudresourcemanager.googleapis.com/v3/{name=}

是代码的永久 ID
要删除的值例如 tagValues/567890123456。

删除与某个键关联的所有标记值后，您便可以删除该键。

控制台

如需删除代码键，请执行以下操作：

1. 在 Google Cloud 控制台中打开代码页面。

   打开“标记”页面

2. 从页面顶部的范围选择器中选择组织
   或项目中包含您的标记键。

3. 点击要删除的标记键旁边的复选框。

4. 点击 delete 删除标记。

5. 点击确认。

gcloud

如需删除标记键，请使用 gcloud resource-manager tags keys delete 命令：

gcloud resource-manager tags keys delete 

是永久 ID，或者
要删除的标记键的命名空间名称；例如：
tagKeys/123456789012。

API

如需删除标记键，请使用 tagKeys.delete 方法：

DELETE https://cloudresourcemanager.googleapis.com/v3/{name=}

是代码的永久 ID
要删除的键；例如 tagKeys/123456789012。

政策和标记

您可以使用将标记与政策配合使用，以支持标记有条件地强制执行这些政策。您可以将是否存在标记值作为该政策的条件。

例如，您可以根据资源是否具有特定标记，有条件地授予 Identity and Access Management (IAM) 角色。

注意 ：对代码所做的任何更改通常都会在 2 分钟内生效。不过，将
可能需要 7 分钟或更长时间才能在整个系统中完全传播。

您可以使用标记和 Identity and Access Management 条件有条件地为层次结构中的用户授予角色。此过程将使用户无法访问资源，直到附加了与条件政策关联的标记。例如，您可能希望要求开发者先为资源分配成本中心，然后才能使用资源。

1. 创建一个标记，您可以利用该标记将资源与其他内容关联，从而确定资源是否已应用适当的治理。例如，您可以创建键为 costCenter 且值为 0001 和 0002 等等的标记，以将资源与您公司的各种成本中心相关联。

2. 创建组织级自定义角色，以允许用户为您要求标记的资源添加标记。这会将这些权限授予组织中任意位置的指定主账号。

   例如，允许用户为项目添加标记的自定义角色将包括以下权限：

   • resourcemanager.projects.get
   • resourcemanager.hierarchyNodes.create
   • resourcemanager.hierarchyNodes.delete
   • resourcemanager.hierarchyNodes.list

3. 为开发者创建项目时，请为他们分配项目的此自定义角色。

4. 向开发者分配包含权限的任何其他角色，以便他们在该项目中执行所需的任何操作。为用户授予项目的角色时，这些角色应始终有条件地被授予角色，以要求附加 costCenter 标记。

   resource.hasTagKey('123456789012/costCenter')
   

   
   重要提示 ：请确保您授予开发者的任何角色都不会
   包含任何setIamPolicy权限，因为这些权限允许开发者
   修改项目的 IAM 政策，以便移除任何
   你可能实施的有条件限制。

现在，无论何时创建项目，您的开发者都必须为项目附加 costCenter 标记，然后他们才能在被授予 IAM 政策的项目中执行操作。

您可以使用标记并有条件地强制执行组织政策，
集中控制层次结构中的资源。如需了解详情，请参阅设置带有标记的组织政策。

支持的服务

如需查看支持标记的服务列表，请参阅支持标记的服务。

排查已知问题

条件表达式失败

如果您使用 Google Cloud CLI 运行某个 add-iam-policy-binding 命令，并且该资源的 IAM 政策包含该角色的条件角色绑定，gcloud CLI 会提示您选择政策中的某个条件表达式。如果您选择包含英文逗号的条件表达式，该命令将失败。如需解决此问题，请在命令行中使用 --condition 标志指定条件表达式。