创建和管理自定义角色

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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

from typing import List

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2, policy_pb2


def query_testable_permissions(
    project_id: str, permissions: List[str]
) -> policy_pb2.Policy:
    """
    Tests IAM permissions of the caller.

    project_id: ID or number of the Google Cloud project you want to use.
    """

    client = resourcemanager_v3.ProjectsClient()
    request = iam_policy_pb2.TestIamPermissionsRequest()
    request.resource = f"projects/{project_id}"
    request.permissions.extend(permissions)

    permissions_reponse = client.test_iam_permissions(request)
    print(permissions_reponse)
    return permissions_reponse.permissions

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

$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

响应包含权限列表。

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

控制台

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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

from google.api_core.exceptions import NotFound
from google.cloud.iam_admin_v1 import GetRoleRequest, IAMClient, Role


def get_role(project_id: str, role_id: str) -> Role:
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = GetRoleRequest(name=name)
    try:
        role = client.get_role(request)
        print(f"Retrieved role: {role_id}: {role}")
        return role
    except NotFound:
        raise f"Role with id [{role_id}] not found, take some actions"

REST

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

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

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

HTTP 方法和网址：

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

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

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

$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

响应中包含角色定义。

{
  "name": "projects/my-project/roles/customRole",
  "title": "My Custom Role",
  "description": "My custom role description.",
  "includedPermissions": [
    "storage.buckets.get",
    "storage.buckets.list"
  ],
  "etag": "BwWiPg2fmDE="
}

控制台

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

gcloud

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

REST API

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

控制台

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

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

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

   转到“角色”页面

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

3. 点击创建角色。

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

5. 点击添加权限。

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

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

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

   转到“角色”页面

2. 选择要在哪个组织或项目中创建角色。
3. 选择创建新自定义角色时要依据的基准角色。
4. 点击基于所选角色创建角色。
5. 输入角色的称谓、说明、ID 和角色发布阶段。角色创建后，角色 ID 便无法更改。
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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

from typing import List, Optional

from google.api_core.exceptions import AlreadyExists, FailedPrecondition
from google.cloud.iam_admin_v1 import CreateRoleRequest, IAMClient, Role


def create_role(
    project_id: str, role_id: str, permissions: List[str], title: Optional[str] = None
) -> Role:
    """
    Creates iam role with given parameters.
    Args:
        project_id: GCP project id
        role_id: id of GCP iam role
        permissions: list of iam permissions to assign to role. f.e ["iam.roles.get", "iam.roles.list"]
        title: title for iam role. role_id will be used in case of None

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()

    parent = f"projects/{project_id}"

    request = CreateRoleRequest(
        parent=parent,
        role_id=role_id,
        role=Role(title=title, included_permissions=permissions),
    )
    try:
        role = client.create_role(request)
        print(f"Created iam role: {role_id}: {role}")
        return role
    except AlreadyExists:
        print(f"Role with id [{role_id}] already exists, take some actions")
    except FailedPrecondition:
        print(
            f"Role with id [{role_id}] already exists and in deleted state, take some actions"
        )

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

$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

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

{
  "name": "projects/myProject/roles/myCompanyAdmin",
  "title": "My Company Admin",
  "description": "My custom role description.",
  "includedPermissions": [
    "iam.roles.get",
    "iam.roles.list"
  ],
  "etag": "BwWox/JbaZw="
}

控制台

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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

from google.api_core.exceptions import NotFound
from google.cloud.iam_admin_v1 import IAMClient, Role, UpdateRoleRequest

from snippets.get_role import get_role


def edit_role(role: Role) -> Role:
    """
    Edits an existing IAM role in a GCP project.
    Args:
        role: google.cloud.iam_admin_v1.Role object to be updated

    Returns: Updated google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    request = UpdateRoleRequest(name=role.name, role=role)
    try:
        role = client.update_role(request)
        print(f"Edited role: {role.name}: {role}")
        return role
    except NotFound:
        print(f"Role [{role.name}] not found, take some actions")

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

$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

响应中包含简化的角色定义，其中包括角色名称、您更新的字段以及标识角色当前版本的 ETag。

{
  "name": "projects/test-project-1000092/roles/myCompanyAdmin",
  "title": "My Updated Company Admin",
  "includedPermissions": [
    "storage.buckets.get",
    "storage.buckets.list"
  ],
  "stage": "BETA",
  "etag": "BwWoyDpAxBc="
}

控制台

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

如需了解如何安装和使用 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.UpdateRoleRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class DisableRole {

  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 = "testRole";

    Role role = disableRole(projectId, roleId);
    System.out.println("Role name: " + role.getName());
    System.out.println("Role stage: " + role.getStage());
  }

  public static Role disableRole(String projectId, String roleId)
          throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    Role role = Role.newBuilder()
                    .setName(roleName)
                    .setStage(Role.RoleLaunchStage.DISABLED)
                    .build();

    FieldMask fieldMask = FieldMask.newBuilder().addPaths("stage").build();
    UpdateRoleRequest updateRoleRequest =
              UpdateRoleRequest.newBuilder()
                      .setName(roleName)
                      .setRole(role)
                      .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()) {
      return iamClient.updateRole(updateRoleRequest);
    }
  }
}

Python

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

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

from google.cloud.iam_admin_v1 import GetRoleRequest, IAMClient, Role, UpdateRoleRequest


def disable_role(project_id: str, role_id: str) -> Role:
    """
    Disables an IAM role in a GCP project.
    Args:
        project_id: GCP project ID
        role_id: ID of GCP IAM role

    Returns: Updated google.cloud.iam_admin_v1.Role object with disabled stage
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    get_request = GetRoleRequest(name=name)
    try:
        role = client.get_role(get_request)
        role.stage = Role.RoleLaunchStage.DISABLED
        update_request = UpdateRoleRequest(name=role.name, role=role)
        client.update_role(update_request)
        print(f"Disabled role: {role_id}: {role}")
        return role
    except NotFound:
        raise f"Role with id [{role_id}] not found, take some actions"

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

$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

您应该收到类似以下内容的 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 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅准备工作。

from google.cloud.iam_admin_v1 import IAMClient, ListRolesRequest, RoleView
from google.cloud.iam_admin_v1.services.iam.pagers import ListRolesPager


def list_roles(
    project_id: str, show_deleted: bool = True, role_view: RoleView = RoleView.BASIC
) -> ListRolesPager:
    """
    Lists IAM roles in a GCP project.
    Args:
        project_id: GCP project ID
        show_deleted: Whether to include deleted roles in the results
        role_view: Level of detail for the returned roles (e.g., BASIC or FULL)

    Returns: A pager for traversing through the roles
    """
    client = IAMClient()
    parent = f"projects/{project_id}"
    request = ListRolesRequest(parent=parent, show_deleted=show_deleted, view=role_view)
    roles = client.list_roles(request)
    for page in roles.pages:
        for role in page.roles:
            print(role)
    print("Listed all iam roles")
    return roles

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：可选。此方法之前的响应中返回的分页令牌。如果已指定，则角色列表将从上一个请求结束的位置开始。

HTTP 方法和网址：

GET https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

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

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"

$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

您应该收到类似以下内容的 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. 选择要删除的角色，然后点击页面顶部的 delete 删除。

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