创建和管理自定义角色

本页面介绍如何创建和管理 Identity and Access Management (IAM) 自定义角色。管理角色的操作包括修改、停用、列出、删除和取消删除角色。

准备工作

启用 IAM API。
启用 API
了解 Google Cloud 资源层次结构。
阅读了解 IAM 自定义角色。

所需的角色

如需获得创建和管理自定义角色所需的权限，请让管理员向您授予以下 IAM 角色：

要管理其角色的项目的 Role Administrator (roles/iam.roleAdmin)（如需管理项目的角色）
要管理其角色的组织的 Organization Role Administrator (roles/iam.organizationRoleAdmin)（如需管理组织的角色）

如需详细了解如何授予角色，请参阅管理访问权限。

查看项目、文件夹和组织的可用权限

您可以为整个组织或该组织中的特定项目创建自定义角色。自定义角色可用的权限取决于您创建该角色的位置。例如，如果有某项权限只能在组织级层使用，那么您便无法在项目级层自定义角色中添加该权限。

如需检查组织级层和项目级自定义角色可以使用哪些权限，您可以使用 gcloud CLI 或 Identity and Access Management API，列出特定组织或项目中可用的权限。例如，您可以获取可用于在项目中创建的自定义角色的所有权限。

某些权限可能对您不可见或不可用于自定义角色，即使这些权限在自定义角色中受支持也是如此。例如，如果您尚未为服务启用 API，则可能无法在自定义角色中使用某项权限。

如需详细了解可以添加到自定义角色的权限，请参阅支持的权限。

gcloud CLI

使用 gcloud iam list-testable-permissions 命令获取特定项目或组织中自定义角色可用的权限列表。响应会列出您可以在该项目或组织的自定义角色中使用的权限。

要列出项目或组织的自定义角色中可用的权限，请运行此命令：

gcloud iam list-testable-permissions full-resource-name \
    --filter="customRolesSupportLevel!=NOT_SUPPORTED"

将 full-resource-name 替换为以下某个值：

项目：//cloudresourcemanager.googleapis.com/projects/project-id（例如 //cloudresourcemanager.googleapis.com/projects/my-project-id）
组织：//cloudresourcemanager.googleapis.com/organizations/numeric-id（例如 //cloudresourcemanager.googleapis.com/organizations/123456789012）

结果会指明自定义角色是否支持每个权限。没有 customRolesSupportLevel 字段的权限完全受支持。

list-testable-permissions 命令可能会返回数百个结果。以下部分示例显示了每个结果的格式：

---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
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"
}

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

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户帐号通过执行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以执行 gcloud auth list 来检查当前活跃的帐号。

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

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

PowerShell (Windows)

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

$cred = gcloud auth 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 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

响应包含权限列表。

注意：没有 customRolesSupportLevel 字段的权限在自定义角色中完全受支持。

{
  "permissions": [
    {
      "name": "iam.serviceAccountKeys.create",
      "stage": "GA"
    },
    {
      "name": "iam.serviceAccountKeys.delete",
      "stage": "GA"
    },
    {
      "name": "iam.serviceAccountKeys.get",
      "stage": "GA"
    }
  ],
  "nextPageToken": "CgoHBajEfjUDQyABEPaIv5vIiMDTVhgDIhtpYW0uc2VydmljZUFjY291bnRLZXlzLmxpc3Q"
}

C++

如需了解如何安装和使用 IAM 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 IAM C++ API 参考文档。

在 GitHub 上查看反馈

namespace iam = ::google::cloud::iam;
[](std::string const& resource) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::QueryTestablePermissionsRequest request;
  request.set_full_resource_name(resource);
  int count = 0;
  for (auto& permission : client.QueryTestablePermissions(request)) {
    if (!permission) throw std::move(permission).status();
    std::cout << "Permission successfully retrieved: " << permission->name()
              << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No testable permissions found in resource: " << resource
              << "\n";
  }
}

C#

如需了解如何安装和使用 IAM 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 和角色所含的权限。您可以使用 Google Cloud 控制台或 IAM API 查看元数据。

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

控制台

在 Google Cloud 控制台中，转到角色页面。

转到“角色”页面
从页面顶部的下拉列表中选择您的组织或项目。
选中一个或多个角色对应的复选框以查看角色权限。右侧面板会显示相应角色中所含的权限（如有）。

类型列中的图标表明这是自定义角色还是预定义角色

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

gcloud CLI

使用 gcloud iam roles describe 命令查看预定义角色和自定义角色的元数据。

要查看预定义角色的元数据，请执行以下命令：

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 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 方法可获取角色的定义。

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

role-name：完整的角色名称，包括任何 organizations/、projects/ 或 roles/ 前缀。例如 organizations/123456789012/roles/myCompanyAdmin。

HTTP 方法和网址：

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

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

curl（Linux、macOS 或 Cloud Shell）

执行以下命令：

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

PowerShell (Windows)

执行以下命令：

$cred = gcloud auth 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 IAM C++ API 参考文档。

在 GitHub 上查看反馈

namespace iam = ::google::cloud::iam;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::GetRoleRequest request;
  request.set_name(name);
  auto response = client.GetRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully retrieved: " << response->DebugString()
            << "\n";
}

C#

如需了解如何安装和使用 IAM 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 权限。项目级层自定义角色可以包含任何受支持的权限，但只能在组织或文件夹级层使用的权限除外，例如 resourcemanager.organizations.get。如果您尝试将这类权限添加到项目级层自定义角色，则会收到错误消息：

控制台

系统会显示以下警告消息：“不适用于项目级层自定义角色”。系统会从已包含权限列表中自动取消选择该权限，您可以继续创建此角色。

gcloud

系统会返回以下错误消息：INVALID_ARGUMENT: Permission PERMISSION is not valid。除非您先从角色定义中移除该权限并重试此操作，否则系统将不会创建该自定义角色。

REST API

系统会返回以下错误消息：Permission PERMISSION is not valid，以及 HTTP 400 错误代码和 INVALID_ARGUMENT 状态。除非您先从角色定义中移除该权限并重试此操作，否则系统将不会创建该自定义角色。

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

每个自定义角色都可以具有发布阶段。大部分发布阶段都是参考信息，可帮助您跟踪每个角色是否已准备好投入广泛使用。此外，您还可以借助 DISABLED 发布阶段停用自定义角色。如需详细了解发布阶段，请参阅测试和部署。

控制台

一些预定义角色包含已弃用的权限或不允许在自定义角色中使用的权限。如果您尝试基于其中一个预定义角色创建自定义角色，则自定义角色将忽略已弃用的权限和受限的权限。

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

在 Google Cloud 控制台中，转到角色页面。

转到“角色”页面
在页面顶部的下拉列表中，选择要在哪个组织或项目中创建角色。
点击创建角色。
输入角色的名称、标题、说明和角色发布阶段。角色创建后，角色名称便无法更改。
点击添加权限。
选择要包含在角色中的权限，然后点击添加权限。可使用所有服务和所有类型下拉列表，按服务和类型过滤权限并选择权限。

基于现有预定义角色创建自定义角色：

在 Google Cloud 控制台中，转到角色页面。
转到“角色”页面
选择要在哪个组织或项目中创建角色。
选择创建新自定义角色时要依据的基准角色。
点击基于所选角色创建角色。
输入角色的名称、标题、说明和角色发布阶段。角色创建后，角色名称便无法更改。
取消选中要从角色中排除的权限。
点击添加权限以包含任何权限。
点击创建。

gcloud CLI

使用 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。项目 ID 是字母数字字符串，例如 my-project。组织 ID 是数字，例如 123456789012。
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）

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth 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)

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

$cred = gcloud auth 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（浏览器）

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

{
  "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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 IAM C++ API 参考文档。

在 GitHub 上查看反馈

namespace iam = ::google::cloud::iam;
[](std::string const& parent, std::string const& role_id,
   std::vector<std::string> const& included_permissions) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::CreateRoleRequest request;
  request.set_parent("projects/" + parent);
  request.set_role_id(role_id);
  google::iam::admin::v1::Role role;
  role.set_stage(google::iam::admin::v1::Role::GA);
  for (auto const& permission : included_permissions) {
    *role.add_included_permissions() = permission;
  }
  *request.mutable_role() = role;
  auto response = client.CreateRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully created: " << response->DebugString()
            << "\n";
}

C#

如需了解如何安装和使用 IAM 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 值。

控制台

在 Google Cloud 控制台中，转到角色页面。

转到“角色”页面
在页面顶部的下拉列表中，选择包含您要修改的角色的项目或组织。
点击自定义角色。
点击修改角色。
如需更新角色的元数据，请修改角色的标题、说明或角色发布阶段。
如需更新角色的权限，请执行以下操作：
1. 点击添加权限以为角色添加新权限。
2. 取消选中权限以从角色中移除相应权限。
点击更新以保存修改后的角色。

gcloud CLI

使用 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: role-name
stage: launch-stage
title: role-title

每个占位值的说明如下：

role-description 是角色的简短说明，例如 "My custom role description"。
etag-value 是当前角色版本的唯一标识符，例如 BwVkBkbfr70=。
permission-1 和 permission-2 是要包含在自定义角色中的权限，例如 iam.roles.get。您不能在权限名称中使用通配符 (*)。
role-name 是完整的角色名称，包括任何 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。项目 ID 是字母数字字符串，例如 my-project。组织 ID 是数字，例如 123456789012。
role-name：完整的角色名称，包括任何 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"
}

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

curl（Linux、macOS 或 Cloud Shell）

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

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth 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)

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

$cred = gcloud auth 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（浏览器）

响应中包含简化的角色定义，其中包括角色名称、您更新的字段以及标识角色当前版本的 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 IAM C++ API 参考文档。

在 GitHub 上查看反馈

namespace iam = ::google::cloud::iam;
[](std::string const& name, std::string const& title) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::UpdateRoleRequest request;
  request.set_name(name);
  google::iam::admin::v1::Role role;
  role.set_title(title);
  google::protobuf::FieldMask update_mask;
  *update_mask.add_paths() = "title";
  *request.mutable_role() = role;
  *request.mutable_update_mask() = update_mask;
  auto response = client.UpdateRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully updated: " << response->DebugString()
            << "\n";
}

C#

如需了解如何安装和使用 IAM 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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

停用自定义角色

您可以通过将自定义角色的发布阶段更改为 DISABLED 来停用该角色。当某个角色被停用后，与该角色相关的所有角色绑定也会随之停用，这意味着向用户授予该角色不会产生任何影响。

控制台

在 Google Cloud 控制台中，转到角色页面。

转到“角色”页面
点击页面顶部的“选择项目”下拉列表。
选择您的组织或项目。
选择自定义角色并点击停用。

gcloud CLI

使用 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。项目 ID 是字母数字字符串，例如 my-project。组织 ID 是数字，例如 123456789012。
role-name：完整的角色名称，包括任何 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"
}

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

curl（Linux、macOS 或 Cloud Shell）

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

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth 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)

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

$cred = gcloud auth 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（浏览器）

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/test-project-1000092/roles/myCompanyAdmin",
  "stage": "DISABLED",
  "etag": "BwWoyDpAxBc="
}

C++

将该角色的 stage 字段更新为 DISABLED。

C#

将该角色的 stage 字段更新为 DISABLED。

Go

将该角色的 stage 字段更新为 DISABLED。

Python

将该角色的 stage 字段更新为 DISABLED。

列出角色

您可以列出在项目或组织中创建的所有自定义角色。

控制台

在 Google Cloud 控制台中，转到角色页面。

转到“角色”页面

该页面上会列出您选择的组织或项目的所有自定义角色。

gcloud CLI

使用 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 iam roles list

REST

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

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

resource-type：您要管理其自定义角色的资源类型。使用值 projects 或 organizations。
resource-id：您要管理其自定义角色的项目 ID 或组织 ID。项目 ID 是字母数字字符串，例如 my-project。组织 ID 是数字，例如 123456789012。
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）

执行以下命令：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth 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)

执行以下命令：

$cred = gcloud auth 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 IAM C++ API 参考文档。

在 GitHub 上查看反馈

namespace iam = ::google::cloud::iam;
[](std::string const& project) {
  iam::IAMClient client(iam::MakeIAMConnection());
  int count = 0;
  google::iam::admin::v1::ListRolesRequest request;
  request.set_parent(project);
  for (auto& role : client.ListRoles(request)) {
    if (!role) throw std::move(role).status();
    std::cout << "Roles successfully retrieved: " << role->name() << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No roles found in project: " << project << "\n";
  }
}

C#

如需了解如何安装和使用 IAM 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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'])

删除自定义角色

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

控制台

在 Google Cloud 控制台中，转到角色页面。

转到“角色”页面
选择要删除的角色，然后点击页面顶部的删除。

gcloud CLI

使用 gcloud iam roles delete 命令删除自定义角色：

要删除组织级层自定义角色，请执行以下命令：

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 方法可删除项目或组织中的自定义角色。

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

role-name：完整的角色名称，包括任何 organizations/、projects/ 或 roles/ 前缀。例如 organizations/123456789012/roles/myCompanyAdmin。

HTTP 方法和网址：

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

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

curl（Linux、macOS 或 Cloud Shell）

执行以下命令：

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

PowerShell (Windows)

执行以下命令：

$cred = gcloud auth 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 IAM C++ API 参考文档。

在 GitHub 上查看反馈

namespace iam = ::google::cloud::iam;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::DeleteRoleRequest request;
  request.set_name(name);
  auto response = client.DeleteRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully deleted: " << response->DebugString()
            << "\n";
}

C#

如需了解如何安装和使用 IAM 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 天内，Google Cloud 控制台会显示该角色已被删除。您也可以以编程方式列出已删除的角色，但默认情况下它们会被忽略。

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

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

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

恢复删除自定义角色

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

您只能在 7 天内恢复删除的角色。7 天后，该角色可以随时被永久删除，并且系统会移除引用该角色的所有角色绑定。

控制台

在 Google Cloud 控制台中，转到角色页面。

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

gcloud CLI

使用 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 方法可恢复项目或组织中已删除的自定义角色。

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

role-name：完整的角色名称，包括任何 organizations/、projects/ 或 roles/ 前缀。例如 organizations/123456789012/roles/myCompanyAdmin。
etag：角色版本的标识符。包含此字段可防止覆盖其他角色更改。

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "etag": "etag"
}

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

curl（Linux、macOS 或 Cloud Shell）

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth 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)

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

$cred = gcloud auth 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（浏览器）

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

{
  "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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 IAM C++ API 参考文档。

在 GitHub 上查看反馈

namespace iam = ::google::cloud::iam;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::UndeleteRoleRequest request;
  request.set_name(name);
  auto response = client.UndeleteRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully undeleted: " << response->DebugString()
            << "\n";
}

C#

如需了解如何安装和使用 IAM 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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 客户端库，请参阅 IAM 客户端库。如需了解详情，请参阅 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

后续步骤

了解如何向主帐号授予角色。
了解如何使用角色建议来缩小主帐号的权限范围。
了解条件角色授予，该机制只有在满足特定条件的情况下才会授予角色。