建立及管理自訂角色

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 進行驗證，請設定應用程式預設憑證。 詳情請參閱「事前準備」。

import os
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.
    permissions: List of permissions to get.
    """

    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，最大值為 1,000。如果權限數量大於頁面大小，回應會包含分頁符記，可用於擷取下一頁結果。
• NEXT_PAGE_TOKEN：選用。這個方法先前回應中傳回的分頁符記。如果指定，可測試的權限清單會從前一個回應結束的位置開始。

HTTP 方法和網址：

POST https://iam.googleapis.com/v1/permissions:queryTestablePermissions

JSON 要求主體：

{
  "fullResourceName": "FULL_RESOURCE_NAME"
  "pageSize": PAGE_SIZE,
  "pageToken": "NEXT_PAGE_TOKEN"
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/permissions:queryTestablePermissions"

PowerShell (Windows)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/permissions:queryTestablePermissions" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求主體貼到這項工具中，並完成其他必填欄位，然後按一下「Execute」(執行)。

回覆會包含權限清單。

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

控制台

1. 前往 Google Cloud 控制台的「Roles」(角色) 頁面。

   前往「Roles」(角色) 頁面

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 as exc:
        raise NotFound(f"Role with id [{role_id}] not found, take some actions") from exc

REST

roles.get 方法會取得角色的定義。

使用任何要求資料之前，請先替換以下項目：

• ROLE_NAME：完整角色名稱，包括任何 organizations/、projects/ 或 roles/ 前置字串。例如：organizations/123456789012/roles/myCompanyAdmin。

HTTP 方法和網址：

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

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

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

PowerShell (Windows)

執行下列指令：

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

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

APIs Explorer (瀏覽器)

開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

回覆會包含角色定義。

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

控制台

顯示以下警告訊息：「不適用於專案層級的自訂角色」。系統會自動從所含權限清單中取消選取該權限，您可以繼續建立角色。

gcloud

系統會傳回下列錯誤訊息：INVALID_ARGUMENT: Permission PERMISSION is not valid。您必須先從角色定義中移除權限，然後再次嘗試執行作業，系統才會建立自訂角色。

REST API

系統會傳回下列錯誤訊息：Permission PERMISSION is not valid，以及 HTTP 400 錯誤代碼和 INVALID_ARGUMENT 狀態。您必須先從角色定義中移除權限，然後再次嘗試操作，才能建立自訂角色。

控制台

某些預先定義的角色具有已淘汰的權限，或是自訂角色中不允許的權限。如果您嘗試以其中一個預先定義的角色為基礎建立自訂角色，自訂角色會省略已淘汰和受限的權限。

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

1. 前往 Google Cloud 控制台的「Roles」(角色) 頁面。

   前往「Roles」(角色) 頁面

2. 使用頁面頂端的下拉式清單，選取要建立角色的機構或專案。

3. 按一下「建立角色」。

4. 輸入角色的「標題」、「說明」、「ID」和「角色推出階段」。角色建立後即無法變更角色 ID。

5. 按一下 [Add Permissions] (新增權限)。

6. 選取要加入角色中的權限，然後按一下 [Add Permissions] (新增權限)。使用「所有服務」和「所有類型」下拉式清單，根據服務和類型篩選及選取權限。

以現有的預先定義角色為基礎建立自訂角色：

1. 前往 Google Cloud 控制台的「Roles」(角色) 頁面。

   前往「Roles」(角色) 頁面

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 (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles"

PowerShell (Windows)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求主體貼到這項工具中，並完成其他必填欄位，然後按一下「Execute」(執行)。

回應會包含您建立的角色。

{
  "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 控制台的「Roles」(角色) 頁面。

   前往「Roles」(角色) 頁面

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 是角色目前版本的專屬 ID，例如 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: organizations/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：角色版本的 ID。 請加入這個欄位，避免覆寫其他角色變更。

選用 (定義下列一或多個值)：

• ROLE_TITLE：使用者可自然閱讀的角色名稱。例如：My Company Admin。
• ROLE_DESCRIPTION：角色的說明。例如："The company admin role allows company admins to access important resources"。
• PERMISSION_1 和 PERMISSION_2：要加入角色中的權限。例如，storage.objects.update。權限名稱不得使用萬用字元 (*)。
• LAUNCH_STAGE：角色的目前發布階段。這個欄位可包含下列任一值：EAP、ALPHA、BETA、GA、DEPRECATED 或 DISABLED。

HTTP 方法和網址：

PATCH https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles

JSON 要求主體：

{
  "roleId": "ROLE_NAME",
  "title": "ROLE_TITLE",
  "description": "ROLE_DESCRIPTION",
  "includedPermissions": [
    "PERMISSION_1",
    "PERMISSION_2"
  ],
  "stage": "LAUNCH-STAGE",
  "etag": "ETAG"
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles"

PowerShell (Windows)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求主體貼到這項工具中，並完成其他必填欄位，然後按一下「Execute」(執行)。

回應會包含簡短的角色定義，包括角色名稱、您更新的欄位，以及用於識別角色目前版本的 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 控制台的「Roles」(角色) 頁面。

   前往「Roles」(角色) 頁面

2. 按一下頁面頂端的「Select a project」下拉式選單。

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: organizations/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.api_core.exceptions import NotFound
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 as exc:
        raise NotFound(f'Role with id [{role_id}] not found, take some actions') from exc

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：角色版本的 ID。 請加入這個欄位，避免覆寫其他角色變更。

HTTP 方法和網址：

PATCH https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles

JSON 要求主體：

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

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles"

PowerShell (Windows)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求主體貼到這項工具中，並完成其他必填欄位，然後按一下「Execute」(執行)。

您應該會收到如下的 JSON 回應：

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

控制台

前往 Google Cloud 控制台的「Roles」(角色) 頁面。

前往「Roles」(角色) 頁面

頁面會列出您所選機構或專案的所有自訂角色。

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，最大值為 1,000。如果角色數量大於頁面大小，回應會包含分頁符記，可用於擷取下一頁結果。
• 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 (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN"

PowerShell (Windows)

執行下列指令：

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

您應該會收到如下的 JSON 回應：

{
  "roles": [
    {
      "name": "projects/my-project/roles/customRole1",
      "title": "First Custom Role",
      "description": "Created on: 2020-06-01",
      "etag": "BwWiPg2fmDE="
    },
    {
      "name": "projects/my-project/roles/customRole2",
      "title": "Second Custom Role",
      "description": "Created on: 2020-06-07",
      "etag": "BwWiuX53Wi0="
    }
  ]
}

控制台

1. 前往 Google Cloud 控制台的「Roles」(角色) 頁面。

   前往「Roles」(角色) 頁面

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

C#

如要瞭解如何安裝及使用 IAM 的用戶端程式庫，請參閱 IAM 用戶端程式庫。 詳情請參閱 IAM C# API 參考說明文件。

如要向 IAM 進行驗證，請設定應用程式預設憑證。 詳情請參閱「事前準備」。

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static void DeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        service.Projects.Roles.Delete(
            $"projects/{projectId}/roles/{name}").Execute();
        Console.WriteLine("Deleted role: " + name);
    }
}

Go

如要瞭解如何安裝及使用 IAM 的用戶端程式庫，請參閱 IAM 用戶端程式庫。 詳情請參閱 IAM Go API 參考說明文件。

如要向 IAM 進行驗證，請設定應用程式預設憑證。 詳情請參閱「事前準備」。

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

如要瞭解如何安裝及使用 IAM 的用戶端程式庫，請參閱 IAM 用戶端程式庫。 詳情請參閱 IAM Java API 參考說明文件。

如要向 IAM 進行驗證，請設定應用程式預設憑證。 詳情請參閱「事前準備」。

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

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

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

    deleteRole(projectId, roleId);
  }

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

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

Python

如要瞭解如何安裝及使用 IAM 的用戶端程式庫，請參閱 IAM 用戶端程式庫。 詳情請參閱 IAM Python API 參考說明文件。

如要向 IAM 進行驗證，請設定應用程式預設憑證。 詳情請參閱「事前準備」。

from google.api_core.exceptions import FailedPrecondition, NotFound
from google.cloud.iam_admin_v1 import (
    DeleteRoleRequest,
    IAMClient,
    Role,
    UndeleteRoleRequest,
)
def delete_role(project_id: str, role_id: str) -> Role:
    """Deletes iam role in GCP project. Can be undeleted later.
    Args:
        project_id: GCP project id
        role_id: id of GCP iam role

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = DeleteRoleRequest(name=name)
    try:
        role = client.delete_role(request)
        print(f"Deleted role: {role_id}: {role}")
        return role
    except NotFound:
        print(f"Role with id [{role_id}] not found, take some actions")
    except FailedPrecondition as err:
        print(f"Role with id [{role_id}] already deleted, take some actions)", err)

REST

roles.delete 方法會刪除專案或機構中的自訂角色。

使用任何要求資料之前，請先替換以下項目：

• ROLE_NAME：完整角色名稱，包括任何 organizations/、projects/ 或 roles/ 前置字串。例如：organizations/123456789012/roles/myCompanyAdmin。

HTTP 方法和網址：

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

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

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

PowerShell (Windows)

執行下列指令：

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

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

APIs Explorer (瀏覽器)

開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

回應會包含已刪除的角色定義。

{
  "name": "projects/my-project/roles/myCompanyAdmin",
  "title": "My Company Admin",
  "description": "My custom role description.",
  "includedPermissions": [
    "iam.roles.get",
    "iam.roles.list"
  ],
  "etag": "BwWiPg2fmDE=",
  "deleted": true
}