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

このページでは、Identity and Access Management(IAM)カスタムロールを作成および管理する方法について説明します。ロールの管理には、ロールの変更、無効化、一覧表示、削除、削除の取り消しが含まれます。

始める前に

  • Enable the IAM API.

    Enable the API

  • 認証を設定する。

    このページのサンプルをどのように使うかに応じて、タブを選択してください。

    コンソール

    Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。

    gcloud

    このページの gcloud CLI のサンプルは、次のいずれかの開発環境から使用できます。

    • Cloud Shell: gcloud CLI がすでに設定されているオンライン ターミナルを使用するには、Cloud Shell をアクティブにします。

      このページの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。セッションが初期化されるまで数秒かかることがあります。

    • ローカルシェル: ローカル開発環境で gcloud CLI を使用するには、gcloud CLI をインストールして初期化してください。

    C++

    このページの C++ サンプルをローカル開発環境から使用するには、gcloud CLI をインストールして初期化し、自身のユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定してください。

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. If you're using a local shell, then create local authentication credentials for your user account:

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    詳細については、Google Cloud の認証に関するドキュメントのローカル開発環境の認証の設定をご覧ください。

    C#

    このページの .NET サンプルをローカル開発環境から使用するには、gcloud CLI をインストールして初期化し、自身のユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定してください。

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. If you're using a local shell, then create local authentication credentials for your user account:

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    詳細については、Google Cloud の認証に関するドキュメントのローカル開発環境の認証の設定をご覧ください。

    Go

    このページの Go サンプルをローカル開発環境から使用するには、gcloud CLI をインストールして初期化し、自身のユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定してください。

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. If you're using a local shell, then create local authentication credentials for your user account:

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    詳細については、Google Cloud の認証に関するドキュメントのローカル開発環境の認証の設定をご覧ください。

    Java

    このページの Java サンプルをローカル開発環境から使用するには、gcloud CLI をインストールして初期化し、自身のユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定してください。

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. If you're using a local shell, then create local authentication credentials for your user account:

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    詳細については、Google Cloud の認証に関するドキュメントのローカル開発環境の認証の設定をご覧ください。

    Python

    このページの Python サンプルをローカル開発環境から使用するには、gcloud CLI をインストールして初期化し、自身のユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定してください。

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. If you're using a local shell, then create local authentication credentials for your user account:

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    詳細については、Google Cloud の認証に関するドキュメントのローカル開発環境の認証の設定をご覧ください。

    REST

    このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

      Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init

  • Google Cloud のリソース階層について理解する。

  • IAM のカスタムロールについてを読む。

必要なロール

カスタムロールを作成して管理するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

  • プロジェクトのロールを管理する: ロールを管理するプロジェクトに対するロール管理者roles/iam.roleAdmin
  • 組織のロールを管理する: ロールを管理する組織に対する組織のロールの管理者roles/iam.organizationRoleAdmin

ロールの付与の詳細については、アクセスの管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

プロジェクト、フォルダ、組織で利用可能な権限を表示する

カスタムロールは、組織全体、または組織内の特定のプロジェクトに対して作成できます。カスタムロールで使用できる権限は、ロールを作成する場所によって異なります。たとえば、組織レベルでのみ権限を使用できる場合、その権限をプロジェクト レベルのカスタムロールに含めることはできません。

組織レベルとプロジェクト レベルのカスタムロールで使用できる権限を確認するには、gcloud CLI または Identity and Access Management API を使用して、具体的な組織やプロジェクトで使用可能な権限のリストを出力します。たとえば、プロジェクトで作成したカスタムロールで使用可能なすべての権限を取得できます。

カスタムロールでサポートされている場合でも、カスタムロールで一部の権限が表示されない場合や、使用できない場合があります。たとえば、サービスで API を有効にしていない場合は、カスタムロールで権限を使用できないことがあります。

カスタムロールに追加できる権限の詳細については、サポートされている権限をご覧ください。

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

def query_testable_permissions(resource: str) -> None:
    """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"])

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

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスには、権限のリストが含まれます。

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

ロール メタデータを取得する

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

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

コンソール

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

def get_role(name: str) -> None:
    """Gets a role."""

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

REST

roles.get メソッドはロールの定義を取得します。

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

  • ROLE_NAME: organizations/projects/roles/ のいずれかの接頭辞を含む完全なロール名。たとえば、organizations/123456789012/roles/myCompanyAdmin

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

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

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

カスタムロールを作成する

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

組織レベルのカスタムロールには、カスタムロールでサポートされる任意の IAM 権限を含めることができます。プロジェクト レベルのカスタムロールには、サポートされている任意の権限を含めることができます。ただし、resourcemanager.organizations.get など、組織レベルまたはフォルダレベルのみで使用できる権限は除きます。これらの権限をプロジェクト レベルのカスタムロールに追加しようとすると、次のようなエラー メッセージが表示されます。

コンソール

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

gcloud

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

REST API

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

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

カスタムロールにはリリース ステージを設定できます。リリース ステージのほとんどは情報提供を目的としています。これにより、各ロールを広く使用できるかどうかをトラッキングできます。さらに、DISABLED リリース ステージでは、カスタムロールを無効にすることができます。リリース ステージの詳細については、テストとデプロイをご覧ください。

コンソール

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

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

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

    [ロール] ページに移動

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

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

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

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

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

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

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

    [ロール] ページに移動

  2. ロールを作成する組織またはプロジェクトを選択します。
  3. 新しいカスタムロールのベースにするロールを選択します。
  4. [選択内容からロールを作成] をクリックします。
  5. ロールの名前タイトル説明ロールのリリース ステージを入力します。ロールの作成後にロール名を変更することはできません。
  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 は、リリースのライフサイクルにおけるロールの段階を示します(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 など)。

    • 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 は、リリースのライフサイクルにおけるロールの段階を示します(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 \
        --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 で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、始める前にをご覧ください。

def create_role(
    name: str, project: str, title: str, description: str, permissions: str, stage: str
) -> dict:
    """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

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_1PERMISSION_2: ロールに含める権限。例: storage.objects.update。権限名にワイルドカード文字(*)は使用できません。

    カスタムロールには、カスタムロールでサポートされる権限のみを含めることができます。カスタムロールに他のロールが含まれている場合、リクエストは失敗します。

  • LAUNCH_STAGE: ロールの現在のリリース ステージ。このフィールドの値は、EAPALPHABETAGADEPRECATEDDISABLED のいずれかになります。

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

リクエストを送信するには、次のいずれかのオプションを展開します。

作成したロールがレスポンスに含まれます。

{
  "name": "projects/myProject/roles/myCompanyAdmin",
  "title": "My Company Admin",
  "description": "My custom role description.",
  "includedPermissions": [
    "iam.roles.get",
    "iam.roles.list"
  ],
  "etag": "BwWox/JbaZw="
}

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

カスタムロールなどのリソースのメタデータの更新では、一般に「読み取り - 変更 - 書き込み」のパターンが使用されます。このパターンでは、ロールの現在の状態を読み取り、データをローカルに更新した後、変更したデータを送信して書き込みます。

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

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

コンソール

  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_1PERMISSION_2 は、iam.roles.get などのカスタムロールに含める権限です。権限名にワイルドカード文字(*)は使用できません。

    • ROLE_NAME は、organizations/projects/roles/ のいずれかの接頭辞を含む完全なロール名です。例: 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/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 は、リリースのライフサイクルにおけるロールの段階を示します(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/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 で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、始める前にをご覧ください。

def edit_role(
    name: str, project: str, title: str, description: str, permissions: str, stage: str
) -> dict:
    """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

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_1PERMISSION_2: ロールに含める権限。例: storage.objects.update。権限名にワイルドカード文字(*)は使用できません。
  • LAUNCH_STAGE: ロールの現在のリリース ステージ。このフィールドの値は、EAPALPHABETAGADEPRECATEDDISABLED のいずれかになります。

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

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスには省略されたロール定義が含まれます。この定義には、ロール名、更新したフィールド、ロールの現在のバージョンを識別する ETag が含まれます。

{
  "name": "projects/test-project-1000092/roles/myCompanyAdmin",
  "title": "My Updated Company Admin",
  "includedPermissions": [
    "storage.buckets.get",
    "storage.buckets.list"
  ],
  "stage": "BETA",
  "etag": "BwWoyDpAxBc="
}

カスタムロールを無効にする

カスタムロールを無効にするには、リリース ステージを DISABLED に変更します。ロールを無効にすると、そのロールに関連するロール バインディングはすべて無効になります。つまり、ユーザーにロールを付与しても効果はありません。

コンソール

  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: organization/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

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

Python

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

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

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような 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 で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、始める前にをご覧ください。

def list_roles(project_id: str) -> None:
    """Lists roles."""

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

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

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような 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. 削除するロールを選択して、ページの上部にある 削除)をクリックします。

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

def delete_role(name: str, project: str) -> dict:
    """Deletes a role."""

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

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

REST

roles.delete メソッドを使用すると、プロジェクトまたは組織内のカスタムロールを削除できます。

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

  • ROLE_NAME: organizations/projects/roles/ のいずれかの接頭辞を含む完全なロール名。たとえば、organizations/123456789012/roles/myCompanyAdmin

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

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

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

ロールを削除しても、そのロールを参照するロール バインディングは許可ポリシーに残りますが、効果はありません。ロールは 7 日以内であれば削除を取り消すことができます。この 7 日間、Google Cloud コンソールにはロールが削除されたことが表示されます。削除されたロールはプログラムで一覧表示することもできますが、デフォルトでは省略されています。

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

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

最初の削除リクエストの発行からロールが完全に削除された後 44 日以内であれば、同じロール ID を使用して新しいロールを作成できます。

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

ロールの削除を取り消すと、以前の状態に戻ります。

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

コンソール

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

    [ロール] ページに移動

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

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 undelete を使用して、カスタムロールの削除を取り消します。

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

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

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

    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

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

    description: My custom role description.
    etag: BwVkCAx9W6w=
    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& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::UndeleteRoleRequest request;
  request.set_name(name);
  auto response = client.UndeleteRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully undeleted: " << 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 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

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

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

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: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Undeleted 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.UndeleteRoleRequest;
import java.io.IOException;

/**
 * Undelete a role to return it to its previous state. Undeleting only works on roles that were
 * deleted in the past 7 days.
 */
public class UndeleteRole {

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

    undeleteRole(projectId, roleId);
  }

  public static void undeleteRole(String projectId, String roleId) throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    UndeleteRoleRequest undeleteRoleRequest =
        UndeleteRoleRequest.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()) {
      Role result = iamClient.undeleteRole(undeleteRoleRequest);
      System.out.println("Undeleted role:\n" + result);
    }
  }
}

Python

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

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

def undelete_role(name: str, project: str) -> dict:
    """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

REST

roles.undelete メソッドを使用すると、プロジェクトまたは組織内のカスタムロールの削除を取り消すことができます。

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

  • ROLE_NAME: organizations/projects/roles/ のいずれかの接頭辞を含む完全なロール名。たとえば、organizations/123456789012/roles/myCompanyAdmin
  • ETAG: ロールのバージョンの識別子。他のロールの変更を上書きしないようにするには、このフィールドを指定します。

HTTP メソッドと URL:

POST https://iam.googleapis.com/v1/ROLE_NAME:undelete

リクエストの本文(JSON):

{
  "etag": "ETAG"
}

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスには、削除を取り消したロールの定義が含まれます。

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

次のステップ