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

このページでは、カスタムロールを作成および管理する方法について説明します。

始める前に

  • カスタムロールの作成に必要な権限とベスト プラクティスに関する情報を含む IAM のカスタムロールについてをお読みください。
  • gcloud コマンドライン ユーティリティを使用する場合は、バージョン 188.0.0 以降を使用していることを確認してください。gcloud をバージョン 188.0.0 に更新するには、gcloud components update --version 188.0.0 コマンドを実行します。

リソースで使用可能な権限の表示

カスタムロールを作成する前に、リソースに適用できる権限を確認する必要がある場合があります。リソースとその下位にあるリソースに適用可能な権限を確認するには、gcloud コマンドライン ツール、Cloud Console または IAM API を使用します。たとえば、組織と組織内のプロジェクトに適用できるすべての権限を確認できます。

Console

  1. Cloud Console の [ロール] ページに移動します。

    [ロール] ページを開く

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

  3. リソースの管理者ロールのチェックボックスを選択して、このリソースに適用可能なすべての権限を表示します。たとえば、Compute インスタンス管理者ロールを選択すると、Compute Engine インスタンスに適用可能なすべての権限が右側のパネルに表示されます。

gcloud コマンド

gcloud iam list-testable-permissions コマンドを使用して、対象のリソースに適用可能な権限のリストを取得します。返される権限は、このリソースおよび階層内でそれより下のリソースに対してカスタムロールを作成するのに使用できる権限です。

次の例では、プロジェクト リソースに対してテスト可能な権限を一覧表示する方法を示します。

gcloud iam list-testable-permissions project-id

project-id はプロジェクトの ID です。リソース名の完全名(//cloudresourcemanager.googleapis.com/projects/project-id)の形式で指定します。(例: //cloudresourcemanager.googleapis.com/projects/my-project-id

list-testable-permissions コマンドから何百もの結果が返されることがあります。結果数を制限するために、フィルタ式を指定することもできます。次に、結果が短縮された例を示します。

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

各権限は、カスタムロールでサポートされるかどうかを示すことに注意してください。サポートされる権限とサポートされない権限の完全なリストについては、カスタムロールの権限のサポートをご覧ください。

REST API

QueryTestablePermissions は、リソースに適用できるすべての権限を返します。返される権限は、このリソースおよび階層内でそれより下のリソースに対してカスタムロールを作成するのに使用できる権限です。リクエストに必要なパラメータは、//cloudresourcemanager.googleapis.com/projects/my-project などの完全なリソース名のみです。

リソースに権限の長いリストが含まれる場合、呼び出し元は、必要に応じてページ設定のサポートを提供できます。

{
  "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/my-project"
}

エラーコード

エラーコード ステータス メッセージ
INVALID_ARGUMENT 0〜100 の値にする必要があります。
INVALID_ARGUMENT ページ設定トークンのエンコードが無効です。
INVALID_ARGUMENT ページ設定トークンが無効です。
INVALID_ARGUMENT ページ設定トークンが、指定されたコンテナ用ではありません。
INVALID_ARGUMENT ページ設定トークンの開始点が無効です。
INVALID_ARGUMENT ページ設定トークンの Cookie が無効です。
INVALID_ARGUMENT ページ設定トークンの期限が切れています。
INVALID_ARGUMENT フィールド full_resource_name を指定する必要があります。
INVALID_ARGUMENT フィールド full_resource_namefull-resource-name)が無効です。//[a-z0-9\\.\\-]+/.+. と一致しません。

C#

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている C# 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM C# API のリファレンス ドキュメントをご覧ください。


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

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

        var request = new QueryTestablePermissionsRequest
        {
            FullResourceName = fullResourceName
        };
        var response = service.Permissions.QueryTestablePermissions(request)
            .Execute();
        foreach (var p in response.Permissions)
        {
            Console.WriteLine(p.Name);
        }
        return response.Permissions;
    }
}

Go

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Go 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Go API のリファレンス ドキュメントをご覧ください。

import (
	"context"
	"fmt"
	"io"

	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: %v", err)
	}

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

Python

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Python 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Python API のリファレンス ドキュメントをご覧ください。

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

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

ロール メタデータの取得

カスタムロールを作成する前に、事前定義ロールとカスタムロールの両方のメタデータを取得する必要がある場合があります。ロール メタデータには、そのロールの ID と権限が含まれます。メタデータを表示するには、Google Cloud Platform Console または IAM API を使用します。

ロール メタデータを表示するには、次のいずれかの方法で行います。

Console

  1. Cloud Console の [ロール] ページに移動します。

    [ロール] ページを開く

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

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

タイプ列のアイコンは、カスタムロールか、事前定義ロールかを示しています。

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

gcloud コマンド

gcloud iam roles describe コマンドを使用して、事前定義ロールとカスタムロールのメタデータを表示します。

事前定義ロールのメタデータを表示するには、gcloud コマンドを実行します。

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 コマンドを実行します。

  • 組織レベルで作成されたカスタムロールのメタデータを表示するには、次のコマンドを実行します。

    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-id など)。
  • role-id はロールの ID です。projects/organizations/roles/ などの接頭辞は含まれません。(例: myCompanyAdmin

詳しくは、gcloud iam roles describe のリファレンス ドキュメントをご覧ください。

REST API

表示するロールのロール名がわかっている場合は、roles.get メソッドを使用してカスタムロールを取得します。ロール名がわからない場合は、roles.list メソッドを使用して、組織やプロジェクト内のすべてのカスタムロールを一覧表示します。

GetRole(), を呼び出すには、GetRoleRequest に次のフィールドを設定します。

  • ロールの名前(roles/role-idorganizations/organization-id/roles/role-id など)。

ListRoles() を呼び出すには、ListRolesRequest に次のフィールドを設定します。

  • すべてのカスタムロールを取得する親(organizations/organization-idprojects/project-id など)。

エラーコード

エラーコード ステータス メッセージ
PERMISSION_DENIED path でロールを取得する権限がありません。
NOT_FOUND role という名前のロールが見つかりませんでした。
INVALID_ARGUMENT ロール名は、roles/role または organizations/organization-id/roles/role の形式で指定してください。
PERMISSION_DENIED path のロールを一覧表示する権限がありません。
INVALID_ARGUMENT path が無効です。親は「organizations/{organization_id}」、「projects/{project_id}」、または空の形式にする必要があります。
INVALID_ARGUMENT ロールビューが無効です。

C#

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている C# 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM C# API のリファレンス ドキュメントをご覧ください。


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

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

        var role = service.Roles.Get(name).Execute();
        Console.WriteLine(role.Name);
        Console.WriteLine(String.Join(", ", role.IncludedPermissions));
        return role;
    }
}

Go

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Go 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Go API のリファレンス ドキュメントをご覧ください。

import (
	"context"
	"fmt"
	"io"

	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: %v", err)
	}

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

Python

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Python 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Python API のリファレンス ドキュメントをご覧ください。

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

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

カスタムロールの作成

カスタムロールは、プロジェクト レベルまたは組織レベルで作成できます。

カスタムロールを作成するには、呼び出し元が iam.roles.create 権限を所有している必要があります。デフォルトでは、プロジェクトや組織のオーナーがこの権限を持ち、カスタムロールを作成および管理できます。

オーナー以外のユーザー(組織管理者を含む)には、組織ロールの管理者ロールまたは IAM ロールの管理者ロールのいずれかを割り当てる必要があります。

カスタムロールのタイトル、説明、権限名の合計サイズは 64 KB に制限されています。より大きなカスタムロールを作成する必要がある場合は、権限を複数のカスタムロールに分割できます。Custom Admin (1 of 2)Custom Admin (2 of 2) など、カスタムロール間の関係を示すロールタイトルを選択します。

Console

最初から新しいカスタムロールを作成するには、次の手順を行います。

  1. Cloud Console の [ロール] ページに移動します。

    [ロール] ページを開く

  2. ロールを作成する組織またはプロジェクトを選択します。

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

  4. ロールの [名前]、[タイトル]、[説明] を入力します。

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

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

既存のキュレートされたロールに基づいてカスタムロールを作成するには、次の手順を行います。

  1. Cloud Console の [ロール] ページに移動します。

    [ロール] ページを開く

  2. ロールを作成する組織またはプロジェクトを選択します。
  3. 新しいカスタムロールのベースにするロールを選択します。
  4. [選択からロールを作成] をクリックします。
  5. ロールの [名前]、[タイトル]、[説明] を入力します。
  6. ロールから除外する権限のチェックボックスをオフにします。
  7. [権限を追加] をクリックして権限を追加します。
  8. [作成] をクリックします。

gcloud コマンド

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 は、リリースのライフサイクルにおけるロールの段階を示します(ALPHABETAGA など)。
  • permission-1permission-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-id など)。
  • 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-id \
  --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-id/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-id など)。
  • role-title は、ロールのわかりやすいタイトルです("My Company Admin" など)。
  • role-description は、ロールに関する簡単な説明です("My custom role description." など)。
  • permissions-list には、カスタムロールに含める権限のカンマ区切りのリストが含まれます。(例: iam.roles.get,iam.roles.list
  • launch-stage は、リリースのライフサイクルにおけるロールの段階を示します(ALPHABETAGA など)。

次の例は、フラグを使用して組織レベルでロールを作成する方法を示しています。

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-id \
  --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-id/roles/myCompanyAdmin
stage: ALPHA
title: My Company Admin

REST API

create メソッドを使用して、新しいカスタムロールを作成します。

リクエストに次の必須パラメータを設定します。

  • 新しいカスタムロールに使用する role_id(myCustomStorageAuditor など)。
  • 「このロールは、ストレージ リソース、その容量、アクセス ポリシーを一覧表示できるよう権限を付与します」などのカスタムロールに関する説明。
  • このロールに関連付ける権限のリスト。
  • ロールに名前フィールドを設定すると、エラーが発生することに注意してください。

次のオプション パラメータも設定することをおすすめします。

  • 「カスタムロール編集者の例」などのカスタムロールのタイトル。
  • stage の値を GA などに設定します。

stage は、ALPHABETAGADEPRECATED または DISABLED の値を使用します。

一部の事前定義ロールには、サポートが終了した権限や、カスタムロールでは許可されない権限が含まれています。サポートが終了した権限や制限された権限を含む事前定義ロールに基づくカスタムロールの作成は失敗します。

{
  "roleId": "full-role-id",
  "role": {
    "title": "role-title",
    "description": "role-description",
    "includedPermissions": [
      "permission-1",
      "permission-2"
    ]
  }
}

ここで

  • full-role-id は、organizations/projects/、または roles/ 接頭辞を含む完全なロール ID です。(例: organizations/123456789012/roles/myCompanyAdmin.
  • role-title はロールのタイトルです。(例: Storage Auditor
  • role-description は、ロールの果たす内容の説明です。
  • permission-1permission-2 は、カスタムロールに含める権限です。

エラーコード

エラーコード ステータス メッセージ
PERMISSION_DENIED parent でロールを作成する権限がありません。
ALREADY_EXISTS parentrole-id という名前のロールがすでに存在します。
INVALID_ARGUMENT path が無効です。親は「organizations/{organization_id}」、「projects/{project_id}」、または空の形式にする必要があります。
INVALID_ARGUMENT role_id role-id は無効です。パターン pattern と一致しません。
INVALID_ARGUMENT ロール内の権限の数が最大数 max を超えています。
INVALID_ARGUMENT role.stage stage が無効です。

C#

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている C# 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM C# API のリファレンス ドキュメントをご覧ください。


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

public partial class CustomRoles
{
    public static Role CreateRole(string name, string projectId, string title,
        string description, IList<string> permissions, string stage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = new Role
        {
            Title = title,
            Description = description,
            IncludedPermissions = permissions,
            Stage = stage
        };
        var request = new CreateRoleRequest
        {
            Role = role,
            RoleId = name
        };
        role = service.Projects.Roles.Create(request,
            "projects/" + projectId).Execute();
        Console.WriteLine("Created role: " + role.Name);
        return role;
    }
}

Go

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Go 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Go API のリファレンス ドキュメントをご覧ください。

import (
	"context"
	"fmt"
	"io"

	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: %v", err)
	}

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

Python

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Python 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Python API のリファレンス ドキュメントをご覧ください。

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

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

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

既存のカスタムロールの編集

Read-Modify-Write

カスタムロールなどのリソースのメタデータの更新では一般に、リソースの現在の状態の読み取り、ローカルでのデータの更新、変更されたデータの書き込み用の送信が行われます。このような処理では、2 つ以上の独立したプロセスが一連の操作を同時に試行する場合に競合が発生することがあります。たとえば、プロジェクトの 2 人のオーナーが、1 つのロールに対して相反する変更を同時に行うと、一部の変更が失敗する可能性があります。Cloud IAM では、カスタムロールの etag プロパティを使用してこの問題を解決します。このプロパティは、カスタムロールが最後のリクエスト以降に変更されているかどうかを確認するために使用されます。etag 値を保持している Cloud IAM にリクエストを出すと、Cloud IAM はリクエスト内の etag 値と、カスタムロールに関連付けられている既存の etag 値を比較します。etag 値が一致した場合にのみ変更を書き込みます。

ロールを更新する場合は、roles.get() でロールを取得して更新します。その後、roles.patch() を使用して、更新されたロールを書き込みます。ロールを設定するときに etag 値を使用するのは、roles.get() 内の対応するロールに etag 値が含まれている場合のみです。

Console

  1. Cloud Console の [ロール] ページに移動します。

    [ロール] ページを開く

  2. 編集するロールを含むプロジェクトまたは組織を選択します。

  3. カスタムロールをクリックします。

  4. [ロールを編集] をクリックします。

  5. ロールに新しい権限を追加するには、[権限を追加] をクリックします。

  6. ロールから権限を削除する権限のチェックボックスをオフにします。

  7. [更新] をクリックして、編集したロールを保存します。

gcloud コマンド

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 は、更新するロールの名前です(viewer など)。
  • organization-id は組織の数値 ID です(123456789012 など)。
  • project-id はプロジェクトの名前です(my-project-id など)。

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

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

description: role-description
etag: etag-value
includedPermissions:
- permission-1
- permission-2
name: full-role-id
stage: launch-stage
title: role-title

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

  • role-description は、ロールに関する簡単な説明です("My custom role description" など)。
  • etag-value は、ロールの現在のバージョンの一意の識別子です(BwVkBkbfr70= など)。
  • permission-1permission-2 は、iam.roles.get などのカスタムロールに含める権限です。
  • full-role-id は、organizations/projects/、または roles/ 接頭辞を含む完全なロール ID です。(例: organizations/123456789012/roles/myCompanyAdmin.
  • launch-stage は、リリースのライフサイクルにおけるロールの段階を示します(ALPHABETAGA など)。
  • 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-id/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 は、更新するロールの名前です(viewer など)。
  • organization-id は組織の数値 ID です(123456789012 など)。
  • project-id はプロジェクトの名前です(my-project-id など)。
  • 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-id \
  --file=my-role-definition.yaml

ロールが正常に更新された場合、コマンドの出力は次のようになります。

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/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 はロールの名前です(viewer など)。
  • organization-id は組織の数値 ID です(123456789012 など)。
  • project-id はプロジェクトの名前です(my-project-id など)。
  • role-title は、ロールのわかりやすいタイトルです("My Company Admin" など)。
  • role-description は、ロールに関する簡単な説明です("My custom role description." など)。
  • launch-stage は、リリースのライフサイクルにおけるロールの段階を示します(ALPHABETAGA など)。

次の例は、フラグを使用して組織レベルのロールに権限を追加する方法を示しています。

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: organization/123456789012/roles/viewer
stage: ALPHA
title: My Company Admin

次の例は、フラグを使用してプロジェクト レベルのロールに権限を追加する方法を示しています。

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

ロールが正常に更新された場合、コマンドの出力は次のようになります。

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

REST API

編集するカスタムロールの ID がわかっている場合は、roles.get() メソッドを使用してロールを取得し、roles.patch() を使用して更新します。

編集するカスタムロールの ID がわからない場合は、ListRoles() を使用してすべてのロールを含むリストを取得し、ロールを特定します。roles.list() は、リソースを参照しているロールの一覧を返します。次に、roles.patch() を使用してロールを更新します。

次の必須パラメータを roles.patch() に設定します。

  • ロールの名前(organizations/organization-id/roles/role-id など)。

必要に応じて、updateMask クエリ パラメータを設定して、更新したフィールドを指定します。更新されたロールをリクエスト本文に含めます。

{
  "name": "full-role-id",
  "title": "role-title",
  "description": "role-description",
  "includedPermissions": [
    "permission-1",
    "permission-2"
  ]
}

ここで

  • full-role-id は、organizations/projects/、または roles/ 接頭辞を含む完全なロール ID です。(例: organizations/123456789012/roles/myCompanyAdmin.

  • role-title はロールのタイトルです。(例: New custom editor.

  • role-description はロールの説明です。(例: "My new long description of editor"

  • permission-1permission-2 は、ロールに含める権限です。(例: storage.objects.update

エラーコード

エラーコード ステータス メッセージ
PERMISSION_DENIED ロールを更新する権限がありません。
INVALID_ARGUMENT 定義済みロールは更新できません。
INVALID_ARGUMENT リクエスト内の名前(url-role-id)とロール内の名前(full-role-id)は一致する必要があります。
INVALID_ARGUMENT 権限 permission が無効です。
ABORTED etag が一致しなかったため、同時ポリシーが変更されました。読み取り-修正-書き込み全体を指数バックオフで再試行してください。

一部の事前定義ロールには、サポートが終了した権限や、カスタムロールでは許可されない権限が含まれています。サポートが終了した権限や制限された権限を含む事前定義ロールに基づくカスタムロールの作成は失敗します。

C#

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている C# 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM C# API のリファレンス ドキュメントをご覧ください。


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

public partial class CustomRoles
{
    public static Role EditRole(string name, string projectId, string newTitle,
        string newDescription, IList<string> newPermissions, string newStage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });
        // First, get a Role using List() or Get().
        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Get(resource).Execute();
        // Then you can update its fields.
        role.Title = newTitle;
        role.Description = newDescription;
        role.IncludedPermissions = newPermissions;
        role.Stage = newStage;
        role = service.Projects.Roles.Patch(role, resource).Execute();
        Console.WriteLine("Updated role: " + role.Name);
        return role;
    }
}

Go

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Go 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Go API のリファレンス ドキュメントをご覧ください。

import (
	"context"
	"fmt"
	"io"

	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: %v", err)
	}

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

Python

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Python 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Python API のリファレンス ドキュメントをご覧ください。

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

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

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

カスタムロールの無効化

カスタムロールを無効にできます。ロールを無効にすると、そのロールに関連するポリシー バインディングはすべて無効になります。つまり、ユーザーにロールを付与しても、そのロールの権限は付与されません。

Console

  1. Cloud Console の [ロール] ページに移動します。

    [ロール] ページを開く

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

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

  4. カスタムロールを選択し、[無効] をクリックします。

gcloud コマンド

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 はロールの名前です(viewer など)。
  • organization-id は組織の数値 ID です(123456789012 など)。
  • project-id はプロジェクトの名前です(my-project-id など)。

次の例は、組織レベルのロールを無効にする方法を示しています。

gcloud iam roles update myCompanyAdmin --organization=123456789012 \
  --stage=DISABLED

ロールが正常に更新された場合、コマンドの出力は次のようになります。

description: My custom role description.
etag: BwVkB5NLIQw=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: organization/123456789012/roles/myCompanyAdmin
stage: DISABLED
title: My Company Admin

次の例は、プロジェクト レベルのロールを無効にする方法を示しています。

gcloud iam roles update myCompanyAdmin --project=my-project-id \
  --stage=DISABLED

ロールが正常に更新された場合、コマンドの出力は次のようになります。

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

REST API

roles.patch() メソッドを使用して、カスタムロールを無効にします。

無効にするカスタムロールの ID がわかっている場合は、roles.get() メソッドでロールを取得します。ロールの stage プロパティを DISABLED に変更して、roles.patch() メソッドを呼び出してロールを更新します。

無効にするカスタムロールの ID がわからない場合は、roles.list() を使用してロールの一覧を取得し、目的のロールを特定します。roles.list() は、リソースを参照しているロールの一覧を返します。無効にするロールを特定し、その stage プロパティを DISABLED, に変更します。その後、roles.patch() メソッドを呼び出し、ロールを更新します。

ロールを無効にするには、次のフィールドを設定します。

  • stage フィールドを DISABLED. に設定します。
  • updateMask クエリ パラメータを stage に設定します。

ロールを再度有効にするには、同じプロセスに従いますが、ロールの stage フィールドを ALPHABETA、または GA に設定します。

{
  "name": "organizations/123456/roles/myCompanyCustomAdmin",
  "stage": "DISABLED"
}

エラーコード

エラーコード ステータス メッセージ
PERMISSION_DENIED ロールを更新する権限がありません。
INVALID_ARGUMENT キュレートされたロールを更新できません。
INVALID_ARGUMENT リクエスト内の名前(url-role-id)とロール内の名前(full-role-id)は一致する必要があります。
INVALID_ARGUMENT 権限 permission が無効です。
ABORTED 同時ポリシーが変更されました。読み取り-修正-書き込みを指数バックオフで再試行してください。

C#

ロールの stage フィールドを DISABLED更新します。

Go

ロールの stage フィールドを DISABLED更新します。

Python

ロールの stage フィールドを DISABLED更新します。

ロールの一覧表示

Console

Cloud Console の [ロール] ページに移動します。

[ロール] ページを開く

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

gcloud コマンド

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-id など)。

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

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

gcloud iam roles list

REST API

組織やプロジェクトで定義されているすべてのカスタムロールを一覧表示するには、roles.list() メソッドを使用します。また、このメソッドを使用し、リクエストの親フィールドを "" に設定することで、事前定義ロールを一覧表示することもできます。

roles.list() を呼び出すには、リクエストに次のフィールドを設定します。

  • すべてのカスタムロールを取得するために使用する次のような親要素。

    • projects/project-id
    • organizations/organization-id

結果に各ロールの権限が含まれるようにするには、view フィールドを FULL に設定します。

最近削除されたロールを結果に含める場合は、showDeleted フィールドを true に設定します。

すべてのキュレートされたロールの一覧を表示する場合は、親を ""(空文字列)に設定します。

エラーコード

エラーコード ステータス メッセージ
PERMISSION_DENIED path のロールを一覧表示する権限がありません。
INVALID_ARGUMENT path が無効です。親は「organizations/{organization_id}」、「projects/{project_id}」、または空の形式にする必要があります。
INVALID_ARGUMENT ロールビューが無効です。

C#

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている C# 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM C# API のリファレンス ドキュメントをご覧ください。


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

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

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

Go

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Go 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Go API のリファレンス ドキュメントをご覧ください。

import (
	"context"
	"fmt"
	"io"

	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: %v", err)
	}

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

Python

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Python 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Python API のリファレンス ドキュメントをご覧ください。

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

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

カスタムロールの削除

Console

  1. Cloud Console の [ロール] ページに移動します。

    [ロール] ページを開く

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

gcloud コマンド

gcloud iam roles delete コマンドを使用して、カスタムロールを削除します。ロールは停止され、新しい IAM ポリシー バインディングの作成には使用できません。

カスタムロールを削除するには、次のいずれかのコマンドを実行します。

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

    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-id など)。

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

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

REST API

roles.delete でロールを削除します。ロールは停止され、新しい IAM ポリシー バインディングの作成には使用できません。

name は、次の形式になります。

  • organizations/organization-id
  • projects/project-id

エラーコード

エラーコード ステータス メッセージ
PERMISSION_DENIED path でロールを削除する権限がありません。
FAILED_PRECONDITION すでに削除されているため、role-id は削除できません。
FAILED_PRECONDITION ロール role-id は予約されているため削除できません。
INVALID_ARGUMENT キュレートされたロールは削除状態にはできません。

C#

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている C# 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM C# API のリファレンス ドキュメントをご覧ください。


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

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

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

Go

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Go 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Go API のリファレンス ドキュメントをご覧ください。

import (
	"context"
	"fmt"
	"io"

	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: %v", err)
	}

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

Python

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Python 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Python API のリファレンス ドキュメントをご覧ください。

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

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

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

ロールが削除されると、そのバインディングは残りますが、非アクティブです。ロールは 7 日以内であれば削除を取り消すことができます。この 7 日間、ロールは Cloud Console で [削除済み] と表示され、プログラムの list コマンドでは表示されません(リクエストで showDeleted が設定されている場合を除く)。

ロールは 7 日後に完全削除が予定されます。この時点で、ロールは組織あたり 300 個のカスタムロールまたはプロジェクトあたり 300 個のカスタムロールの上限にカウントされなくなります。

完全に削除するには 30 日かかります。この 30 日間の間に、ロールと、そのロールに関連付けられているすべてのバインディングが完全に削除されます。同じロール ID を使用して新しいロールを作成することはできません。

最初の削除リクエストの 37 日後にロールが完全に削除された後は、同じロール ID を使用して新しいロールを作成できるようになります。

カスタムロールの削除の取り消し

Console

  1. Cloud Console の [ロール] ページに移動します。

    [ロール] ページを開く

  2. 削除を取り消すロールを見つけ、行の最後にあるその他アイコンをクリックして [削除を取り消す] をクリックします。

ロールの削除は、削除から 7 日以内に限って取り消すことができます。7 日が経過すると、ロールは完全に削除され、ロールに関連付けられたすべてのバインディングが除去されます。

gcloud コマンド

gcloud iam roles undelete を使用して、カスタムロールの削除を取り消します。ロールの削除を取り消すと、以前の状態に戻ります。

ロールの削除は、削除から 7 日以内に限って取り消すことができます。7 日が経過すると、ロールは完全に削除され、ロールに関連付けられたすべてのバインディングが除去されます。

カスタムロールの削除を取り消すには、次のいずれかのコマンドを実行します。

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

    gcloud iam roles undelete role-id --organization=organization-id
    
  • プロジェクト レベルのカスタムロールの削除を取り消すには、次のコマンドを実行します。

    gcloud iam roles undelete role-id --project=project-id
    

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

  • role-id はロールの名前です(myCompanyAdmin など)。
  • organization-id は組織の数値 ID です(123456789012 など)。
  • project-id はプロジェクトの名前です(my-project-id など)。

次の例は、組織レベルのカスタムロールの削除を取り消す方法を示しています。

gcloud iam roles undelete myCompanyAdmin --organization=123456789012

ロールの削除が正常に取り消された場合、コマンドの出力は次のようになります。

description: My custom role description.
etag: BwVkCAx9W6w=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: organization/123456789012/roles/myCompanyAdmin
stage: ALPHA
title: My Company Admin

次の例は、プロジェクト レベルのカスタムロールの削除を取り消す方法を示しています。

gcloud iam roles undelete myCompanyAdmin --project=my-project-id

ロールの削除が正常に取り消された場合、コマンドの出力は次のようになります。

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

REST API

roles.undelete はロールを以前の状態に戻します。

name は、次の形式になります。

  • organizations/organization-id/roles/role-id
  • projects/project-id/roles/role-id

ロールの削除は、削除から 7 日以内に限って取り消すことができます。7 日が経過すると、ロールは完全に削除され、ロールに関連付けられたすべてのバインディングが除去されます。

エラーコード

エラーコード ステータス メッセージ
PERMISSION_DENIED path でのロールの削除を取り消す権限がありません。
FAILED_PRECONDITION 削除されていないロールの削除を取り消すことはできません。
FAILED_PRECONDITION 予約済みロール role-id の削除を取り消すことはできません。
INVALID_ARGUMENT 事前定義ロールの削除は取り消すことはできません。

C#

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている C# 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM C# API のリファレンス ドキュメントをご覧ください。


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

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

        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Undelete(
            new UndeleteRoleRequest(), resource).Execute();
        Console.WriteLine("Undeleted role: " + role.Name);
        return role;
    }
}

Go

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Go 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Go API のリファレンス ドキュメントをご覧ください。

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

このサンプルを試す前に、Cloud IAM クイックスタート: クライアント ライブラリの使用で説明されている Python 向けの手順に沿って設定を行ってください。詳しくは、Cloud IAM Python API のリファレンス ドキュメントをご覧ください。

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

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

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

次のステップ