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

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

准备工作

• 启用 IAM API。

  启用 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. 安装 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

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

所需的角色

如需获得列出可授予角色所需的权限，请让您的管理员为您授予要列出其可授予角色的资源的 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 角色。
• 了解如何选择最合适的预定义角色。
• 了解如何授予、更改和撤消主账号的访问权限。
• 要了解不同类型的资源，请参阅资源名称示例。