查看可针对资源授予的角色

针对某项资源为用户授予 Identity and Access Management (IAM) 角色之前，您可能想知道对于某项特定资源可以授予哪些角色。

准备工作

• 启用 IAM API。

  启用 API

• 设置身份验证。

  选择标签页以了解您打算如何使用本页面上的示例：

  控制台

  当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时，无需设置身份验证。

  gcloud

  您可以从以下任一开发环境使用本页面上的 gcloud CLI 示例：

  • Cloud Shell：如需使用已设置 gcloud CLI 的在线终端，请激活 Cloud Shell。

    Cloud Shell 会话会在页面底部启动，并显示命令行提示符。该会话可能需要几秒钟来完成初始化。

  • 本地 shell：如需在本地开发环境中使用 gcloud CLI，请安装并初始化 gcloud CLI。

  C++

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

  1. 安装 Google Cloud CLI。

  2. 如需初始化 gcloud CLI，请运行以下命令：

     gcloud init

  3. 为您的 Google 账号创建本地身份验证凭据：

     gcloud auth application-default login

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

  C#

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

  1. 安装 Google Cloud CLI。

  2. 如需初始化 gcloud CLI，请运行以下命令：

     gcloud init

  3. 为您的 Google 账号创建本地身份验证凭据：

     gcloud auth application-default login

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

  Go

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

  1. 安装 Google Cloud CLI。

  2. 如需初始化 gcloud CLI，请运行以下命令：

     gcloud init

  3. 为您的 Google 账号创建本地身份验证凭据：

     gcloud auth application-default login

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

  Java

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

  1. 安装 Google Cloud CLI。

  2. 如需初始化 gcloud CLI，请运行以下命令：

     gcloud init

  3. 为您的 Google 账号创建本地身份验证凭据：

     gcloud auth application-default login

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

  Python

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

  1. 安装 Google Cloud CLI。

  2. 如需初始化 gcloud CLI，请运行以下命令：

     gcloud init

  3. 为您的 Google 账号创建本地身份验证凭据：

     gcloud auth application-default login

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

  REST

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

  安装 Google Cloud CLI，然后通过运行以下命令初始化 Google Cloud CLI：

  gcloud init

所需的角色

如需获得列出可授予角色所需的权限，请让您的管理员为您授予要列出其可授予角色的资源的 Security Reviewer (roles/iam.securityReviewer) IAM 角色。 如需详细了解如何授予角色，请参阅管理访问权限。

此预定义角色包含所有资源类型的 getIamPolicy 权限。如需列出可授予的角色，您需要拥有要列出可授予的角色的资源的 getIamPolicy 权限 - 例如，要列出项目的可授予角色，您需要 resourcemanager.projects.getIamPolicy 权限。

您也可以使用自定义角色或其他预定义角色来获取此权限。

了解可授予哪些角色

如果某个角色包含某种资源类型的任何权限，则可以针对该资源或其上层资源授予该角色。例如，storage.admin 角色授予 storage.buckets.get 和 storage.objects.get API 的权限，因此可以针对“Storage Buckets”和“Storage Objects”资源类型授予该角色。

也可以在定义角色权限的资源类型的“上层”授予这些角色。换句话说，可以针对位于 Google Cloud 资源层次结构中较高级层的资源授予较低层级资源的角色。以 storage.admin 角色为例，除了“Storage Buckets”外，您还可以在项目或组织级层授予该角色。

按角色授予的权限只会影响指定级层或更低级层的资源，而不会影响更高级层的资源或同级资源。此外，针对资源授予某项角色时，系统仅会授予适用于指定资源的权限，而无论该角色的名称、说明或其包含的其他权限为何。例如，在项目级层将角色 resourcemanager.organizationAdmin（该角色授予 resourcemanager.projects.list 权限）分配给用户，只会为他们授予该特定项目的权限。而不允许他们列出或管理组织中的所有项目。同样，在特定 Compute Engine 实例上分配 compute.admin 角色只会为该实例（而不会为项目中的其他实例）授予权限。

列出可授予的角色

您可以使用 Google Cloud 控制台、Google Cloud CLI、IAM API 或 IAM 客户端库列出可授予的角色。

Google Cloud 控制台始终会列出您正在查看的资源的所有可授予角色。Google Cloud CLI、IAM API 和客户端库仅会列出已启用的 API 的可授予角色。

控制台

如需查看项目、文件夹或组织的可授予角色，请执行以下操作：

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

   转到 IAM 页面

2. 点击页面顶部的选择项目。

3. 选择您要查看其可授予角色的项目、文件夹或组织。

4. 点击 授予访问权限。

5. 点击选择角色 此菜单显示您可以针对此资源授予的所有角色，包括任何自定义角色。

如需查看其他资源类型的可授予角色，请执行以下操作：

1. 在 Google Cloud 控制台中，进入列出要查看其可授予角色的资源的页面。

   例如，如需管理对 Compute Engine 实例的访问权限，请转到虚拟机实例页面。

   进入“虚拟机实例”

2. 选中要查看其可授予角色的资源旁边的复选框。

3. 确保信息面板可见。如果未显示，请点击显示信息面板。

4. 点击 添加主账号。

5. 点击选择角色 此菜单显示您可以针对此资源授予的所有角色，包括任何自定义角色。

gcloud

使用 gcloud iam list-grantable-roles 命令返回可应用于给定资源的所有角色的列表。

gcloud iam list-grantable-roles full-resource-name

系统可能会返回大量角色，具体取决于所需的资源。 如需限制结果数量，您可以指定过滤表达式。

输出结果如下所示：

description: Full control of all Compute Engine resources.
name: roles/compute.admin
title: Compute Admin
---
description: Full control of Compute Engine instance resources.
name: roles/compute.instanceAdmin
title: Compute Instance Admin

# Additional results here...

C++

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

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

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& resource) {
  iam::IAMClient client(iam::MakeIAMConnection());
  int count = 0;
  for (auto& role : client.QueryGrantableRoles(resource)) {
    if (!role) throw std::move(role).status();
    std::cout << "Role successfully retrieved: " << role->name() << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No grantable roles 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<Role> ViewGrantableRoles(string fullResourceName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var request = new QueryGrantableRolesRequest
        {
            FullResourceName = fullResourceName
        };
        var response = service.Roles.QueryGrantableRoles(request).Execute();
        foreach (var role in response.Roles)
        {
            Console.WriteLine("Title: " + role.Title);
            Console.WriteLine("Name: " + role.Name);
            Console.WriteLine("Description: " + role.Description);
            Console.WriteLine();
        }
        return response.Roles;
    }
}

Go

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

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

import (
	"context"
	"fmt"
	"io"

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

// viewGrantableRoles lists roles grantable on a resource.
func viewGrantableRoles(w io.Writer, fullResourceName 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.QueryGrantableRolesRequest{
		FullResourceName: fullResourceName,
	}
	response, err := service.Roles.QueryGrantableRoles(request).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.QueryGrantableRoles: %w", err)
	}
	for _, role := range response.Roles {
		fmt.Fprintf(w, "Found grantable role: %v\n", role.Name)
	}
	return response.Roles, err
}

Java

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

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

QueryGrantableRolesRequest request = new QueryGrantableRolesRequest();
request.setFullResourceName(fullResourceName);

QueryGrantableRolesResponse response = service.roles().queryGrantableRoles(request).execute();

for (Role role : response.getRoles()) {
  System.out.println("Title: " + role.getTitle());
  System.out.println("Name: " + role.getName());
  System.out.println("Description: " + role.getDescription());
  System.out.println();
}

Python

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

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

def view_grantable_roles(full_resource_name: str) -> None:
    roles = (
        service.roles()
        .queryGrantableRoles(body={"fullResourceName": full_resource_name})
        .execute()
    )

    for role in roles["roles"]:
        if "title" in role:
            print("Title: " + role["title"])
        print("Name: " + role["name"])
        if "description" in role:
            print("Description: " + role["description"])
        print(" ")

REST

roles.queryGrantableRoles 方法会返回针对某个资源可授予的所有角色的列表。

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

• FULL_RESOURCE_NAME：由服务名称和资源路径组成的 URI。如需查看示例，请参阅完整资源名称。

HTTP 方法和网址：

POST https://iam.googleapis.com/v1/roles:queryGrantableRoles

请求 JSON 正文：

{
  "fullResourceName": "FULL_RESOURCE_NAME"
}

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

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/roles:queryGrantableRoles"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 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/roles:queryGrantableRoles" | Select-Object -Expand Content

APIs Explorer（浏览器）

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

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

{
  "roles": [
    {
      "name": "roles/compute.admin",
      "title": "Compute Admin",
      "description": "Full control of all Compute Engine resources."
    },
    {
      "name": "roles/compute.instanceAdmin",
      "title": "Compute Instance Admin (beta)",
      "description": "Full control of Compute Engine instance resources."
    }
  ]
}

在上面的示例中，完整资源名称是无传输协议的 URI，由与 DNS 兼容的 API 服务名称和资源路径组成。

例如，如需返回针对项目可授予的所有角色，请使用：

//cloudresourcemanager.googleapis.com/projects/project-id

较低层级资源具有更详细的完全限定名称。例如，使用以下命令可返回针对 Compute Engine 实例可授予的所有角色：

//compute.googleapis.com/projects/project-id/zones/zone-name/instances/instance-id

后续步骤

• 了解可用的 IAM 角色。
• 了解如何选择最合适的预定义角色。
• 了解如何授予、更改和撤消主账号的访问权限。
• 要了解不同类型的资源，请参阅资源名称示例。