本页面介绍了如何创建和管理自定义角色。
准备工作
- 阅读了解 IAM 自定义角色,其中介绍了创建自定义角色所需的权限和最佳做法。
- 如果您使用的是
gcloud
命令行实用程序,请确保使用 188.0.0 版或更高版本。要将gcloud
更新为 188.0.0 版,请运行以下命令:gcloud components update --version 188.0.0
查看资源的可用权限
在创建自定义角色之前,您应先了解哪些权限可应用于资源。您可以使用 gcloud
命令行工具、Google Cloud Console 或 Identity and Access Management API,获取可应用于某项资源及其下级资源的所有权限。例如,您可以获取可应用于某组织及其中项目的所有权限。
控制台
在 Cloud Console 中,转到角色页面。
从页面顶部的下拉列表中选择您的项目。
选中与资源的管理员角色对应的复选框,以查看可应用于该资源的所有权限。例如,如果您选择了 Compute Instance Admin 角色,则右侧面板会显示可应用于 Compute Engine 实例的所有权限。
gcloud
使用 gcloud iam list-testable-permissions
命令获取可应用于目标资源的权限列表。返回的权限就是可用于针对此资源及其下任何资源创建自定义角色的权限。
以下示例演示了如何列出项目资源的可测试权限:
gcloud iam list-testable-permissions project-id
project-id
是使用完整资源名称 (//cloudresourcemanager.googleapis.com/projects/project-id
) 格式的项目 ID,例如 //cloudresourcemanager.googleapis.com/projects/my-project-id
。
list-testable-permissions
命令可能会返回数百个结果。若要限制结果的数量,您还可以指定过滤条件表达式。以下是仅显示部分结果的示例:
---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
customRolesSupportLevel: NOT_SUPPORTED
name: appengine.applications.list
onlyInPredefinedRoles: true
stage: GA
---
name: appengine.applications.update
stage: GA
---
name: appengine.instances.delete
stage: GA
---
name: appengine.instances.get
stage: GA
---
请注意,每个权限都会指明是否受自定义角色支持。如需查看受支持和不受支持权限的完整列表,请参阅自定义角色权限支持。
REST
permissions.queryTestablePermissions
方法可列出您可以针对资源测试的每个权限。
在使用下面的请求数据之前,请先进行以下替换:
full-resource-name
:由服务名称和资源路径组成的 URI。如需查看示例,请参阅完整资源名称。page-size
:可选。要包含在响应中的权限的数量。默认值为 100,最大值为 1000。如果权限数大于页面大小,则响应中会包含分页令牌,您可以使用该令牌检索下一页结果。next-page-token
:可选。此方法之前的响应中返回的分页令牌。如果已指定,则可测试权限列表将从上一个响应结束的位置开始。
HTTP 方法和网址:
POST https://iam.googleapis.com/v1/permissions:queryTestablePermissions
请求 JSON 正文:
{ "fullResourceName": "full-resource-name" "pageSize": page-size, "pageToken": "next-page-token" }
如需发送您的请求,请展开以下选项之一:
您应该会收到类似以下内容的 JSON 响应:
{ "permissions": [ { "name": "iam.serviceAccountKeys.create", "stage": "GA" }, { "name": "iam.serviceAccountKeys.delete", "stage": "GA" }, { "name": "iam.serviceAccountKeys.get", "stage": "GA" } ], "nextPageToken": "CgoHBajEfjUDQyABEPaIv5vIiMDTVhgDIhtpYW0uc2VydmljZUFjY291bnRLZXlzLmxpc3Q" }
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。
获取角色元数据
在创建自定义角色之前,您应先获取预定义角色和自定义角色的元数据。角色元数据包括角色 ID 和角色所含的权限。您可以使用 Cloud Console 或 IAM API 查看元数据。
要查看角色元数据,请使用以下方法之一:
控制台
在 Cloud Console 中,转到角色页面。
从页面顶部的下拉列表中选择您的组织或项目。
选中一个或多个角色对应的复选框以查看角色权限。 右侧面板会显示相应角色中所含的权限(如有)。
类型列中的图标表明这是自定义角色
还是预定义角色
如果您想要查找包含特定权限的所有角色,请在“角色”列表顶部的过滤条件框中输入权限名称。
gcloud
使用 gcloud iam roles describe
命令查看预定义角色和自定义角色的元数据。
要查看预定义角色的元数据,请执行以下 gcloud
命令:
gcloud iam roles describe role-id
role-id
是角色的 ID。预定义角色的 ID 中包含 role
前缀,例如 roles/iam.roleViewer
。
以下示例演示了针对预定义角色 roles/iam.roleViewer
执行 describe
命令时的输出结果:
gcloud iam roles describe roles/iam.roleViewer
description: Read access to all custom roles in the project. etag: AA== includedPermissions: - iam.roles.get - iam.roles.list - resourcemanager.projects.get - resourcemanager.projects.getIamPolicy name: roles/iam.roleViewer stage: GA title: Role Viewer
要查看自定义角色的元数据,请执行以下 gcloud
命令之一:
要查看在组织级层创建的自定义角色的元数据,请执行以下命令:
gcloud iam roles describe --organization=organization-id role-id
要查看在项目级层创建的自定义角色的元数据,请执行以下命令:
gcloud iam roles describe --project=project-id role-id
每个占位值的说明如下:
organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。role-id
是角色的 ID,不包括projects/
、organizations/
或roles/
等任何前缀。例如myCompanyAdmin
。
如需了解详情,请参阅 gcloud iam roles describe
的参考文档。
REST
roles.get
方法可获取角色的定义。
在使用下面的请求数据之前,请先进行以下替换:
-
full-role-id
:完整的角色 ID,包括任何organizations/
、projects/
或roles/
前缀。例如organizations/123456789012/roles/myCompanyAdmin
。
HTTP 方法和网址:
GET https://iam.googleapis.com/v1/full-role-id
如需发送您的请求,请展开以下选项之一:
响应中包含角色定义。
{ "name": "projects/my-project/roles/customRole", "title": "My Custom Role", "description": "My custom role description.", "includedPermissions": [ "storage.buckets.get", "storage.buckets.list" ], "etag": "BwWiPg2fmDE=" }
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。
创建自定义角色
您可以在项目或组织级层创建自定义角色。
要创建自定义角色,调用者必须拥有 iam.roles.create
权限。默认情况下,项目或组织的所有者拥有此权限,并可创建和管理自定义角色。
您必须为非所有者的用户(包括组织管理员)分配 Organization Role Administrator 角色或 IAM Role Administrator 角色。
自定义角色的标题、描述和权限名称的总大小不得超过 64 KB。如果您需要创建更大的自定义角色,可以将权限拆分给多个自定义角色。请选择可显示自定义角色之间关系的角色标题,例如 Custom
Admin (1 of 2)
和 Custom Admin (2 of 2)
。
控制台
要从头开始创建新自定义角色,请执行以下操作:
在 Cloud Console 中,转到角色页面。
在页面顶部的下拉列表中,选择要在哪个组织或项目中创建角色。
点击创建角色。
输入角色的名称、标题和说明。
点击添加权限。
选择要包含在角色中的权限,然后点击添加权限。可使用所有服务和所有类型下拉列表,按服务和类型过滤权限并选择权限。
基于现有的精选角色创建自定义角色:
- 在 Cloud Console 中,转到角色页面。
- 选择要在哪个组织或项目中创建角色。
- 选择创建新自定义角色时要依据的基准角色。
- 点击基于所选角色创建角色。
- 输入角色的名称、标题和说明。
- 取消选中要从角色中排除的权限。
- 点击添加权限以包含任何权限。
- 点击创建。
gcloud
使用 gcloud iam roles create
命令创建新的自定义角色。您可以通过以下两种方式使用此命令:
- 提供包含角色定义的 YAML 文件
- 使用标志指定角色定义
创建自定义角色时,您必须使用 --organization=organization-id
或 --project=project-id
标志指定该角色是应用于组织级层还是项目级层。
以下各示例都是在项目级层创建自定义角色。
要使用 YAML 文件创建自定义角色,请执行以下操作:
创建一个 YAML 文件以包含您的自定义角色定义。该文件必须采用以下结构:
title: role-title description: role-description stage: launch-stage includedPermissions: - permission-1 - permission-2
每个占位值的说明如下:
role-title
是角色的易记标题,例如"My Company Admin"
。role-description
是角色的简短说明,例如"My custom role description"
。launch-stage
表示角色在发布生命周期中所处的阶段,例如ALPHA
、BETA
或GA
。permission-1
和permission-2
是要包含在自定义角色中的权限,例如iam.roles.get
。
保存 YAML 文件,然后执行以下命令之一:
要在组织级层创建自定义角色,请执行以下命令:
gcloud iam roles create role-id --organization=organization-id \ --file=yaml-file-path
要在项目级层创建自定义角色,请执行以下命令:
gcloud iam roles create role-id --project=project-id \ --file=yaml-file-path
每个占位值的说明如下:
role-id
是角色的名称,例如myCompanyAdmin
。organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。yaml-file-path
是包含自定义角色定义的 YAML 文件的位置路径。
示例
以下示例 YAML 文件演示了如何创建角色定义:
title: "My Company Admin" description: "My custom role description." stage: "ALPHA" includedPermissions: - iam.roles.get - iam.roles.list
以下示例演示了如何使用 YAML 文件在组织级层创建角色:
gcloud iam roles create myCompanyAdmin --organization=123456789012 \ --file=my-role-definition.yaml
如果成功创建了角色,则该命令的输出类似于以下内容:
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
以下示例演示了如何使用 YAML 文件在项目级层创建角色:
gcloud iam roles create myCompanyAdmin --project=my-project-id \ --file=my-role-definition.yaml
如果成功创建了角色,则该命令的输出类似于以下内容:
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
要使用标志创建自定义角色,请执行以下操作:
执行以下命令之一:
要在组织级层创建自定义角色,请执行以下命令:
gcloud iam roles create role-id --organization=organization-id \ --title=role-title --description=role-description \ --permissions=permissions-list --stage=launch-stage
要在项目级层创建自定义角色,请执行以下命令:
gcloud iam roles create role-id --project=project-id \ --title=role-title --description=role-description \ --permissions=permissions-list --stage=launch-stage
每个占位值的说明如下:
role-id
是角色的名称,例如myCompanyAdmin
。organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。role-title
是角色的易记标题,例如"My Company Admin"
。role-description
是角色的简短说明,例如"My custom role description."
。permissions-list
包含要纳入自定义角色的权限的英文逗号分隔列表。例如:iam.roles.get,iam.roles.list
。launch-stage
表示角色在发布生命周期中所处的阶段,例如ALPHA
、BETA
或GA
。
示例
以下示例演示了如何使用标志在组织级层创建角色:
gcloud iam roles create myCompanyAdmin --organization=123456789012\ --title="My Company Admin" --description="My custom role description." \ --permissions=iam.roles.get,iam.roles.list --stage=ALPHA
如果成功创建了角色,则该命令的输出类似于以下内容:
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
以下示例演示了如何使用标志在项目级层创建角色:
gcloud iam roles create myCompanyAdmin --project=my-project-id \ --title="My Company Admin" --description="My custom role description." \ --permissions=iam.roles.get,iam.roles.list --stage=ALPHA
如果成功创建了角色,则该命令的输出类似于以下内容:
Created role [myCompanyAdmin]. description: My custom role description. etag: BwVkBX0sQD0= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
REST
roles.create
方法可在项目或组织中创建自定义角色。
在使用下面的请求数据之前,请先进行以下替换:
resource-type
:您要管理其自定义角色的资源类型。使用值projects
或organizations
。resource-id
:您要管理其自定义角色的项目 ID 或组织 ID。role-id
:角色的名称,例如myCompanyAdmin
。role-title
:角色的直观易懂的标题。例如My Company Admin
。role-description
:角色的说明。例如"The company admin role allows company admins to access important resources"
。permission-1
和permission-2
:您要在角色中包含的权限。例如storage.objects.update
。launch-stage
:角色的当前发布阶段。此字段可以包含以下值之一:EAP
、ALPHA
、BETA
、GA
、DEPRECATED
或DISABLED
。
HTTP 方法和网址:
POST https://iam.googleapis.com/v1/resource-type/resource-id/roles
请求 JSON 正文:
{ "roleId": "role-id", "role": { "title": "role-title", "description": "role-description", "includedPermissions": [ "permission-1", "permission-2" ], "stage": "launch-stage" } }
如需发送您的请求,请展开以下选项之一:
响应中包含您创建的角色。
{ "name": "projects/myProject/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWox/JbaZw=" }
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。
修改现有自定义角色
读取-修改-写入
通常,我们按照以下模式更新资源的元数据(如自定义角色):先读取其当前状态,接着在本地更新数据,然后发送修改后的数据以进行写入。如果有两个或两个以上的独立过程同时尝试执行该序列,此模式可能会导致冲突。例如,当项目有两位所有者同时尝试对某一角色进行有冲突的更改时,部分更改可能会失败。IAM 可利用自定义角色的 etag
属性解决此问题。该属性用于验证自上次请求以来自定义角色是否发生了更改。当您使用 ETag 值向 IAM 发出请求时,IAM 会将请求中的 ETag 值与自定义角色所关联的现有 ETag 值进行比较。只有在两个 ETag 值一致的情况下,它才会写入相应更改。
要更新某一角色,请先使用 roles.get()
获取角色,再更新角色,然后使用 roles.patch()
写入更新后的角色。只有 roles.get()
中的相应角色包含 etag 值,才能在设置角色时使用 etag 值。
控制台
在 Cloud Console 中,转到角色页面。
在页面顶部的下拉列表中,选择包含您要修改的角色的项目或组织。
点击某个自定义角色。
点击修改角色。
点击添加权限以为角色添加新权限。
取消选中权限以从角色中移除相应权限。
点击更新以保存修改后的角色。
gcloud
使用 gcloud iam roles update
命令更新自定义角色。
您可以通过以下两种方式使用此命令:
- 提供包含已更新角色定义的 YAML 文件
- 使用标志指定更新的角色定义
更新自定义角色时,必须使用 --organization=organization-id
或 --project=project-id
标志指定该角色是应用于组织级层还是项目级层。以下各示例都是在项目级层创建自定义角色。
要使用 YAML 文件更新自定义角色,请执行以下操作:
通过执行以下命令之一获取角色的当前定义:
要获取组织级层自定义角色的定义,请执行以下命令:
gcloud iam roles describe role-id --organization=organization-id
要获取项目级层自定义角色的定义,请执行以下命令:
gcloud iam roles describe role-id --project=project-id
每个占位值的说明如下:
role-id
是要更新的角色的名称,例如myCompanyAdmin
。organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。
describe
命令返回角色的定义并包含用于唯一标识当前角色版本的 etag
值。您应在更新的角色定义中提供 etag
值,以确保任何并发的角色更改都不会被覆盖。
describe
命令返回以下输出:
description: role-description etag: etag-value includedPermissions: - permission-1 - permission-2 name: full-role-id stage: launch-stage title: role-title
每个占位值的说明如下:
role-description
是角色的简短说明,例如"My custom role description"
。etag-value
是当前角色版本的唯一标识符,例如BwVkBkbfr70=
。permission-1
和permission-2
是要包含在自定义角色中的权限,例如iam.roles.get
。full-role-id
是完整的角色 ID,包括任何organizations/
、projects/
或roles/
前缀。例如organizations/123456789012/roles/myCompanyAdmin.
launch-stage
表示角色在发布生命周期中所处的阶段,例如ALPHA
、BETA
或GA
。role-title
是角色的易记标题,例如"My Company Admin"
。
要更新角色,请将输出的角色定义加入 YAML 文件中,或使用输出的 etag
值更新原始 YAML 文件。
请考虑以下示例 YAML 文件,该文件包含针对项目级层角色运行的 describe
命令的输出并添加了两项 Cloud Storage 权限:
description: My custom role description. etag: BwVkBkbfr70= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
保存 YAML 文件,然后执行以下命令之一:
要更新组织级层角色,请执行以下命令:
gcloud iam roles update role-id --organization=organization-id \ --file=yaml-file-path
要更新项目级层角色,请执行以下命令:
gcloud iam roles update role-id --project=project-id \ --file=yaml-file-path
每个占位值的说明如下:
role-id
是要更新的角色的名称,例如myCompanyAdmin
。organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。yaml-file-path
是包含已更新自定义角色定义的 YAML 文件的位置路径。
示例
以下示例演示了如何使用 YAML 文件更新组织级层角色:
gcloud iam roles update myCompanyAdmin --organization=123456789012 \ --file=my-role-definition.yaml
如果成功更新了角色,则该命令的输出类似于以下内容:
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
以下示例演示了如何使用 YAML 文件更新项目级层角色:
gcloud iam roles update myCompanyAdmin --project=my-project-id \ --file=my-role-definition.yaml
如果成功更新了角色,则该命令的输出类似于以下内容:
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
要使用标志更新自定义角色,请执行以下操作:
可使用相应标志更新角色定义的每个部分。
如需查看所有可用标志的列表,请参阅 gcloud iam roles update
主题。
您可以使用以下标志添加或移除权限:
--add-permissions=permissions
:为角色添加一个或多个以英文逗号分隔的权限。--remove-permissions=permissions
:从角色中移除一个或多个以英文逗号分隔的权限。
或者,您只需使用 --permissions=permissions
标志指定新权限,并提供权限的英文逗号分隔列表以替换现有权限列表。
要更新角色定义的其他部分,请执行以下命令之一:
要更新组织级层角色,请执行以下命令:
gcloud iam roles update role-id --organization=organization-id \ --title=role-title --description=role-description \ --stage=launch-stage
要更新项目级层角色,请执行以下命令:
gcloud iam roles update role-id --project=project-id \ --title=role-title --description=role-description \ --stage=launch-stage
每个占位值的说明如下:
role-id
是角色的名称,例如myCompanyAdmin
。organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。role-title
是角色的易记标题,例如"My Company Admin"
。role-description
是角色的简短说明,例如"My custom role description."
。launch-stage
表示角色在发布生命周期中所处的阶段,例如ALPHA
、BETA
或GA
。
示例
以下示例演示了如何使用标志向组织级层角色添加权限:
gcloud iam roles update myCompanyAdmin --organization=123456789012 \ --add-permissions=storage.buckets.get,storage.buckets.list
如果成功更新了角色,则该命令的输出类似于以下内容:
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: organization/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
以下示例演示了如何使用标志向项目级层角色添加权限:
gcloud iam roles update myCompanyAdmin --project=my-project-id \ --add-permissions=storage.buckets.get,storage.buckets.list
如果成功更新了角色,则该命令的输出类似于以下内容:
description: My custom role description. etag: BwVkBwDN0lg= includedPermissions: - iam.roles.get - iam.roles.list - storage.buckets.get - storage.buckets.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
REST
roles.patch
方法可更新项目或组织中的自定义角色。
在使用下面的请求数据之前,请先进行以下替换:
必需:
resource-type
:您要管理其自定义角色的资源类型。使用值projects
或organizations
。resource-id
:您要管理其自定义角色的项目 ID 或组织 ID。-
full-role-id
:完整的角色 ID,包括任何organizations/
、projects/
或roles/
前缀。例如organizations/123456789012/roles/myCompanyAdmin
。
推荐:
etag
:角色版本的标识符。包含此字段可防止覆盖其他角色更改。
可选(定义以下一个或多个值)
role-title
:角色的直观易懂的标题。例如My Company Admin
。role-description
:角色的说明。例如"The company admin role allows company admins to access important resources"
。permission-1
和permission-2
:您要在角色中包含的权限。例如storage.objects.update
。launch-stage
:角色的当前发布阶段。此字段可以包含以下值之一:EAP
、ALPHA
、BETA
、GA
、DEPRECATED
或DISABLED
。
HTTP 方法和网址:
PATCH https://iam.googleapis.com/v1/resource-type/resource-id/roles
请求 JSON 正文:
{ "roleId": "full-role-id", "title": "role-title", "description": "role-description", "includedPermissions": [ "permission-1", "permission-2" ], "stage": "launch-stage", "etag": "etag" }
如需发送您的请求,请展开以下选项之一:
响应中包含简化的角色定义,其中包括角色名称、您更新的字段以及标识角色当前版本的 ETag。
{ "name": "projects/test-project-1000092/roles/myCompanyAdmin", "title": "My Updated Company Admin", "includedPermissions": [ "storage.buckets.get", "storage.buckets.list" ], "stage": "BETA", "etag": "BwWoyDpAxBc=" }
一些预定义角色包含已弃用的权限或不允许在自定义角色中使用的权限。如果基于包含任何已弃用权限或受限权限的预定义角色创建自定义角色,操作则将失败。
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。
停用自定义角色
您可以停用自定义角色。当某个角色被停用后,与该角色相关的所有政策绑定也会随之停用,这意味着向用户授予该角色不会产生任何影响。
控制台
在 Cloud Console 中,转到角色页面。
点击页面顶部的“选择项目”下拉列表。
选择您的组织或项目。
选择自定义角色并点击停用。
gcloud
使用 gcloud iam roles update
命令将该角色的发布阶段设置为 DISABLED
,以停用自定义角色。您可以通过以下两种方式更新现有自定义角色(请参阅修改现有自定义角色部分的 gcloud 标签页):
- 提供包含已更新角色定义的 YAML 文件
- 使用标志指定更新的角色定义
停用现有自定义角色的最简单方法是使用 --stage
标志并将其设置为 DISABLED
。执行以下命令之一:
要停用组织级层角色,请执行以下命令:
gcloud iam roles update role-id --organization=organization-id \ --stage=DISABLED
要停用项目级层角色,请执行以下命令:
gcloud iam roles update role-id --project=project-id \ --stage=DISABLED
每个占位值的说明如下:
role-id
是角色的名称,例如myCompanyAdmin
。organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。
示例
以下示例演示了如何停用组织级层角色:
gcloud iam roles update myCompanyAdmin --organization=123456789012 \ --stage=DISABLED
如果成功更新了角色,则该命令的输出类似于以下内容:
description: My custom role description. etag: BwVkB5NLIQw= includedPermissions: - iam.roles.get - iam.roles.list name: organization/123456789012/roles/myCompanyAdmin stage: DISABLED title: My Company Admin
以下示例演示了如何停用项目级层角色:
gcloud iam roles update myCompanyAdmin --project=my-project-id \ --stage=DISABLED
如果成功更新了角色,则该命令的输出类似于以下内容:
description: My custom role description. etag: BwVkB5NLIQw= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: DISABLED title: My Company Admin
REST
roles.patch
方法可让您将自定义角色的发布阶段更改为 DISABLED
,从而停用该角色。
在使用下面的请求数据之前,请先进行以下替换:
resource-type
:您要管理其自定义角色的资源类型。使用值projects
或organizations
。resource-id
:您要管理其自定义角色的项目 ID 或组织 ID。-
full-role-id
:完整的角色 ID,包括任何organizations/
、projects/
或roles/
前缀。例如organizations/123456789012/roles/myCompanyAdmin
。 etag
:角色版本的标识符。包含此字段可防止覆盖其他角色更改。
HTTP 方法和网址:
PATCH https://iam.googleapis.com/v1/resource/resource-id/roles
请求 JSON 正文:
{ "roleId": "full-role-id", "stage": DISABLED, "etag": "etag" }
如需发送您的请求,请展开以下选项之一:
您应该会收到类似以下内容的 JSON 响应:
{ "name": "projects/test-project-1000092/roles/myCompanyAdmin", "stage": "DISABLED", "etag": "BwWoyDpAxBc=" }
C#
将该角色的 stage
字段更新为 DISABLED
。
Go
将该角色的 stage
字段更新为 DISABLED
。
Python
将该角色的 stage
字段更新为 DISABLED
。
列出角色
您可以列出在项目或组织中创建的所有自定义角色。
控制台
在 Cloud Console 中,转到角色页面。
该页面上会列出您选择的组织或项目的所有自定义角色。
gcloud
使用 gcloud iam roles list
命令列出项目或组织的自定义角色和预定义角色。
要列出自定义角色,请执行以下命令之一:
要列出组织级层自定义角色,请执行以下命令:
gcloud iam roles list --organization=organization-id
要列出项目级层自定义角色,请执行以下命令:
gcloud iam roles list --project=project-id
每个占位值的说明如下:
organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。
此外,还可以指定 --show-deleted
标志以列出已删除的角色。
执行以下 gcloud
命令可列出预定义角色:
gcloud iam roles list
REST
roles.list
方法可列出项目或组织中的所有自定义角色。
在使用下面的请求数据之前,请先进行以下替换:
resource-type
:您要管理其自定义角色的资源类型。使用值projects
或organizations
。resource-id
:您要管理其自定义角色的项目 ID 或组织 ID。role-view
:可选。要为返回的角色包含的信息。要包含角色的权限,请将此字段设置为FULL
。要排除角色的权限,请将此字段设置为BASIC
。默认值为BASIC
。page-size
:可选。要包含在响应中的角色的数量。默认值为 300,最大值为 1000。如果角色数大于页面大小,则响应中会包含分页令牌,您可以使用该令牌检索下一页结果。next-page-token
:可选。此方法之前的响应中返回的分页令牌。如果已指定,则角色列表将从上一个请求结束的位置开始。
HTTP 方法和网址:
GET https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token
如需发送您的请求,请展开以下选项之一:
您应该会收到类似以下内容的 JSON 响应:
{ "roles": [ { "name": "projects/my-project/roles/customRole1", "title": "First Custom Role", "description": "Created on: 2020-06-01", "etag": "BwWiPg2fmDE=" }, { "name": "projects/my-project/roles/customRole2", "title": "Second Custom Role", "description": "Created on: 2020-06-07", "etag": "BwWiuX53Wi0=" } ] }
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。
删除自定义角色
您可以删除项目或组织中的任何自定义角色。
控制台
在 Cloud Console 中,转到角色页面。
选择要删除的角色,然后点击页面顶部的 delete 删除。
gcloud
使用 gcloud iam roles delete
命令删除自定义角色。
该角色将被停用,并且不能用于创建新的 IAM 政策绑定。
要删除自定义角色,请执行以下命令之一:
要删除组织级层自定义角色,请执行以下命令:
gcloud iam roles delete role-id --organization=organization-id
要删除项目级层自定义角色,请执行以下命令:
gcloud iam roles delete role-id --project=project-id
每个占位值的说明如下:
role-id
是角色的名称,例如myCompanyAdmin
。organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。
除非使用 --show-deleted
标志,否则删除的角色将不会包含在 gcloud iam roles list
中。在 list
响应中,删除的角色以 deleted: true
块表示,例如:
--- deleted: true description: My custom role description. etag: BwVkB5NLIQw= name: projects/my-project-id/roles/myCompanyAdmin title: My Company Admin ---
REST
roles.delete
方法可删除项目或组织中的自定义角色。
在使用下面的请求数据之前,请先进行以下替换:
-
full-role-id
:完整的角色 ID,包括任何organizations/
、projects/
或roles/
前缀。例如organizations/123456789012/roles/myCompanyAdmin
。
HTTP 方法和网址:
DELETE https://iam.googleapis.com/v1/full-role-id
如需发送您的请求,请展开以下选项之一:
响应中包含已删除的角色的定义。
{ "name": "projects/my-project/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWiPg2fmDE=", "deleted": true }
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。
删除角色后,其绑定仍会保留,但处于无效状态。您可以在 7 天内恢复删除的角色。在这 7 天内,所删除的角色将在 Cloud Console 中显示为“已删除”,并且以编程方式使用 list
命令也不会显示该角色(除非在请求中设置了 showDeleted
)。
7 天后,系统将安排永久删除该角色。此时,该角色不再计入每个组织 300 个自定义角色或每个项目 300 个自定义角色的限额。
永久性删除过程会持续 30 天。在 30 天的窗口期内,该角色和与之关联的所有绑定都将被永久移除,并且此期间您无法使用相同的角色 ID 创建新角色。
该角色被永久删除之后,也就是自初始删除请求起 37 天后,您方可使用相同的角色 ID 创建新角色。
恢复删除的自定义角色
恢复删除的角色可将角色恢复到其之前的状态。
您只能在 7 天内恢复删除的角色。7 天后,该角色将被永久删除,并且与该角色关联的所有绑定都会被移除。
控制台
在 Cloud Console 中,转到角色页面。
找到要恢复的已删除角色,点击行末尾的更多图标,然后点击恢复删除。
gcloud
使用 gcloud iam roles undelete
命令恢复删除的自定义角色。
要恢复删除的自定义角色,请执行以下命令之一:
要恢复删除的组织级层自定义角色,请执行以下命令:
gcloud iam roles undelete role-id --organization=organization-id
要恢复删除的项目级层自定义角色,请执行以下命令:
gcloud iam roles undelete role-id --project=project-id
每个占位值的说明如下:
role-id
是角色的名称,例如myCompanyAdmin
。organization-id
是组织的数字 ID,例如123456789012
。project-id
是项目的名称,例如my-project-id
。
示例
以下示例演示了如何恢复删除的组织级层自定义角色:
gcloud iam roles undelete myCompanyAdmin --organization=123456789012
如果成功恢复了删除的角色,则该命令的输出类似于以下内容:
description: My custom role description. etag: BwVkCAx9W6w= includedPermissions: - iam.roles.get - iam.roles.list name: organization/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
以下示例演示了如何恢复删除的项目级层自定义角色:
gcloud iam roles undelete myCompanyAdmin --project=my-project-id
如果成功恢复了删除的角色,则该命令的输出类似于以下内容:
description: My custom role description. etag: BwVkCAx9W6w= includedPermissions: - iam.roles.get - iam.roles.list name: projects/my-project-id/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
REST
roles.undelete
方法可恢复项目或组织中已删除的自定义角色。
在使用下面的请求数据之前,请先进行以下替换:
-
full-role-id
:完整的角色 ID,包括任何organizations/
、projects/
或roles/
前缀。例如organizations/123456789012/roles/myCompanyAdmin
。 etag
:角色版本的标识符。包含此字段可防止覆盖其他角色更改。
HTTP 方法和网址:
POST https://iam.googleapis.com/v1/full-role-id:undelete
请求 JSON 正文:
{ "etag": "etag" }
如需发送您的请求,请展开以下选项之一:
响应中包含恢复的已删除角色的定义。
{ "name": "projects/my-project/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWiPg2fmDE=" }
C#
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 IAM C# API 参考文档。
Go
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 IAM Go API 参考文档。
Python
在试用此示例之前,请按照《IAM 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 IAM Python API 参考文档。