创建和管理自定义角色

本页面介绍了如何创建和管理自定义角色。

准备工作

• 阅读了解 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，获取可应用于某项资源及其下级资源的所有权限。例如，您可以获取可应用于某组织及其中项目的所有权限。

控制台

1. 在 Cloud Console 中，转到角色页面。

   转到“角色”页面

2. 从页面顶部的下拉列表中选择您的项目。

3. 选中与资源的管理员角色对应的复选框，以查看可应用于该资源的所有权限。例如，如果您选择了 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 API

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"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/permissions:queryTestablePermissions

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/permissions:queryTestablePermissions" | Select-Object -Expand Content

API Explorer（浏览器）

复制请求正文并打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

您应该会收到类似以下内容的 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 参考文档。

在 GitHub 上查看 反馈

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static IList<Permission> QueryTestablePermissions(
        string fullResourceName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var request = new QueryTestablePermissionsRequest
        {
            FullResourceName = fullResourceName
        };
        var response = service.Permissions.QueryTestablePermissions(request)
            .Execute();
        foreach (var p in response.Permissions)
        {
            Console.WriteLine(p.Name);
        }
        return response.Permissions;
    }
}

Go

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 IAM Go API 参考文档。

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// queryTestablePermissions lists testable permissions on a resource.
func queryTestablePermissions(w io.Writer, fullResourceName string) ([]*iam.Permission, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	request := &iam.QueryTestablePermissionsRequest{
		FullResourceName: fullResourceName,
	}
	response, err := service.Permissions.QueryTestablePermissions(request).Do()
	if err != nil {
		return nil, fmt.Errorf("Permissions.QueryTestablePermissions: %v", err)
	}
	for _, p := range response.Permissions {
		fmt.Fprintf(w, "Found permissions: %v", p.Name)
	}
	return response.Permissions, nil
}

Python

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 IAM Python API 参考文档。

在 GitHub 上查看 反馈

def query_testable_permissions(resource):
    """Lists valid permissions for a resource."""

    # pylint: disable=no-member
    permissions = service.permissions().queryTestablePermissions(body={
        'fullResourceName': resource
    }).execute()['permissions']
    for p in permissions:
        print(p['name'])

获取角色元数据

在创建自定义角色之前，您应先获取预定义角色和自定义角色的元数据。角色元数据包括角色 ID 和角色所含的权限。您可以使用 Cloud Console 或 IAM API 查看元数据。

要查看角色元数据，请使用以下方法之一：

控制台

1. 在 Cloud Console 中，转到角色页面。

   转到“角色”页面

2. 从页面顶部的下拉列表中选择您的组织或项目。

3. 选中一个或多个角色对应的复选框以查看角色权限。 右侧面板会显示相应角色中所含的权限（如有）。

类型列中的图标表明这是自定义角色（“工厂”图标）还是预定义角色（六边形图标）。

如果您想要查找包含特定权限的所有角色，请在“角色”列表顶部的过滤条件框中输入权限名称。

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 API

roles.get 方法可获取角色的定义。

在使用下面的任何请求数据之前，请先进行以下替换：

• full-role-id：完整的角色 ID，包括任何 organizations/、projects/ 或 roles/ 前缀。例如 organizations/123456789012/roles/myCompanyAdmin。

  注意：如果您不知道完整的角色 ID，请使用 roles.list 方法列出组织或项目中的所有自定义角色，或所有 IAM 预定义角色。完整的角色 ID 位于响应正文的 name 字段中。

HTTP 方法和网址：

GET https://iam.googleapis.com/v1/full-role-id

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

执行以下命令：

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://iam.googleapis.com/v1/full-role-id

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://iam.googleapis.com/v1/full-role-id" | Select-Object -Expand Content

API Explorer（浏览器）

打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行互动以发送请求。填写所有必填字段，然后点击执行。

响应中包含角色定义。

{
  "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 参考文档。

在 GitHub 上查看 反馈

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role GetRole(string name)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = service.Roles.Get(name).Execute();
        Console.WriteLine(role.Name);
        Console.WriteLine(String.Join(", ", role.IncludedPermissions));
        return role;
    }
}

Go

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 IAM Go API 参考文档。

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// getRole gets role metadata.
func getRole(w io.Writer, name string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	role, err := service.Roles.Get(name).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.Get: %v", err)
	}
	fmt.Fprintf(w, "Got role: %v\n", role.Name)
	for _, permission := range role.IncludedPermissions {
		fmt.Fprintf(w, "Got permission: %v\n", permission)
	}
	return role, nil
}

Python

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 IAM Python API 参考文档。

在 GitHub 上查看 反馈

def get_role(name):
    """Gets a role."""

    # pylint: disable=no-member
    role = service.roles().get(name=name).execute()
    print(role['name'])
    for permission in role['includedPermissions']:
        print(permission)

创建自定义角色

您可以在项目或组织级层创建自定义角色。

注意：您不能在文件夹级层定义自定义角色。如果您需要在文件夹中使用自定义角色，请在该文件夹的父级定义自定义角色。

要创建自定义角色，调用者必须拥有 iam.roles.create 权限。默认情况下，项目或组织的所有者拥有此权限，并可创建和管理自定义角色。

您必须为非所有者的用户（包括组织管理员）分配 Organization Role Administrator 角色或 IAM Role Administrator 角色。

自定义角色的标题、描述和权限名称的总大小不得超过 64 KB。如果您需要创建更大的自定义角色，可以将权限拆分给多个自定义角色。请选择可显示自定义角色之间关系的角色标题，例如 Custom Admin (1 of 2) 和 Custom Admin (2 of 2)。

控制台

要从头开始创建新自定义角色，请执行以下操作：

1. 在 Cloud Console 中，转到角色页面。

   转到“角色”页面

2. 在页面顶部的下拉列表中，选择要在哪个组织或项目中创建角色。

3. 点击创建角色。

4. 输入角色的名称、标题和说明。

5. 点击添加权限。

6. 选择要包含在角色中的权限，然后点击添加权限。可使用所有服务和所有类型下拉列表，按服务和类型过滤权限并选择权限。

基于现有的精选角色创建自定义角色：

1. 在 Cloud Console 中，转到角色页面。

   转到“角色”页面

2. 选择要在哪个组织或项目中创建角色。
3. 选择创建新自定义角色时要依据的基准角色。
4. 点击基于所选角色创建角色。
5. 输入角色的名称、标题和说明。
6. 取消选中要从角色中排除的权限。
7. 点击添加权限以包含任何权限。
8. 点击创建。

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 API

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
  }
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/resource-type/resource-id/roles

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/resource-type/resource-id/roles" | Select-Object -Expand Content

API Explorer（浏览器）

复制请求正文并打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

响应中包含您创建的角色。

{
  "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 参考文档。

在 GitHub 上查看 反馈

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role CreateRole(string name, string projectId, string title,
        string description, IList<string> permissions, string stage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = new Role
        {
            Title = title,
            Description = description,
            IncludedPermissions = permissions,
            Stage = stage
        };
        var request = new CreateRoleRequest
        {
            Role = role,
            RoleId = name
        };
        role = service.Projects.Roles.Create(request,
            "projects/" + projectId).Execute();
        Console.WriteLine("Created role: " + role.Name);
        return role;
    }
}

Go

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 IAM Go API 参考文档。

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// createRole creates a custom role.
func createRole(w io.Writer, projectID, name, title, description, stage string, permissions []string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	request := &iam.CreateRoleRequest{
		Role: &iam.Role{
			Title:               title,
			Description:         description,
			IncludedPermissions: permissions,
			Stage:               stage,
		},
		RoleId: name,
	}
	role, err := service.Projects.Roles.Create("projects/"+projectID, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Create: %v", err)
	}
	fmt.Fprintf(w, "Created role: %v", role.Name)
	return role, nil
}

Python

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 IAM Python API 参考文档。

在 GitHub 上查看 反馈

def create_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().create(
        parent='projects/' + project,
        body={
            'roleId': name,
            'role': {
                'title': title,
                'description': description,
                'includedPermissions': permissions,
                'stage': stage
            }
        }).execute()

    print('Created role: ' + role['name'])
    return role

修改现有自定义角色

读取-修改-写入

通常，我们按照以下模式更新资源的元数据（如自定义角色）：先读取其当前状态，接着在本地更新数据，然后发送修改后的数据以进行写入。如果有两个或两个以上的独立过程同时尝试执行该序列，此模式可能会导致冲突。例如，当项目有两位所有者同时尝试对某一角色进行有冲突的更改时，部分更改可能会失败。IAM 可利用自定义角色的 etag 属性解决此问题。该属性用于验证自上次请求以来自定义角色是否发生了更改。当您使用 ETag 值向 IAM 发出请求时，IAM 会将请求中的 ETag 值与自定义角色所关联的现有 ETag 值进行比较。只有在两个 ETag 值一致的情况下，它才会写入相应更改。

要更新某一角色，请先使用 roles.get() 获取角色，再更新角色，然后使用 roles.patch() 写入更新后的角色。只有 roles.get() 中的相应角色包含 etag 值，才能在设置角色时使用 etag 值。

注意：如果通过添加或移除 resourcemanager.organizations.get、resourcemanager.folders.get 和 resourcemanager.projects.get 当中的任何权限来修改自定义角色，则对自定义角色所做的更改最多可能需要 24 个小时才会对 organizations.search 和 folders.search Cloud Resource Manager API 生效。此外，如果 API 调用未提供指定父级类型和 ID 的过滤条件，API projects.list 也会受到这种延迟的影响。发生这种延迟的原因是，这些权限涉及搜索功能，可能最多需要 24 个小时才能重建搜索索引。

控制台

1. 在 Cloud Console 中，转到角色页面。

   转到“角色”页面

2. 在页面顶部的下拉列表中，选择包含您要修改的角色的项目或组织。

3. 点击某个自定义角色。

4. 点击修改角色。

5. 点击添加权限以为角色添加新权限。

6. 取消选中权限以从角色中移除相应权限。

7. 点击更新以保存修改后的角色。

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 API

roles.patch 方法可更新项目或组织中的自定义角色。

在使用下面的任何请求数据之前，请先进行以下替换：

必需：

• resource-type：您要列出其自定义角色的资源类型。使用值 projects 或 organizations。
• resource-id：您要列出其自定义角色的项目 ID 或组织 ID。

• full-role-id：完整的角色 ID，包括任何 organizations/、projects/ 或 roles/ 前缀。例如 organizations/123456789012/roles/myCompanyAdmin。

  注意：如果您不知道完整的角色 ID，请使用 roles.list 方法列出组织或项目中的所有自定义角色，或所有 IAM 预定义角色。完整的角色 ID 位于响应正文的 name 字段中。

推荐：

• 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"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/resource-type/resource-id/roles

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method PATCH `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/resource-type/resource-id/roles" | Select-Object -Expand Content

API Explorer（浏览器）

复制请求正文并打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

响应中包含简化的角色定义，其中包括角色名称、您更新的字段以及标识角色当前版本的 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 参考文档。

在 GitHub 上查看 反馈

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role EditRole(string name, string projectId, string newTitle,
        string newDescription, IList<string> newPermissions, string newStage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });
        // First, get a Role using List() or Get().
        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Get(resource).Execute();
        // Then you can update its fields.
        role.Title = newTitle;
        role.Description = newDescription;
        role.IncludedPermissions = newPermissions;
        role.Stage = newStage;
        role = service.Projects.Roles.Patch(role, resource).Execute();
        Console.WriteLine("Updated role: " + role.Name);
        return role;
    }
}

Go

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 IAM Go API 参考文档。

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// editRole modifies a custom role.
func editRole(w io.Writer, projectID, name, newTitle, newDescription, newStage string, newPermissions []string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	role, err := service.Projects.Roles.Get(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Get: %v", err)
	}
	role.Title = newTitle
	role.Description = newDescription
	role.IncludedPermissions = newPermissions
	role.Stage = newStage
	role, err = service.Projects.Roles.Patch(resource, role).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Patch: %v", err)
	}
	fmt.Fprintf(w, "Updated role: %v", role.Name)
	return role, nil
}

Python

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 IAM Python API 参考文档。

在 GitHub 上查看 反馈

def edit_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'title': title,
            'description': description,
            'includedPermissions': permissions,
            'stage': stage
        }).execute()

    print('Updated role: ' + role['name'])
    return role

停用自定义角色

您可以停用自定义角色。当某个角色被停用后，与该角色相关的所有政策绑定也会随之停用，这意味着系统不会授予该角色所含的任何权限，即使您为某个用户授予了该角色也是如此。

控制台

1. 在 Cloud Console 中，转到角色页面。

   转到“角色”页面

2. 点击页面顶部的“选择项目”下拉列表。

3. 选择您的组织或项目。

4. 选择自定义角色并点击停用。

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 API

通过 roles.patch 方法，您可以将自定义角色的发布阶段更改为 DISABLED，从而停用角色。

在使用下面的任何请求数据之前，请先进行以下替换：

• resource-type：您要列出其自定义角色的资源类型。使用值 projects 或 organizations。
• resource-id：您要列出其自定义角色的项目 ID 或组织 ID。

• full-role-id：完整的角色 ID，包括任何 organizations/、projects/ 或 roles/ 前缀。例如 organizations/123456789012/roles/myCompanyAdmin。

  注意：如果您不知道完整的角色 ID，请使用 roles.list 方法列出组织或项目中的所有自定义角色，或所有 IAM 预定义角色。完整的角色 ID 位于响应正文的 name 字段中。
• etag：角色版本的标识符。添加此字段可防止对角色进行并发更改。

HTTP 方法和网址：

PATCH https://iam.googleapis.com/v1/resource/resource-id/roles

请求 JSON 正文：

{
  "roleId": "full-role-id",
  "stage": DISABLED,
  "etag": "etag"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/resource/resource-id/roles

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method PATCH `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/resource/resource-id/roles" | Select-Object -Expand Content

API Explorer（浏览器）

复制请求正文并打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

您应该会收到类似以下内容的 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 API

roles.list 方法可列出项目或组织中的所有自定义角色。

在使用下面的任何请求数据之前，请先进行以下替换：

• resource-type：您要列出其自定义角色的资源类型。使用值 projects 或 organizations。
• resource-id：您要列出其自定义角色的项目 ID 或组织 ID。
• role-view：可选。要为返回的角色包含的信息。要包含角色的权限，请将此字段设置为 FULL。要排除角色的权限，请将此字段设置为 BASIC。默认值为 BASIC。
• page-size：可选。要包含在响应中的角色的数量。默认值为 300，最大值为 1000。如果角色数大于页面大小，则响应中会包含分页令牌，您可以使用该令牌检索下一页结果。
• next-page-token：可选。此方法之前的响应中返回的分页令牌。如果已指定，则角色列表将从上一个请求结束的位置开始。

注意：要列出所有预定义的 IAM 角色，请省略 resource-type 和 resource-id 字段。例如：GET https://iam.googleapis.com/v1/roles。

HTTP 方法和网址：

GET https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

执行以下命令：

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token" | Select-Object -Expand Content

API Explorer（浏览器）

打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行互动以发送请求。填写所有必填字段，然后点击执行。

您应该会收到类似以下内容的 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 参考文档。

在 GitHub 上查看 反馈

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static IList<Role> ListRoles(string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var response = service.Projects.Roles.List("projects/" + projectId)
            .Execute();
        foreach (var role in response.Roles)
        {
            Console.WriteLine(role.Name);
        }
        return response.Roles;
    }
}

Go

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 IAM Go API 参考文档。

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// listRoles lists a project's roles.
func listRoles(w io.Writer, projectID string) ([]*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	response, err := service.Projects.Roles.List("projects/" + projectID).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.List: %v", err)
	}
	for _, role := range response.Roles {
		fmt.Fprintf(w, "Listing role: %v\n", role.Name)
	}
	return response.Roles, nil
}

Python

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 IAM Python API 参考文档。

在 GitHub 上查看 反馈

def list_roles(project_id):
    """Lists roles."""

    # pylint: disable=no-member
    roles = service.roles().list(
        parent='projects/' + project_id).execute()['roles']
    for role in roles:
        print(role['name'])

删除自定义角色

您可以删除项目或组织中的任何自定义角色。

重要提示：已删除的角色处于暂停状态，无法用于创建新的 IAM 政策绑定。包含已删除角色的现有绑定将不再有效。

控制台

1. 在 Cloud Console 中，转到角色页面。

   转到“角色”页面

2. 选择要删除的角色，然后点击页面顶部的 删除。

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 API

roles.delete 方法可删除项目或组织中的自定义角色。

在使用下面的任何请求数据之前，请先进行以下替换：

• full-role-id：完整的角色 ID，包括任何 organizations/、projects/ 或 roles/ 前缀。例如 organizations/123456789012/roles/myCompanyAdmin。

  注意：如果您不知道完整的角色 ID，请使用 roles.list 方法列出组织或项目中的所有自定义角色，或所有 IAM 预定义角色。完整的角色 ID 位于响应正文的 name 字段中。

HTTP 方法和网址：

DELETE https://iam.googleapis.com/v1/full-role-id

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

执行以下命令：

curl -X DELETE \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://iam.googleapis.com/v1/full-role-id

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method DELETE `
  -Headers $headers `
  -Uri "https://iam.googleapis.com/v1/full-role-id" | Select-Object -Expand Content

API Explorer（浏览器）

打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行互动以发送请求。填写所有必填字段，然后点击执行。

响应中包含已删除的角色的定义。

{
  "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 参考文档。

在 GitHub 上查看 反馈

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static void DeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        service.Projects.Roles.Delete(
            $"projects/{projectId}/roles/{name}").Execute();
        Console.WriteLine("Deleted role: " + name);
    }
}

Go

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 IAM Go API 参考文档。

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// deleteRole deletes a custom role.
func deleteRole(w io.Writer, projectID, name string) error {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return fmt.Errorf("iam.NewService: %v", err)
	}

	_, err = service.Projects.Roles.Delete("projects/" + projectID + "/roles/" + name).Do()
	if err != nil {
		return fmt.Errorf("Projects.Roles.Delete: %v", err)
	}
	fmt.Fprintf(w, "Deleted role: %v", name)
	return nil
}

Python

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 IAM Python API 参考文档。

在 GitHub 上查看 反馈

def delete_role(name, project):
    """Deletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().delete(
        name='projects/' + project + '/roles/' + name).execute()

    print('Deleted role: ' + name)
    return role

删除角色后，其绑定仍会保留，但处于无效状态。您可以在 7 天内恢复删除的角色。在这 7 天内，所删除的角色将在 Cloud Console 中显示为“已删除”，并且以编程方式使用 list 命令也不会显示该角色（除非在请求中设置了 showDeleted）。

7 天后，系统将安排永久删除该角色。此时，该角色不再计入每个组织 300 个自定义角色或每个项目 300 个自定义角色的限额。

注意：在项目中创建的自定义角色不会计入您组织的自定义角色限额。

永久性删除过程会持续 30 天。在 30 天的窗口期内，该角色和与之关联的所有绑定都将被永久移除，并且此期间您无法使用相同的角色 ID 创建新角色。

该角色被永久删除之后，也就是自初始删除请求起 37 天后，您方可使用相同的角色 ID 创建新角色。

恢复删除的自定义角色

恢复删除的角色可将角色恢复到其之前的状态。

您只能在 7 天内恢复删除的角色。7 天后，系统会永久删除相应角色，并移除与该角色关联的所有绑定。

控制台

1. 在 Cloud Console 中，转到角色页面。

   转到“角色”页面

2. 找到要恢复的已删除角色，点击行末尾的“更多”图标，然后点击恢复删除。

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 API

roles.undelete 方法可恢复项目或组织中已删除的自定义角色。

在使用下面的任何请求数据之前，请先进行以下替换：

• full-role-id：完整的角色 ID，包括任何 organizations/、projects/ 或 roles/ 前缀。例如 organizations/123456789012/roles/myCompanyAdmin。

  注意：如果您不知道完整的角色 ID，请使用 roles.list 方法列出组织或项目中的所有自定义角色，或所有 IAM 预定义角色。完整的角色 ID 位于响应正文的 name 字段中。
• etag：角色版本的标识符。添加此字段可防止对角色进行并发更改。

HTTP 方法和网址：

POST https://iam.googleapis.com/v1/full-role-id:undelete

请求 JSON 正文：

{
  "etag": "etag"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1/full-role-id:undelete

PowerShell (Windows)

注意：请确保已将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号私钥文件路径。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1/full-role-id:undelete" | Select-Object -Expand Content

API Explorer（浏览器）

复制请求正文并打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

响应中包含恢复的已删除角色的定义。

{
  "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 参考文档。

在 GitHub 上查看 反馈

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role UndeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Undelete(
            new UndeleteRoleRequest(), resource).Execute();
        Console.WriteLine("Undeleted role: " + role.Name);
        return role;
    }
}

Go

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 IAM Go API 参考文档。

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// undeleteRole restores a deleted custom role.
func undeleteRole(w io.Writer, projectID, name string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	request := &iam.UndeleteRoleRequest{}
	role, err := service.Projects.Roles.Undelete(resource, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Undelete: %v", err)
	}
	fmt.Fprintf(w, "Undeleted role: %v", role.Name)
	return role, nil
}

Python

在试用此示例之前，请按照《IAM 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 IAM Python API 参考文档。

在 GitHub 上查看 反馈

def undelete_role(name, project):
    """Undeletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'stage': 'DISABLED'
        }).execute()

    print('Disabled role: ' + role['name'])
    return role

后续步骤

• 了解如何向成员授予角色。
• 了解条件角色授予，该机制只有在满足特定条件的情况下才会授予角色。