创建和管理自定义角色

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

准备工作

• Enable the IAM API.

  Enable the API

• 设置身份验证。

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  C++

  如需在本地开发环境中使用本页面上的 C++ 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  如需了解详情，请参阅 Google Cloud 身份验证文档中的为本地开发环境设置身份验证。

  C#

  如需在本地开发环境中使用本页面上的 .NET 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  如需了解详情，请参阅 Google Cloud 身份验证文档中的为本地开发环境设置身份验证。

  Go

  如需在本地开发环境中使用本页面上的 Go 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  如需了解详情，请参阅 Google Cloud 身份验证文档中的为本地开发环境设置身份验证。

  Java

  如需在本地开发环境中使用本页面上的 Java 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  如需了解详情，请参阅 Google Cloud 身份验证文档中的为本地开发环境设置身份验证。

  Python

  如需在本地开发环境中使用本页面上的 Python 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  如需了解详情，请参阅 Google Cloud 身份验证文档中的为本地开发环境设置身份验证。

  REST

  如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭据。

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

• 了解 Google Cloud 资源层次结构。

• 阅读了解 IAM 自定义角色。

所需的角色

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

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

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

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

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

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

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

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

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

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 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）

   • 组织：//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
   ---
   

C++

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

namespace iam = ::google::cloud::iam_admin_v1;
[](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 参考文档。

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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: %w", err)
	}

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

Java

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.cloud.iam.admin.v1.IAMClient.QueryTestablePermissionsPagedResponse;
import com.google.iam.admin.v1.QueryTestablePermissionsRequest;
import java.io.IOException;

/** View available permissions in a project. */
public class QueryTestablePermissions {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    // Full resource names can take one of the following forms:
    // cloudresourcemanager.googleapis.com/projects/PROJECT_ID
    // cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID
    String fullResourceName = "your-full-resource-name";

    queryTestablePermissions(fullResourceName);
  }

  public static void queryTestablePermissions(String fullResourceName) throws IOException {
    QueryTestablePermissionsRequest queryTestablePermissionsRequest =
        QueryTestablePermissionsRequest.newBuilder().setFullResourceName(fullResourceName).build();

    try (IAMClient iamClient = IAMClient.create()) {
      QueryTestablePermissionsPagedResponse queryTestablePermissionsPagedResponse =
          iamClient.queryTestablePermissions(queryTestablePermissionsRequest);
      queryTestablePermissionsPagedResponse
          .iterateAll()
          .forEach(permission -> System.out.println(permission.getName()));
    }
  }
}

Python

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

def query_testable_permissions(resource: str) -> None:
    """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"])

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)

注意：以下命令假定您已登录gcloud请使用您的用户账号来运行以下命令：gcloud init 或 gcloud auth login . 您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

APIs Explorer（浏览器）

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

响应包含权限列表。

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

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

获取角色元数据

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

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

控制台

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

   转到“角色”页面

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

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

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

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

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 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。

   • ROLE_ID 是角色的 ID，不包括 projects/、organizations/ 或 roles/ 等任何前缀。例如 myCompanyAdmin。

   如需了解详情，请参阅 gcloud iam roles describe 的参考文档。

C++

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

namespace iam = ::google::cloud::iam_admin_v1;
[](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 参考文档。

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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: %w", err)
	}

	role, err := service.Roles.Get(name).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.Get: %w", 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
}

Java

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.GetRoleRequest;
import com.google.iam.admin.v1.Role;
import java.io.IOException;

/** Get role metadata. Specifically, printing out role permissions. */
public class GetRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    String roleId = "a unique identifier (e.g. testViewer)";

    getRole(roleId);
  }

  public static void getRole(String roleId) throws IOException {
    GetRoleRequest getRoleRequest = GetRoleRequest.newBuilder().setName(roleId).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role role = iamClient.getRole(getRoleRequest);
      role.getIncludedPermissionsList().forEach(permission -> System.out.println(permission));
    }
  }
}

Python

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

def get_role(name: str) -> None:
    """Gets a role."""

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

REST

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

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

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

HTTP 方法和网址：

GET https://iam.googleapis.com/v1/ROLE_NAME

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

curl（Linux、macOS 或 Cloud Shell）

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

执行以下命令：

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

PowerShell (Windows)

注意：以下命令假定您已登录gcloud请使用您的用户账号来运行以下命令：gcloud init 或 gcloud auth login . 您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

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

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

APIs Explorer（浏览器）

打开方法参考页面。APIs 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="
}

创建自定义角色

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

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

组织级层自定义角色可以包含自定义角色支持的任何 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 发布阶段停用自定义角色。如需详细了解发布阶段，请参阅测试和部署。

控制台

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

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

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

   转到“角色”页面

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

3. 点击创建角色。

4. 输入角色的名称、标题、说明和角色发布阶段。角色创建后，角色名称便无法更改。

5. 点击添加权限。

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

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

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

   转到“角色”页面

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

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 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。

   • 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 \
       --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/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。

   • 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 \
       --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/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

C++

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

namespace iam = ::google::cloud::iam_admin_v1;
[](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 参考文档。

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Created role: %v", role.Name)
	return role, nil
}

Java

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.CreateRoleRequest;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.Role.RoleLaunchStage;
import java.io.IOException;
import java.util.Arrays;

/** Create role. */
public class CreateRole {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";
    String title = "a title for your role (e.g. IAM Role Viewer)";
    String description = "a description of the role";
    Iterable<String> includedPermissions =
        Arrays.asList("roles/iam.roleViewer", "roles/logging.viewer");

    createRole(projectId, title, description, includedPermissions, roleId);
  }

  public static void createRole(
      String projectId,
      String title,
      String description,
      Iterable<String> includedPermissions,
      String roleId)
      throws IOException {
    Role.Builder roleBuilder =
        Role.newBuilder()
            .setTitle(title)
            .setDescription(description)
            .addAllIncludedPermissions(includedPermissions)
            // See launch stage enums at
            // https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage
            .setStage(RoleLaunchStage.BETA);
    CreateRoleRequest createRoleRequest =
        CreateRoleRequest.newBuilder()
            .setParent("projects/" + projectId)
            .setRoleId(roleId)
            .setRole(roleBuilder)
            .build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role result = iamClient.createRole(createRoleRequest);
      System.out.println("Created role: " + result.getName());
    }
  }
}

Python

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

def create_role(
    name: str, project: str, title: str, description: str, permissions: str, stage: str
) -> dict:
    """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

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）

注意：以下命令假定您已使用您的用户账号通过运行 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/RESOURCE_TYPE/RESOURCE_ID/roles"

PowerShell (Windows)

注意：以下命令假定您已登录gcloud请使用您的用户账号来运行以下命令：gcloud init 或 gcloud auth login . 您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

APIs Explorer（浏览器）

复制请求正文并打开方法参考页面。APIs 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="
}

修改现有自定义角色

通常，我们按照以下模式更新资源的元数据（如自定义角色）：读取-修改-写入模式。使用此模式时，您可以读取角色的当前状态，在本地更新数据，然后发送修改后的数据以进行写入。

如果有两个或两个以上的独立过程同时尝试执行该序列，则读取-修改-写入模式可能会导致冲突。例如，当项目有两位所有者同时尝试对某一角色进行有冲突的更改时，部分更改可能会失败。IAM 可利用自定义角色的 etag 属性解决此问题。该属性用于验证自上次请求以来自定义角色是否发生了更改。当您使用 ETag 值向 IAM 发出请求时，IAM 会将请求中的 ETag 值与自定义角色所关联的现有 ETag 值进行比较。只有在两个 ETag 值一致的情况下，它才会写入相应更改。

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

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

控制台

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

   转到“角色”页面

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

3. 点击自定义角色。

4. 点击修改角色。

5. 如需更新角色的元数据，请修改角色的标题、说明或角色发布阶段。

6. 如需更新角色的权限，请执行以下操作：

   1. 点击添加权限以为角色添加新权限。
   2. 取消选中权限以从角色中移除相应权限。

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

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 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。

   describe 命令返回角色的定义并包含用于唯一标识当前角色版本的 etag 值。您应在更新的角色定义中提供 etag 值，以确保任何并发的角色更改都不会被覆盖。

   describe 命令返回以下输出：

   description: ROLE_DESCRIPTION
   etag: ETAG
   includedPermissions:
   - PERMISSION_1
   - PERMISSION_2
   name: ROLE_NAME
   stage: LAUNCH_STAGE
   title: ROLE_TITLE

   每个占位值的说明如下：

   • ROLE_DESCRIPTION 是角色的简短说明，例如 "My custom role description"。

   • ETAG 是当前角色版本的唯一标识符，例如 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/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 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。

   • 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 \
       --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/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。

   • 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 \
       --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/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

C++

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

namespace iam = ::google::cloud::iam_admin_v1;
[](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 参考文档。

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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: %w", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	role, err := service.Projects.Roles.Get(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Get: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Updated role: %v", role.Name)
	return role, nil
}

Java

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.Role.RoleLaunchStage;
import com.google.iam.admin.v1.UpdateRoleRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

/** Edit role metadata. Specifically, update description and launch stage. */
public class EditRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";
    String description = "a new description of the role";

    editRole(projectId, roleId, description);
  }

  public static void editRole(String projectId, String roleId, String description)
      throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    Role.Builder roleBuilder =
        Role.newBuilder()
            .setName(roleName)
            .setDescription(description)
            // See launch stage enums at
            // https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage
            .setStage(RoleLaunchStage.GA);
    FieldMask fieldMask = FieldMask.newBuilder().addPaths("description").addPaths("stage").build();
    UpdateRoleRequest updateRoleRequest =
        UpdateRoleRequest.newBuilder()
            .setName(roleName)
            .setRole(roleBuilder)
            .setUpdateMask(fieldMask)
            .build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role result = iamClient.updateRole(updateRoleRequest);
      System.out.println("Edited role:\n" + result);
    }
  }
}

Python

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

def edit_role(
    name: str, project: str, title: str, description: str, permissions: str, stage: str
) -> dict:
    """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

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": "ROLE_NAME",
  "title": "ROLE_TITLE",
  "description": "ROLE_DESCRIPTION",
  "includedPermissions": [
    "PERMISSION_1",
    "PERMISSION_2"
  ],
  "stage": "LAUNCH-STAGE",
  "etag": "ETAG"
}

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

curl（Linux、macOS 或 Cloud Shell）

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

将请求正文保存在名为 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)

注意：以下命令假定您已登录gcloud请使用您的用户账号来运行以下命令：gcloud init 或 gcloud auth login . 您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

APIs Explorer（浏览器）

复制请求正文并打开方法参考页面。APIs 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="
}

停用自定义角色

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

控制台

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

   转到“角色”页面

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

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

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

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 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。

   示例

   以下示例演示了如何停用组织级层角色：

   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 \
       --stage=DISABLED

   如果成功更新了角色，则该命令的输出类似于以下内容：

   description: My custom role description.
   etag: BwVkB5NLIQw=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   name: projects/my-project/roles/myCompanyAdmin
   stage: DISABLED
   title: My Company Admin

C++

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

C#

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

Go

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

Java

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

Python

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

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_TYPE/RESOURCE_ID/roles

请求 JSON 正文：

{
  "roleId": "ROLE_NAME",
  "stage": DISABLED,
  "etag": "ETAG"
}

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

curl（Linux、macOS 或 Cloud Shell）

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

将请求正文保存在名为 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)

注意：以下命令假定您已登录gcloud请使用您的用户账号来运行以下命令：gcloud init 或 gcloud auth login . 您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

APIs Explorer（浏览器）

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

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

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

列出角色

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

控制台

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

转到“角色”页面

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

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 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。

   此外，还可以指定 --show-deleted 标志以列出已删除的角色。

   执行以下命令可列出预定义角色：

   gcloud iam roles list

C++

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

namespace iam = ::google::cloud::iam_admin_v1;
[](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 参考文档。

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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: %w", err)
	}

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

Java

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.cloud.iam.admin.v1.IAMClient.ListRolesPagedResponse;
import com.google.iam.admin.v1.ListRolesRequest;
import java.io.IOException;

/** List roles in a project. */
public class ListRoles {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    String projectId = "your-project-id";

    listRoles(projectId);
  }

  public static void listRoles(String projectId) throws IOException {
    ListRolesRequest listRolesRequest =
        ListRolesRequest.newBuilder().setParent("projects/" + projectId).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      ListRolesPagedResponse listRolesResponse = iamClient.listRoles(listRolesRequest);
      listRolesResponse.iterateAll().forEach(role -> System.out.println(role));
    }
  }
}

Python

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

def list_roles(project_id: str) -> None:
    """Lists roles."""

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

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）

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

执行以下命令：

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)

注意：以下命令假定您已登录gcloud请使用您的用户账号来运行以下命令：gcloud init 或 gcloud auth login . 您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

APIs Explorer（浏览器）

打开方法参考页面。APIs 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="
    }
  ]
}

删除自定义角色

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

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

控制台

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

   转到“角色”页面

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

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 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。

   除非使用 --show-deleted 标志，否则删除的角色将不会包含在 gcloud iam roles list 中。在 list 响应中，删除的角色以 deleted: true 块表示，例如：

   ---
   deleted: true
   description: My custom role description.
   etag: BwVkB5NLIQw=
   name: projects/my-project/roles/myCompanyAdmin
   title: My Company Admin
   ---
   

C++

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

namespace iam = ::google::cloud::iam_admin_v1;
[](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 参考文档。

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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: %w", err)
	}

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

Java

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.DeleteRoleRequest;
import java.io.IOException;

/** Delete role. */
public class DeleteRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";

    deleteRole(projectId, roleId);
  }

  public static void deleteRole(String projectId, String roleId) throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    DeleteRoleRequest deleteRoleRequest = DeleteRoleRequest.newBuilder().setName(roleName).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      iamClient.deleteRole(deleteRoleRequest);
      System.out.println("Role deleted.");
    }
  }
}

Python

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

def delete_role(name: str, project: str) -> dict:
    """Deletes a role."""

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

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

REST

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

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

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

HTTP 方法和网址：

DELETE https://iam.googleapis.com/v1/ROLE_NAME

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

curl（Linux、macOS 或 Cloud Shell）

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

执行以下命令：

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

PowerShell (Windows)

注意：以下命令假定您已登录gcloud请使用您的用户账号来运行以下命令：gcloud init 或 gcloud auth login . 您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

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

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

APIs Explorer（浏览器）

打开方法参考页面。APIs 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
}

角色被删除后，引用该角色的任何角色绑定都将保留在允许政策中，但处于无效状态。您可以在 7 天内恢复删除的角色。在这 7 天内，Google Cloud 控制台会显示该角色已被删除。您也可以以编程方式列出已删除的角色，但默认情况下它们会被忽略。

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

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

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

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

恢复删除自定义角色

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

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

控制台

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

   转到“角色”页面

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

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 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。

   示例

   以下示例演示了如何恢复删除的组织级层自定义角色：

   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

   如果成功恢复了删除的角色，则该命令的输出类似于以下内容：

   description: My custom role description.
   etag: BwVkCAx9W6w=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   name: projects/my-project/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

C++

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

namespace iam = ::google::cloud::iam_admin_v1;
[](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 参考文档。

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

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: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Undeleted role: %v", role.Name)
	return role, nil
}

Java

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.UndeleteRoleRequest;
import java.io.IOException;

/**
 * Undelete a role to return it to its previous state. Undeleting only works on roles that were
 * deleted in the past 7 days.
 */
public class UndeleteRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to a role that was deleted in the past 7 days.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";

    undeleteRole(projectId, roleId);
  }

  public static void undeleteRole(String projectId, String roleId) throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    UndeleteRoleRequest undeleteRoleRequest =
        UndeleteRoleRequest.newBuilder().setName(roleName).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role result = iamClient.undeleteRole(undeleteRoleRequest);
      System.out.println("Undeleted role:\n" + result);
    }
  }
}

Python

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

如需向 IAM 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

def undelete_role(name: str, project: str) -> dict:
    """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

REST

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

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

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

HTTP 方法和网址：

POST https://iam.googleapis.com/v1/ROLE_NAME:undelete

请求 JSON 正文：

{
  "etag": "ETAG"
}

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

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/ROLE_NAME:undelete"

PowerShell (Windows)

注意：以下命令假定您已登录gcloud请使用您的用户账号来运行以下命令：gcloud init 或 gcloud auth login . 您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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/ROLE_NAME:undelete" | Select-Object -Expand Content

APIs Explorer（浏览器）

复制请求正文并打开方法参考页面。APIs 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="
}

后续步骤

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