建立及管理自訂角色

本頁面說明如何建立和管理自訂角色。

事前準備

  • 請參閱瞭解 IAM 自訂角色一文,其中提供建立自訂角色所需權限與最佳做法的相關資訊。
  • 如果您使用 gcloud 指令列工具,請確定版本為 188.0.0 或更新版本。如要將 gcloud 更新為 188.0.0 版,請執行以下指令:gcloud components update --version 188.0.0

檢視資源的可用權限

在建立自訂角色前,您可能會想要知道什麼權限可以套用到某項資源上。您可以透過 gcloud 指令列工具、Cloud Console 或 IAM API,取得可套用到資源及階層下方資源的所有權限。例如,您能夠取得可套用在機構和機構內專案的所有權限。

主控台

  1. 前往 GCP 主控台的「Roles」(角色) 頁面。

    開啟「Roles」(角色) 頁面

  2. 在頁面頂端的下拉式選單中選取專案。
  3. 勾選資源管理角色的核取方塊,即可檢視能套用到這項資源的所有權限。舉例來說,如果選取 Compute 執行個體管理員角色,右側面板就會顯示可套用到 Compute Engine 執行個體的所有權限。

GCLOUD 指令

只要使用 gcloud iam list-testable-permissions 指令,您就能取得可套用至目標資源的權限清單。傳回的權限即為可用於在這項資源和階層下方的任何資源中建立自訂角色的權限。

下列範例說明如何列出某項專案資源可測試的權限:

gcloud iam list-testable-permissions [PROJECT-ID]

[PROJECT-ID] 是完整資源名稱形式的專案 ID://cloudresourcemanager.googleapis.com/projects/PROJECT-ID,像是 //cloudresourcemanager.googleapis.com/projects/my-project-id

list-testable-permissions 指令可能會傳回數百個結果。如要過濾傳回的結果,您也可以指定篩選條件運算式。以下為只顯示部分結果的範例:

---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
customRolesSupportLevel: NOT_SUPPORTED
name: appengine.applications.list
onlyInPredefinedRoles: true
stage: GA
---
name: appengine.applications.update
stage: GA
---
name: appengine.instances.delete
stage: GA
---
name: appengine.instances.get
stage: GA
---

請注意,每個權限都會顯示是否受到自訂角色支援。如需支援與未支援權限的完整清單,請參閱自訂角色權限支援說明。

REST API

QueryTestablePermissions 會傳回可套用至資源的所有權限。傳回的權限即為可用於在這項資源和階層下方的任何資源建立自訂角色的權限。這項要求只需要輸入完整的資源名稱,像是 //cloudresourcemanager.googleapis.com/projects/my-project

如果資源的權限清單較長,呼叫者也可以選擇性提供分頁支援。

範例

full_resource_name: '//cloudresourcemanager.googleapis.com/projects/my-project'`

錯誤代碼

錯誤代碼 狀態訊息
INVALID_ARGUMENT 必須介於 0 至 100 之間
INVALID_ARGUMENT 分頁符記編碼無效
INVALID_ARGUMENT 分頁符記無效
INVALID_ARGUMENT 分頁符記不適用於指定容器
INVALID_ARGUMENT 分頁符記內的起點無效
INVALID_ARGUMENT 分頁符記 Cookie 無效
INVALID_ARGUMENT 分頁符記過期
INVALID_ARGUMENT 必須指定 {full_resource_name}
INVALID_ARGUMENT {full_resource_name},不符合 //[a-z0-9.-]/.a-z0-9.-]/ 的限制。

C#

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Cloud IAM C# API 參考說明文件


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

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中操作說明設定 Go 環境。詳情請參閱 Cloud IAM Go API 參考說明文件

import (
	"context"
	"fmt"
	"io"

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

// queryTestablePermissions lists testable permissions on a resource.
func queryTestablePermissions(w io.Writer, fullResourceName string) ([]*iam.Permission, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

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

Python

嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Cloud IAM Python API 參考文件

def query_testable_permissions(resource):
    """Lists valid permissions for a resource."""

    # pylint: disable=no-member
    permissions = service.permissions().queryTestablePermissions(body={
        'fullResourceName': resource
    }).execute()['permissions']
    for p in permissions:
        print(p['name'])

取得角色中繼資料

在建立自訂角色前,您可能會想要取得預先定義角色和自訂角色的中繼資料。角色中繼資料包括角色 ID 和角色擁有的權限。您可以透過 Google Cloud Platform 主控台或 IAM API 檢視中繼資料。

如要檢視角色中繼資料,請使用以下任一方式:

主控台

  1. 前往 GCP 主控台的「Roles」(角色) 頁面。

    開啟「Roles」(角色) 頁面

  2. 在頁面頂端的下拉式選單中選取機構或專案。
  3. 選取一或多個角色的核取方塊,即可檢視角色的權限。右側面板會顯示角色擁有的權限 (如果有)。

角色旁邊的圖示表示這個角色為自訂角色 (「工廠」圖示) 或預先定義的角色 (六邊形圖示)。

Role icons

如果要尋找包含特定權限的所有角色,請在「角色」清單頂端的「篩選」方塊中輸入權限名稱。

GCLOUD 指令

只要使用 gcloud iam roles describe 指令,您就能查看預先定義角色和自訂角色的中繼資料。

如要檢視預先定義角色的中繼資料,請執行以下 gcloud 指令:

gcloud iam roles describe [ROLE-NAME]

[ROLE-NAME] 是角色名稱,例如 roles/viewer

下列範例說明在預先定義角色 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 指令:

gcloud iam roles describe --organization [ORGANIZATION-ID] [ROLE-NAME]

[ORGANIZATION-ID] 為機構 ID,格式為:1234567[ROLE-NAME] 則為自訂角色名稱,例如 myCustomRole

如要檢視專案層級自訂角色的中繼資料,請執行以下 gcloud 指令:

gcloud iam roles describe --project [PROJECT-ID] [ROLE-NAME]

[PROJECT-ID] 是專案 ID,例如 my-project-id[ROLE-NAME] 則為自訂角色名稱,例如 myCustomRole

詳情請參閱 gcloud iam roles describe 參考文件。

REST API

如果您知道要檢視角色的名稱,請使用 roles.get 方法取得自訂角色。如果您不知道角色名稱,則使用 roles.list 方法列出機構或專案中所有的自訂角色。

如要呼叫 GetRole(),,請設定以下 GetRoleRequest 內的欄位:

  • 角色名稱,例如 roles/{ROLE-NAME}organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}

如要呼叫 ListRoles(),請設定以下 ListRolesRequest 內的欄位:

  • 您希望取得所有自訂角色的父項,例如 organizations/{ORGANIZATION-ID}projects/{PROJECT-ID}

錯誤代碼

錯誤代碼 狀態訊息
PERMISSION_DENIED 您沒有權限在 {path} 中取得角色。
NOT_FOUND 找不到名稱為 {role} 的角色。
INVALID_ARGUMENT 角色名稱的格式必須為 roles/{role}organizations/{organization-id}/roles/{role}
PERMISSION_DENIED 您的權限不足,無法在 {path} 中列出角色。
INVALID_ARGUMENT 父項 {path} 無效。父項格式必須為 organizations/{organization-id} 或空白。
INVALID_ARGUMENT 角色檢視無效。

C#

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Cloud IAM C# API 參考說明文件


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

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中操作說明設定 Go 環境。詳情請參閱 Cloud IAM Go API 參考說明文件

import (
	"context"
	"fmt"
	"io"

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

// getRole gets role metadata.
func getRole(w io.Writer, name string) (*iam.Role, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	role, err := service.Roles.Get(name).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.Get: %v", err)
	}
	fmt.Fprintf(w, "Got role: %v\n", role.Name)
	for _, permission := range role.IncludedPermissions {
		fmt.Fprintf(w, "Got permission: %v\n", permission)
	}
	return role, nil
}

Python

嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Cloud IAM Python API 參考文件

def get_role(name):
    """Gets a role."""

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

建立自訂角色

如要建立自訂角色,呼叫者必須擁有 iam.roles.create 權限。根據預設,專案或機構的擁有者具備這個權限,並且能建立和管理自訂角色。

使用者 (包括機構管理員) 如果不是擁有者,就必須指派為機構角色管理員角色,或 IAM 角色管理員角色。

主控台

從頭建立建立新的自訂角色:

  1. 前往 GCP 主控台的「Roles」(角色) 頁面。

    開啟「Roles」(角色) 頁面

  2. 從「Organization」(機構) 下拉式選單中選取機構。
  3. 按一下 [建立角色]
  4. 輸入角色名稱稱號說明
  5. 按一下 [Add Permissions] (新增權限)
  6. 選取要加入角色中的權限,然後按一下 [Add Permissions] (新增權限)。使用 [All Services] (所有服務) 和 [All Types] (所有類型) 下拉式選單,根據服務及類型來篩選及選取權限。

以現有的收錄角色為基礎建立自訂角色:

  1. 前往 GCP 主控台的「Roles」(角色) 頁面。

    開啟「Roles」(角色) 頁面

  2. 從「Organization」(機構) 下拉式選單中選取機構。
  3. 選取要用來建立新自訂角色的基礎角色。
  4. 按一下 [根據選取的角色建立角色]
  5. 輸入角色名稱稱號說明
  6. 取消勾選要從角色中排除的權限。
  7. 按一下 [新增權限] 加入任何權限。
  8. 按一下 [建立]。

GCLOUD 指令

您可以使用 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] 是角色的好記稱號,例如 "Role Viewer"
  • [ROLE-DESCRIPTION] 是角色的相關簡短說明,例如 "My custom role description"
  • [LAUNCH-STAGE] 表示角色在推出生命週期中的階段,例如 ALPHABETAGA
  • includedPermissions 指定要加入自訂角色中的一或多個權限的清單,例如 - iam.roles.get

儲存 YAML 檔案,然後執行以下 gcloud 指令:

gcloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

各個預留位置值如下所述:

  • [ROLE-ID] 是角色名稱,例如 viewer
  • [PROJECT-ID] 是專案名稱,例如 my-project-id
  • [YAML_FILE-PATH] 是包含自訂角色定義的 YAML 檔案的位置路徑。

以下 YAML 檔案範例說明如何建立角色定義:

title: "Role Viewer"
description: "My custom role description."
stage: "ALPHA"
includedPermissions:
- iam.roles.get
- iam.roles.list

以下範例說明如何透過 YAML 檔案建立角色。

gcloud iam roles create viewer --project my-project-id \
--file my-role-definition.yaml

如果角色建立成功,系統會傳回以下回應:

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

透過標記建立自訂角色:

請執行以下 gcloud 指令:

gcloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--permissions [PERMISSIONS-LIST] --stage [LAUNCH-STAGE]

各個預留位置值如下所述:

  • [ROLE-ID] 是角色名稱,例如 viewer
  • [PROJECT-ID] 是專案名稱,例如 my-project-id
  • [ROLE-TITLE] 是角色的好記稱號,例如 "Role Viewer"
  • [ROLE-DESCRIPTION] 是角色的相關簡短說明,例如 "My custom role description."
  • [PERMISSIONS-LIST] 具有要加入自訂角色中並以半形逗號分隔的權限清單。例如:iam.roles.get,iam.roles.list
  • [LAUNCH-STAGE] 表示角色在推出生命週期中的階段,例如 ALPHABETAGA

以下範例說明如何透過標記建立角色:

gcloud iam roles create viewer --project my-project-id \
--title "Role Viewer" --description "My custom role description." \
--permissions iam.roles.get,iam.roles.list --stage ALPHA

如果角色建立成功,系統會傳回以下回應:

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

REST API

您可以使用 create 方法建立新的自訂角色。

請在要求中設定以下必要參數:

  • 要用於新的自訂角色的 role_id,例如 appengine.myCustomStorageAuditor
  • 自訂角色說明,例如「本角色授予列出儲存資源、資源容量及存取政策的權限」。
  • 要與這個角色建立關聯的權限清單。
  • 請注意,設定角色中的名稱欄位會導致錯誤發生。

我們建議您也設定以下選用參數:

  • 自訂角色的稱號,例如「自訂角色編輯者範例」。
  • 設定 stage 的值,像是 GA

stage 採用下列值:ALPHABETAGADEPRECATEDDISABLED

某些預先定義的角色具有已淘汰的權限,或是自訂角色中不允許的權限。如果建立自訂角色時以包含淘汰或限制權限的預先定義角色為基礎,則建立作業將會失敗。

範例

parent: '[PARENT-NAME]'
role_id: '[ROLE-ID]'
role {
    name: ''
    title: '[ROLE-TITLE]'
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})",

其中:

  • [PARENT-NAME] 是您要建立自訂角色的機構名稱,例如:organizations/0000000000000001;或是要建立自訂角色的專案 ID,例如:projects/my-project
  • [ROLE-ID] 是自訂角色的 ID,例如:appengine.myCustomStorageAuditor.
  • [ROLE-TITLE] 是角色稱號,像是 Storage Auditor
  • [ROLE-DESCRIPTION] 是角色功能說明。
  • [PERMISSION] 是您要新增至自訂角色的權限。

錯誤代碼

錯誤代碼 狀態訊息
PERMISSION_DENIED 您的權限不足,無法在 {parent} 中建立角色。
ALREADY_EXISTS {parent} 中名為 {role-id} 的角色已存在。
INVALID_ARGUMENT 父項 {parent} 無效,父項格式必須為 organizations/{organization-id}
INVALID_ARGUMENT role_id {role-id} 無效,不符合模式 {pattern}
INVALID_ARGUMENT 角色中的權限數量大於 {max} 的上限。
INVALID_ARGUMENT 角色階段 {stage} 無效。

C#

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Cloud IAM C# API 參考說明文件


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

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中操作說明設定 Go 環境。詳情請參閱 Cloud IAM Go API 參考說明文件

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	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) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	request := &iam.CreateRoleRequest{
		Role: &iam.Role{
			Title:               title,
			Description:         description,
			IncludedPermissions: permissions,
			Stage:               stage,
		},
		RoleId: name,
	}
	role, err := service.Projects.Roles.Create("projects/"+projectID, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Create: %v", err)
	}
	fmt.Fprintf(w, "Created role: %v", role.Name)
	return role, nil
}

Python

嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Cloud IAM Python API 參考文件

def create_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().create(
        parent='projects/' + project,
        body={
            'roleId': name,
            'role': {
                'title': title,
                'description': description,
                'includedPermissions': permissions,
                'stage': stage
            }
        }).execute()

    print('Created role: ' + role['name'])
    return role

編輯現有的自訂角色

讀取 - 修改 - 寫入

這是更新資源中繼資料的常見模式,以自訂角色為例:首先讀取角色的目前狀態,在本機上更新資料,然後傳送已修改的資料以供寫入。如果有兩個以上的獨立程序同時嘗試相同順序,這個模式可能會產生衝突。例如,如果專案有兩位擁有者同時嘗試對角色執行彼此衝突的變更,有些變更可能會失敗。Cloud IAM 能透過在自訂角色中使用 etag 屬性來解決這個問題。這個屬性可用於確認自訂角色自上一次要求以來是否變更。當您使用 etag 值對 Cloud IAM 提出要求時,Cloud IAM 會比較要求中的 etag 值和與自訂角色相關聯的現有 etag 值。只有在兩個 etag 值彼此相符時,系統才會執行寫入變更。

更新角色時,請先使用 roles.get() 取得角色,更新角色,然後透過 roles.patch() 寫入已更新的角色。只有在 roles.get() 中的相應角色含有 ETag 值時,您才能使用 ETag 值來設定角色。

主控台

  1. 前往 GCP 主控台的「Roles」(角色) 頁面。

    開啟「Roles」(角色) 頁面

  2. 從「Organization」(機構) 下拉式選單中選取機構。
  3. 按一下某個自訂角色。
  4. 按一下 [編輯角色]
  5. 按一下 [新增權限] 將新的權限加入角色。
  6. 取消勾選要從角色中移除的權限。
  7. 按一下 [更新] 儲存已編輯的角色。

GCLOUD 指令

您可以使用 gcloud iam roles update 指令更新自訂角色。請透過以下兩種方式使用這項指令:

  • 提供含有新版角色定義的 YAML 檔案
  • 使用標記來指定新版角色定義

更新自訂角色時,您必須使用 --organization [ORGANIZATION-ID]--project [PROJECT-ID] 標記,指定這個角色應用於機構層級還是專案層級。下列各個範例是在專案層級中建立自訂角色。

透過 YAML 檔案更新自訂角色:

請執行以下 gcloud 指令來取得角色目前的定義:

gcloud iam roles describe [ROLE-ID] --project [PROJECT-ID]

各個預留位置值如下所述:

  • [ROLE-ID] 是要更新角色的名稱,例如 viewer
  • [PROJECT-ID] 是專案名稱,例如 my-project-id

describe 指令可傳回角色定義,並包含專門用於辨識角色目前版本的 etag 值。您必須在已更新角色定義中提供 etag 值,以確保並行角色變更並未遭到覆寫。

describe 指令可傳回以下輸出:

description: [ROLE-DESCRIPTION]
etag: [ETAG-VALUE]
includedPermissions:
- [PERMISSION-1]
- [PERMISSION-2]
name: [ROLE-ID]
stage: [LAUNCH-STAGE]
title: [ROLE-TITLE]

各個預留位置值如下所述:

  • [ROLE-DESCRIPTION] 是角色的相關簡短說明,例如 "My custom role description"
  • [ETAG-VALUE] 是角色目前版本的專屬 ID,例如 BwVkBkbfr70=
  • includedPermissions 指定要加入自訂角色中的一或多個權限的清單,例如 - iam.roles.get
  • [ROLE-ID] 是角色的階層 ID,取決於角色是在專案或機構層級上建立。例如:projects/my-project-id/roles/viewer
  • [LAUNCH-STAGE] 表示角色在推出生命週期中的階段,例如 ALPHABETAGA
  • [ROLE-TITLE] 是角色的好記稱號,例如 "Role Viewer"

如要更新角色,請將輸出的角色定義加入 YAML 檔案中,或者使用輸出的 etag 值更新原始的 YAML 檔案。

請參考以下 YAML 檔案範例,其中包含 describe 指令的輸出,並新增兩個 Cloud Storage 權限:

description: My custom role description.
etag: BwVkBkbfr70=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

儲存 YAML 檔案,然後執行以下 gcloud 指令:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

各個預留位置值如下所述:

  • [ROLE-ID] 是要更新角色的名稱,例如 viewer
  • [PROJECT-ID] 是專案名稱,例如 my-project-id
  • [YAML_FILE-PATH] 為路徑,可連結至包含已更新自訂角色定義的 YAML 檔案位置。

以下範例說明如何透過 YAML 檔案來更新角色:

gcloud iam roles update viewer --project my-project-id \
--file my-role-definition.yaml

如果角色更新成功,系統會傳回以下回應:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

透過標記更新自訂角色:

您可以使用相應的標記,更新角色定義的各個部分。如需所有可用標記的清單,請參閱 gcloud iam roles update 主題。

如要新增或移除權限,請使用以下標記:

  • --add-permissions [PERMISSIONS]:為角色新增一或多個以半形逗號分隔的權限。
  • --remove-permissions [PERMISSIONS]:移除角色中一或多個以半形逗號分隔的權限。

或者,您可以透過 --permissions [PERMISSIONS] 標記指定新權限,並提供以半形逗號分隔的權限清單來取代現有的權限清單。

要更新角色定義的其他方面,請執行以下 gcloud 指令:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--stage [LAUNCH-STAGE]

各個預留位置值如下所述:

  • [ROLE-ID] 是角色名稱,例如 viewer
  • [PROJECT-ID] 是專案名稱,例如 my-project-id
  • [ROLE-TITLE] 是角色的好記稱號,例如 "Role Viewer"
  • [ROLE-DESCRIPTION] 是角色的相關簡短說明,例如 "My custom role description."
  • [LAUNCH-STAGE] 表示角色在推出生命週期中的階段,例如 ALPHABETAGA

以下範例說明如何使用標記為角色新增權限:

gcloud iam roles update viewer --project my-project-id \
--add-permissions storage.buckets.get,storage.buckets.list

如果角色更新成功,系統會傳回以下回應:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

REST API

您可以使用 Role UpdateRole(UpdateRoleRequest) 方法來編輯現有的自訂角色。

如果您知道要編輯自訂角色的角色 ID,請使用 roles.get() 方法取得這個角色,然後透過 roles.patch() 更新角色。

如果您不知道要編輯自訂角色的角色 ID,請使用 ListRoles() 列出所有角色,並找出要編輯的角色。roles.list() 會傳回參考特定資源的所有角色清單。接著請透過 roles.patch() 更新角色。

請在 roles.patch() 中設定以下必要參數:

  • 角色名稱,例如 organizations/{ORGANIZATION-ID}/roles/{ROLE-ID}

您可以選擇設定 update_mask 欄位,以指定未來開放更新的欄位。

範例

name: '[ROLE-NAME]'
role {
    name: '[ROLE-NAME]'
    title: '[ROLE-TITLE]'`
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})"

其中:

  • [ROLE-NAME] 是角色的名稱,例如 organizations/123456/roles/appengine.customRoleEditor.。 格式可為 roles/{ROLE-NAME}organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}projects/{PROJECT-ID}/roles/{ROLE-NAME}

  • [ROLE-TITLE] 是角色稱號,例如:New custom editor.

  • [ROLE-DESCRIPTION] 是角色的說明,例如「編輯者新的詳細說明」。

  • [PERMISSION] 是您要加入角色中的權限,像是 storage.objects.update

錯誤代碼

錯誤代碼 狀態訊息
PERMISSION_DENIED 您的權限不足,無法更新角色。
INVALID_ARGUMENT 預先定義角色無法更新。
INVALID_ARGUMENT 要求中的名稱 ([ROLE-NAME]) 與角色中的名稱 ([ROLE-NAME]) 必須相符。
INVALID_ARGUMENT 權限 [PERMISSION] 無效。
ABORTED 有並行政策變更,因為 etag 不相符。請使用指數輪詢重試整個讀取 - 修改 - 寫入順序。

某些預先定義的角色具有已淘汰的權限,或是自訂角色中不允許的權限。如果建立自訂角色時以包含淘汰或限制權限的預先定義角色為基礎,則建立作業將會失敗。

C#

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Cloud IAM C# API 參考說明文件


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

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中操作說明設定 Go 環境。詳情請參閱 Cloud IAM Go API 參考說明文件

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	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) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	role, err := service.Projects.Roles.Get(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Get: %v", err)
	}
	role.Title = newTitle
	role.Description = newDescription
	role.IncludedPermissions = newPermissions
	role.Stage = newStage
	role, err = service.Projects.Roles.Patch(resource, role).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Patch: %v", err)
	}
	fmt.Fprintf(w, "Updated role: %v", role.Name)
	return role, nil
}

Python

嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Cloud IAM Python API 參考文件

def edit_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'title': title,
            'description': description,
            'includedPermissions': permissions,
            'stage': stage
        }).execute()

    print('Updated role: ' + role['name'])
    return role

停用自訂角色

您可以停用自訂角色。角色停用後,與角色相關的所有政策繫結都會停用,這代表系統不會授予角色中的權限 (即使您將角色授予使用者)。

主控台

  1. 前往 GCP 主控台的「Roles」(角色) 頁面。

    開啟「Roles」(角色) 頁面

  2. 按一下頁面頂端的 [Select a project] (選取專案) 下拉式選單。
  3. 選取您的機構或專案。
  4. 選取自訂角色,再按一下 [停用]

GCLOUD 指令

您可以使用 gcloud iam roles update 指令將自訂角色的推出階段設為 DISABLED,藉此停用自訂角色。如同編輯現有的自訂角色一節中的「gcloud」分頁所述,您可以透過以下兩種方式更新現有的自訂角色:

  • 提供含有新版角色定義的 YAML 檔案
  • 使用標記來指定新版角色定義

如要停用現有自訂角色,最簡單的方式就是使用 --stage 標記,並將其設為 DISABLED。請執行以下 gcloud 指令:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--stage DISABLED

各個預留位置值如下所述:

  • [ROLE-ID] 是角色名稱,例如 viewer
  • [PROJECT-ID] 是專案名稱,例如 my-project-id。如果角色是在機構層級建立 (例如 1234567),您也可以使用 --organization [ORGANIZATION-ID] 標記。

以下範例說明如何停用角色:

gcloud iam roles update viewer --project my-project-id \
--stage DISABLED

如果角色更新成功,系統會傳回以下回應:

description: My custom role description.
etag: BwVkB5NLIQw=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: DISABLED
title: Role Viewer

REST API

您可以使用 roles.patch() 方法來停用自訂角色。

如果您知道要停用自訂角色的角色 ID,請使用 roles.get() 方法取得這個角色。將角色的 stage 屬性變更為 DISABLED,然後呼叫 roles.patch() 方法來更新角色。

如果您無法確定要停用的自訂角色 ID,請使用 roles.list() 列出所有角色並找出要停用的角色。roles.list() 會傳回與特定資源有關的完整角色清單。找出要停用的角色,將其 rolelaunchstage 屬性變更為 DISABLED,,然後呼叫 roles.patch() 方法來更新角色。

如要停用角色,請設定以下欄位:

  • 將名稱設為角色的完整名稱:organizations/{organization-id}/roles/{role}.
  • Role, 中的 stage 設為 DISABLED.
  • update_mask 設為 'paths: stage'。

如要重新啟用角色,請按照上述停用角色的程序同樣操作,但是請將角色的 stage 屬性設為 ALPHABETAGA

範例

name: 'organizations/123456/roles/appengine.customRoleEditor'
role {
    name: 'organizations/123456/roles/appengine.customRoleEditor'`
    stage: 'DISABLED'
}
update_mask {
    paths:  stage
}

錯誤代碼

錯誤代碼 狀態訊息
PERMISSION_DENIED 您的權限不足,無法更新角色。
INVALID_ARGUMENT 收錄角色無法更新。
INVALID_ARGUMENT 要求中的名稱 ([ROLE-NAME]) 與角色中的名稱 ([ROLE-NAME]) 必須相符。
INVALID_ARGUMENT 權限 [PERMISSION] 無效。
ABORTED 有並行政策變更。請使用指數輪詢重試整個讀取 - 修改 - 寫入程序。

C#

將角色的 stage 欄位更新DISABLED

Go

將角色的 stage 欄位更新DISABLED

Python

將角色的 stage 欄位更新DISABLED

列出角色

主控台

  1. 前往 GCP 主控台的「Roles」(角色) 頁面。

    開啟「Roles」(角色) 頁面


    頁面會列出專案的所有自訂角色。

GCLOUD 指令

只要使用 gcloud iam roles list 指令,您就能列出特定專案或機構的自訂角色和預先定義角色。

如要列出自訂角色,請執行以下 gcloud 指令,並指定專案層級或機構層級的自訂角色:

gcloud iam roles list --project [PROJECT-ID]

[PROJECT-ID] 是專案名稱,例如 my-project-id。如果角色是在機構層級上建立 (例如 1234567),則也可以使用 --organization [ORGANIZATION-ID] 標記。

如要列出已刪除的角色,您也可以指定 --show-deleted 標記。

如要列出預先定義角色,則執行以下 gcloud 指令:

gcloud iam roles list

REST API

您可以使用 roles.list() 方法列出特定機構或專案中定義的所有自訂角色。另外,這個方法也能將要求中的父項欄位設為 "",藉此列出預先定義的角色。

如要呼叫 roles.list(),請設定以下要求中的欄位:

  • 要用來取得所有自訂角色的父項,例如:
    • projects/{PROJECT-ID}
    • organizations/{ORGANIZATION-ID}

如果您希望結果中包含各個角色的權限,請將 view 欄位設為 RoleView::FULL

如果您希望結果中包含最近刪除的角色,請將 showDeleted 欄位設為 true

如果您希望列出所有收錄角色,請將父項設為 "" (空字串)。

錯誤代碼

錯誤代碼 狀態訊息
PERMISSION_DENIED 您的權限不足,無法在 {path} 中列出角色。
INVALID_ARGUMENT 父項 {path} 無效。父項格式必須為 organizations/{organization-id}projects/{project-id} 或空白。
INVALID_ARGUMENT 角色檢視無效。

C#

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Cloud IAM C# API 參考說明文件


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

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中操作說明設定 Go 環境。詳情請參閱 Cloud IAM Go API 參考說明文件

import (
	"context"
	"fmt"
	"io"

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

// listRoles lists a project's roles.
func listRoles(w io.Writer, projectID string) ([]*iam.Role, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

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

Python

嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Cloud IAM Python API 參考文件

def list_roles(project_id):
    """Lists roles."""

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

刪除自訂角色

主控台

  1. 前往 GCP 主控台的「Roles」(角色) 頁面。

    開啟「Roles」(角色) 頁面

  2. 選取要刪除的角色,然後按一下頁面頂端的垃圾桶圖示。

GCLOUD 指令

您可以使用 gcloud iam roles delete 指令刪除自訂角色。角色會遭到暫停,且無法用於建立新的 IAM 政策繫結。

如要刪除自訂角色,則執行以下 gcloud 指令:

gcloud iam roles delete [ROLE-ID] --project [PROJECT-ID]

各個預留位置值如下所述:

  • [ROLE-ID] 是角色名稱,例如 viewer
  • [PROJECT-ID] 是專案名稱,例如 my-project-id。如果角色是在機構層級建立 (例如 1234567),您也可以使用 --organization [ORGANIZATION-ID] 標記。

除非指令含有 --show-deleted 標記,否則這個角色不會包含在 gcloud iam roles list 中。在 list 回應中,已刪除的角色會以 deleted: true 區塊表示,例如:

---
deleted: true
description: My custom role description.
etag: BwVkB5NLIQw=
name: projects/my-project-id/roles/viewer
title: Role Viewer
---

REST API

roles.delete 會刪除角色。角色會遭到暫停,且無法用於建立新的 IAM 政策繫結。

name 可為以下格式

  • organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
  • projects/{PROJECT-ID}/roles/{ROLE-NAME}

錯誤代碼

錯誤代碼 狀態訊息
PERMISSION_DENIED 您的權限不足,無法在 {path} 中刪除角色。
FAILED_PRECONDITION 無法刪除角色 {ROLE-NAME},因為這個角色已經刪除。
FAILED_PRECONDITION 無法刪除已保留的角色 {ROLE-NAME}
INVALID_ARGUMENT 收錄角色無法處於刪除的狀態。

C#

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Cloud IAM C# API 參考說明文件


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

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中操作說明設定 Go 環境。詳情請參閱 Cloud IAM Go API 參考說明文件

import (
	"context"
	"fmt"
	"io"

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

// deleteRole deletes a custom role.
func deleteRole(w io.Writer, projectID, name string) error {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return fmt.Errorf("iam.New: %v", err)
	}

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

Python

嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Cloud IAM Python API 參考文件

def delete_role(name, project):
    """Deletes a role."""

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

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

角色遭到刪除後,其繫結仍會存在,但處於停用狀態。如有需要,您可以在 7 天內取消刪除角色。在 7 天期間內,GCP Console 會將角色顯示為「Deleted」(已刪除)。您透過程式使用 list 指令時,系統也不會顯示該角色 (除非您在要求中設定 showDeleted)。

7 天後,系統就會排定永久刪除該角色的時間。此程序需要 30 天時間。在 30 天期間內,角色及所有相關繫結將永久移除,您無法再以相同的角色 ID 建立新角色。

角色永久刪除後,您可在初始刪除要求的 37 天後,使用相同角色 ID 建立新角色。

取消刪除自訂角色

主控台

  1. 前往 GCP 主控台的「Roles」(角色) 頁面。

    開啟「Roles」(角色) 頁面

  2. 找出要取消刪除的角色,按一下資料列結尾的「更多」圖示,然後點選 [Undelete] (取消刪除)

角色只能在刪除後的 7 天內取消刪除。7 天後,系統就會永久刪除這個角色,並移除與角色相關聯的所有繫結。

GCLOUD 指令

您可以使用 gcloud iam roles undelete 指令取消刪除自訂角色。取消刪除角色後,這個角色將返回先前狀態。

角色只能在刪除後的 7 天內取消刪除。7 天後,系統就會永久刪除這個角色,並移除與角色相關聯的所有繫結。

如要取消刪除自訂角色,則執行以下 gcloud 指令:

gcloud iam roles undelete [ROLE-ID] --project [PROJECT-ID]

各個預留位置值如下所述:

  • [ROLE-ID] 是角色名稱,例如 viewer
  • [PROJECT-ID] 是專案名稱,例如 my-project-id。如果角色是在機構層級建立 (例如 1234567),您也可以使用 --organization [ORGANIZATION-ID] 標記。

以下範例說明如何取消刪除自訂角色:

gcloud iam roles undelete viewer --project my-project-id

如果角色取消刪除成功,系統會傳回以下回應:

description: My custom role description.
etag: BwVkCAx9W6w=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

REST API

roles.undelete 可將角色復原為先前的狀態。

name 可為以下格式

  • organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
  • projects/{PROJECT-ID}/roles/{ROLE-NAME}

角色只能在刪除後的 7 天內取消刪除。7 天後,系統就會永久刪除這個角色,並移除與角色相關聯的所有繫結。

錯誤代碼

錯誤代碼 狀態訊息
PERMISSION_DENIED 您的權限不足,無法在 {path} 中取消刪除角色。
FAILED_PRECONDITION 未刪除的角色無法取消刪除。
FAILED_PRECONDITION 您無法取消刪除保留的角色 {ROLE-NAME}
INVALID_ARGUMENT 預先定義的角色無法取消刪除。

C#

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 C# 環境。詳情請參閱 Cloud IAM C# API 參考說明文件


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

在嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中操作說明設定 Go 環境。詳情請參閱 Cloud IAM Go API 參考說明文件

import (
	"context"
	"fmt"
	"io"

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

// undeleteRole restores a deleted custom role.
func undeleteRole(w io.Writer, projectID, name string) (*iam.Role, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	request := &iam.UndeleteRoleRequest{}
	role, err := service.Projects.Roles.Undelete(resource, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Undelete: %v", err)
	}
	fmt.Fprintf(w, "Undeleted role: %v", role.Name)
	return role, nil
}

Python

嘗試這個範例之前,請先按照 Cloud IAM 快速入門:使用用戶端程式庫中的操作說明設定 Python 環境。詳情請參閱 Cloud IAM Python API 參考文件

def undelete_role(name, project):
    """Undeletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'stage': 'DISABLED'
        }).execute()

    print('Disabled role: ' + role['name'])
    return role

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Cloud IAM 說明文件