カスタムロールの作成と管理

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 メソッドと URL:

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

API Explorer（ブラウザ）

リクエスト本文をコピーして、メソッドのリファレンス ページを開きます。ページの右側に [API 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 コンソールで、[ロール] ページに移動します。

   [ロール] に移動

2. ページの上部にあるプルダウン リストから組織またはプロジェクトを選択します。

3. 1 つ以上のロールのチェックボックスを選択して、ロールの権限を表示します。ロールに含まれている権限があれば、右側のパネルに表示されます。

タイプ列のアイコンは、カスタムロール（「工場」のアイコン）か、事前定義ロール（六角形のアイコン）かを示しています。

特定の権限を含むロールをすべて検索するには、[ロール] リストの上部にある [フィルタ] ボックスに権限名を入力します。

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 など）。

   次の例に、describe が事前定義ロール roles/iam.roleViewer で実行された場合の出力の例を示します。

   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 メソッドと URL:

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

API Explorer（ブラウザ）

メソッドのリファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。必須フィールドを入力して、[Execute] をクリックします。

レスポンスにはロールの定義が含まれます。

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

Console

「プロジェクト レベルのカスタムロールに適用できません」という警告メッセージが表示されます。対象の権限リストから権限が自動的に削除され、ロールの作成に進むことができます。

gcloud

INVALID_ARGUMENT: Permission PERMISSION is not valid というエラー メッセージが返されます。ロールの定義から権限を削除して操作をやり直すまで、カスタムロールは作成されません。

REST API

エラー メッセージ Permission PERMISSION is not valid が返され、HTTP 400 エラーコードとステータス INVALID_ARGUMENT が返されます。ロールの定義から権限を削除して操作をやり直すまで、カスタムロールは作成されません。

Console

一部の事前定義ロールには、サポートが終了した権限や、カスタムロールでは許可されない権限が含まれています。そのような事前定義ロールをに基づいてカスタムロールを作成する場合、サポートが終了した権限、制限されている権限はカスタムロールから省略されます。

最初から新しいカスタムロールを作成するには:

1. Google Cloud コンソールで、[ロール] ページに移動します。

   [ロール] に移動

2. ページの上部にあるプルダウン リストを使用して、ロールを作成する組織またはプロジェクトを選択します。

3. [ロールを作成] をクリックします。

4. ロールのタイトル、説明、ID、ロールのリリース段階を入力します。ロールの作成後にロール ID を変更することはできません。

5. [権限を追加] をクリックします。

6. ロールに含める権限を選択し、[権限を追加] をクリックします。[すべてのサービス] と [すべての種類] プルダウン リストを使用して、サービスと種類別に権限をフィルタリングして選択します。

既存の事前定義ロールに基づいてカスタムロールを作成するには:

1. Google Cloud コンソールで、[ロール] ページに移動します。

   [ロール] に移動

2. ロールを作成する組織またはプロジェクトを選択します。
3. 新しいカスタムロールのベースにするロールを選択します。
4. [選択内容からロールを作成] をクリックします。
5. ロールのタイトル、説明、ID、ロールのリリース段階を入力します。ロールの作成後にロール ID を変更することはできません。
6. ロールから除外する権限のチェックボックスをオフにします。
7. [権限を追加] をクリックして権限を追加します。
8. [作成] をクリックします。

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. gcloud iam roles create を使用して、新しいカスタムロールを作成します。このコマンドは次の 2 つの方法で使用できます。

   • ロール定義が含まれる 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 メソッドと URL:

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

API Explorer（ブラウザ）

リクエスト本文をコピーして、メソッドのリファレンス ページを開きます。ページの右側に [API 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 コンソールで、[ロール] ページに移動します。

   [ロール] に移動

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 を使用して、カスタムロールを更新します。このコマンドは次の 2 つの方法で使用できます。

   • 更新されたロール定義が含まれる YAML ファイルを使用する

   • フラグを使用して、更新されたロール定義を指定する

   カスタムロールを更新する場合は、--organization=ORGANIZATION_ID フラグまたは --project=PROJECT_ID フラグを使用して、組織レベルとプロジェクト レベルのどちらでロールを適用するのかを指定する必要があります。以下の各例では、プロジェクト レベルでカスタムロールを作成します。

   YAML ファイルを使用してカスタムロールを更新するには:

   次のいずれかのコマンドを実行して、ロールの現在の定義を取得します。

   • 組織レベルのカスタムロールのロール定義を取得するには、次のコマンドを実行します。

     gcloud iam roles describe ROLE_ID --organization=ORGANIZATION_ID

   • プロジェクト レベルのカスタムロールのロール定義を取得するには、次のコマンドを実行します。

     gcloud iam roles describe ROLE_ID --project=PROJECT_ID

   各プレースホルダ値についての説明は次のとおりです。

   • ROLE_ID は、更新するロールの名前です（myCompanyAdmin など）。

   • ORGANIZATION_ID は組織の数値 ID です（123456789012 など）。

   • PROJECT_ID はプロジェクトの名前です（my-project など）。

   describe コマンドはロール定義を返し、その定義にはロールの現在のバージョンを一意に特定する etag 値が含まれます。ロールの同時変更が上書きされないように、更新されたロール定義に etag 値を指定する必要があります。

   describe コマンドは、次の出力を返します。

   description: ROLE_DESCRIPTION
   etag: ETAG
   includedPermissions:
   - PERMISSION_1
   - PERMISSION_2
   name: ROLE_NAME
   stage: LAUNCH_STAGE
   title: ROLE_TITLE

   各プレースホルダ値についての説明は次のとおりです。

   • ROLE_DESCRIPTION は、ロールに関する簡単な説明です（"My custom role description" など）。

   • ETAG は、ロールの現在のバージョンの固有識別子です（BwVkBkbfr70= など）。

   • PERMISSION_1 と PERMISSION_2 は、iam.roles.get などのカスタムロールに含める権限です。権限名にワイルドカード文字（*）は使用できません。

   • ROLE_NAME は、organizations/、projects/、roles/ のいずれかの接頭辞を含む完全なロール名です。例: organizations/123456789012/roles/myCompanyAdmin.

   • LAUNCH_STAGE は、リリースのライフサイクルにおけるロールの段階を示します（ALPHA、BETA、GA など）。

   • ROLE_TITLE は、ロールのわかりやすいタイトルです（"My Company Admin" など）。

   ロールを更新するには、出力されたロール定義を YAML ファイルに含めるか、または元の YAML ファイルを出力された etag 値で更新します。

   次の YAML ファイルの例では、プロジェクト レベルのロールの describe コマンドからの出力が含まれ、2 つの 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: ロールのバージョンの識別子。他のロールの変更を上書きしないようにするには、このフィールドを指定します。

省略可（以下の値を 1 つ以上定義します）:

• 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 メソッドと URL:

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

API Explorer（ブラウザ）

リクエスト本文をコピーして、メソッドのリファレンス ページを開きます。ページの右側に [API 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 コンソールで、[ロール] ページに移動します。

   [ロール] に移動

2. ページの上部にある [プロジェクトを選択] プルダウン リストをクリックします。

3. 組織またはプロジェクトを選択します。

4. カスタムの役割を選択し、[無効] をクリックします。

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. gcloud iam roles update コマンドを使用して、開始ステージを DISABLED に設定し、カスタムロールを無効にします。

   既存のカスタムロールの編集の gcloud タブで説明されているように、次の 2 つの方法で既存のカスタムロールを更新できます。

   • 更新されたロール定義が含まれる 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: ロールのバージョンの識別子。他のロールの変更を上書きしないようにするには、このフィールドを指定します。

HTTP メソッドと URL:

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

API Explorer（ブラウザ）

リクエスト本文をコピーして、メソッドのリファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

次のような JSON レスポンスが返されます。

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

コンソール

Google Cloud コンソールで、[ロール] ページに移動します。

[ロール] に移動

選択した組織またはプロジェクトのすべてのカスタムロールが一覧表示されます。

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. gcloud iam roles list コマンドを使用して、プロジェクトまたは組織のカスタムロールと事前定義ロールを一覧表示します。

   • 組織レベルのカスタムロールを一覧表示するには、次のコマンドを実行します。

     gcloud iam roles list --organization=ORGANIZATION_ID

   • プロジェクト レベルのカスタムロールを一覧表示するには、次のコマンドを実行します。

     gcloud iam roles list --project=PROJECT_ID

   各プレースホルダ値についての説明は次のとおりです。

   • ORGANIZATION_ID は組織の数値 ID です（123456789012 など）。

   • PROJECT_ID はプロジェクトの名前です（my-project など）。

   削除されたロールを一覧表示するには、--show-deleted フラグを指定します。

   次のコマンドを実行して、事前定義ロールを一覧表示します。

   gcloud iam roles list

C++

IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C++ API のリファレンス ドキュメントをご覧ください。

IAM で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、始める前にをご覧ください。

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& project) {
  iam::IAMClient client(iam::MakeIAMConnection());
  int count = 0;
  google::iam::admin::v1::ListRolesRequest request;
  request.set_parent(project);
  for (auto& role : client.ListRoles(request)) {
    if (!role) throw std::move(role).status();
    std::cout << "Roles successfully retrieved: " << role->name() << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No roles found in project: " << project << "\n";
  }
}

C#

IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C# API のリファレンス ドキュメントをご覧ください。

IAM で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、始める前にをご覧ください。

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

public partial class CustomRoles
{
    public static IList<Role> ListRoles(string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var response = service.Projects.Roles.List("projects/" + projectId)
            .Execute();
        foreach (var role in response.Roles)
        {
            Console.WriteLine(role.Name);
        }
        return response.Roles;
    }
}

Go

IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Go API のリファレンス ドキュメントをご覧ください。

IAM で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、始める前にをご覧ください。

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Java API のリファレンス ドキュメントをご覧ください。

IAM で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、始める前にをご覧ください。

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

/** List roles in a project. */
public class ListRoles {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    String projectId = "your-project-id";

    listRoles(projectId);
  }

  public static void listRoles(String projectId) throws IOException {
    ListRolesRequest listRolesRequest =
        ListRolesRequest.newBuilder().setParent("projects/" + projectId).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      ListRolesPagedResponse listRolesResponse = iamClient.listRoles(listRolesRequest);
      listRolesResponse.iterateAll().forEach(role -> System.out.println(role));
    }
  }
}

Python

IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM Python API のリファレンス ドキュメントをご覧ください。

IAM で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、始める前にをご覧ください。

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


def list_roles(
    project_id: str, show_deleted: bool = True, role_view: RoleView = RoleView.BASIC
) -> ListRolesPager:
    """Lists IAM roles in a GCP project.

    Args:
        project_id: GCP project ID
        show_deleted: Whether to include deleted roles in the results
        role_view: Level of detail for the returned roles (e.g., BASIC or FULL)

    Returns: A pager for traversing through the roles
    """

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

REST

roles.list メソッドを使用すると、プロジェクトまたは組織内のすべてのカスタムロールの一覧を取得できます。

リクエストのデータを使用する前に、次のように置き換えます。

• RESOURCE_TYPE: カスタムロールを管理するリソースタイプ。値 projects または organizations を使用します。
• RESOURCE_ID: カスタムロールを管理するプロジェクト ID または組織 ID。プロジェクト ID は英数字からなる文字列です（例: my-project）。組織 ID は数値で指定します（例: 123456789012）。
• ROLE_VIEW: 省略可。返されるロールに含める情報。ロールの権限を含めるには、このフィールドを FULL に設定します。ロールの権限を除外するには、このフィールドを BASIC に設定します。デフォルト値は BASIC です。
• PAGE_SIZE: 省略可。レスポンスに含めるロールの数。デフォルト値は 300、最大値は 1,000 です。ロールの数がページサイズよりも大きい場合、レスポンスには、次の結果ページを取得するために使用するページ設定トークンが含まれます。
• NEXT_PAGE_TOKEN: 省略可。以前のレスポンスでこのメソッドから返されたページ設定トークン。指定すると、前のリクエストが終了した時点からロールのリストが開始します。

HTTP メソッドと URL:

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

API Explorer（ブラウザ）

メソッドのリファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。必須フィールドを入力して、[Execute] をクリックします。

次のような JSON レスポンスが返されます。

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

コンソール

1. Google Cloud コンソールで、[ロール] ページに移動します。

   [ロール] に移動

2. 削除するロールを選択して、ページの上部にある delete（削除）をクリックします。

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. gcloud iam roles delete コマンドを使用して、カスタムロールを削除します。

   • 組織レベルのカスタムロールを削除するには、次のコマンドを実行します。

     gcloud iam roles delete ROLE_ID --organization=ORGANIZATION_ID

   • プロジェクト レベルのカスタムロールを削除するには、次のコマンドを実行します。

     gcloud iam roles delete ROLE_ID --project=PROJECT_ID

   各プレースホルダ値についての説明は次のとおりです。

   • ROLE_ID はロールの名前です（myCompanyAdmin など）。

   • ORGANIZATION_ID は組織の数値 ID です（123456789012 など）。

   • PROJECT_ID はプロジェクトの名前です（my-project など）。

   --show-deleted フラグが含まれていない場合は、gcloud iam roles list にロールが含まれません。削除されたロールは、次のように、list レスポンスの deleted: true ブロックに示されます。

   ---
   deleted: true
   description: My custom role description.
   etag: BwVkB5NLIQw=
   name: projects/my-project/roles/myCompanyAdmin
   title: My Company Admin
   ---
   

C++

IAM のクライアント ライブラリをインストールして使用する方法については、IAM クライアント ライブラリをご覧ください。詳細については、IAM C++ API のリファレンス ドキュメントをご覧ください。

IAM で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、始める前にをご覧ください。

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::DeleteRoleRequest request;
  request.set_name(name);
  auto response = client.DeleteRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully deleted: " << response->DebugString()
            << "\n";
}

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 メソッドと URL:

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

API Explorer（ブラウザ）

メソッドのリファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。必須フィールドを入力して、[Execute] をクリックします。

レスポンスには、削除されたロールの定義が含まれます。

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