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

このページでは、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"
}

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して自分のユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

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

API Explorer（ブラウザ）

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

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

注: customRolesSupportLevel フィールドがない権限は、カスタムロールで完全にサポートされています。

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

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して自分のユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

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

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

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

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

API Explorer（ブラウザ）

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

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

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

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

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

注: フォルダレベルでカスタムロールを定義することはできません。フォルダ内でカスタムロールを使用する必要がある場合は、組織レベルでカスタムロールを定義します。

組織レベルのカスタムロールには、カスタムロールでサポートされる任意の 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 は、リリースのライフサイクルにおけるロールの段階を示します（ALPHA、BETA、GA など）。

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

   YAML ファイルを保存し、次のいずれかのコマンドを実行します。

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

     gcloud iam roles create ROLE_ID--organization=ORGANIZATION_ID \
         --file=YAML_FILE_PATH

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

     gcloud iam roles create ROLE_ID --project=PROJECT_ID \
         --file=YAML_FILE_PATH

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

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

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

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

   • YAML_FILE_PATH は、カスタムロールの定義が含まれる YAML ファイルの場所へのパスです。

   例

   次の YAML ファイルの例では、ロール定義を作成する方法を示します。

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

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

   gcloud iam roles create myCompanyAdmin --organization=123456789012 \
       --file=my-role-definition.yaml

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

   Created role [myCompanyAdmin].
   description: My custom role description.
   etag: BwVkBX0sQD0=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   name: organizations/123456789012/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

   次の例は、YAML ファイルを使用してプロジェクト レベルでロールを作成する方法を示しています。

   gcloud iam roles create myCompanyAdmin --project=my-project \
       --file=my-role-definition.yaml

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

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

   フラグを使用してカスタムロールを作成するには:

   次のいずれかのコマンドを実行します。

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

     gcloud iam roles create ROLE_ID--organization=ORGANIZATION_ID \
         --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
         --permissions="PERMISSIONS_LIST" --stage=LAUNCH_STAGE

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

     gcloud iam roles create ROLE_ID --project=PROJECT_ID \
         --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
         --permissions="PERMISSIONS_LIST" --stage=LAUNCH_STAGE

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

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

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

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

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

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

   • PERMISSIONS_LIST には、カスタムロールに含める権限のカンマ区切りのリストが含まれます（たとえば、iam.roles.get,iam.roles.list）。権限名にワイルドカード文字（*）は使用できません。

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

   例

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

   gcloud iam roles create myCompanyAdmin --organization=123456789012 \
       --title="My Company Admin" --description="My custom role description." \
       --permissions="iam.roles.get,iam.roles.list" --stage=ALPHA

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

   Created role [myCompanyAdmin].
   description: My custom role description.
   etag: BwVkBX0sQD0=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   name: organizations/123456789012/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

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

   gcloud iam roles create myCompanyAdmin --project=my-project \
       --title="My Company Admin" --description="My custom role description." \
       --permissions="iam.roles.get,iam.roles.list" --stage=ALPHA

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

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

C++

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

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

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& parent, std::string const& role_id,
   std::vector<std::string> const& included_permissions) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::CreateRoleRequest request;
  request.set_parent("projects/" + parent);
  request.set_role_id(role_id);
  google::iam::admin::v1::Role role;
  role.set_stage(google::iam::admin::v1::Role::GA);
  for (auto const& permission : included_permissions) {
    *role.add_included_permissions() = permission;
  }
  *request.mutable_role() = role;
  auto response = client.CreateRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully created: " << response->DebugString()
            << "\n";
}

C#

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

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

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

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

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

Go

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

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

import (
	"context"
	"fmt"
	"io"

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

// createRole creates a custom role.
func createRole(w io.Writer, projectID, name, title, description, stage string, permissions []string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %w", err)
	}

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

Java

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

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

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.CreateRoleRequest;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.Role.RoleLaunchStage;
import java.io.IOException;
import java.util.Arrays;

/** Create role. */
public class CreateRole {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";
    String title = "a title for your role (e.g. IAM Role Viewer)";
    String description = "a description of the role";
    Iterable<String> includedPermissions =
        Arrays.asList("roles/iam.roleViewer", "roles/logging.viewer");

    createRole(projectId, title, description, includedPermissions, roleId);
  }

  public static void createRole(
      String projectId,
      String title,
      String description,
      Iterable<String> includedPermissions,
      String roleId)
      throws IOException {
    Role.Builder roleBuilder =
        Role.newBuilder()
            .setTitle(title)
            .setDescription(description)
            .addAllIncludedPermissions(includedPermissions)
            // See launch stage enums at
            // https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage
            .setStage(RoleLaunchStage.BETA);
    CreateRoleRequest createRoleRequest =
        CreateRoleRequest.newBuilder()
            .setParent("projects/" + projectId)
            .setRoleId(roleId)
            .setRole(roleBuilder)
            .build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role result = iamClient.createRole(createRoleRequest);
      System.out.println("Created role: " + result.getName());
    }
  }
}

Python

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

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

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

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

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

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

{
  "roleId": "ROLE_ID",
  "role": {
    "title": "ROLE_TITLE",
    "description": "ROLE_DESCRIPTION",
    "includedPermissions": [
      "PERMISSION_1",
      "PERMISSION_2"
    ],
    "stage": "LAUNCH_STAGE"
  }
}

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して自分のユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

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

API Explorer（ブラウザ）

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

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

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

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

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

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

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

注: resourcemanager.organizations.get、resourcemanager.folders.get、resourcemanager.projects.get のいずれかの権限を追加または削除してカスタムロールを変更した場合、カスタムロールの変更が organizations.search と folders.search の Cloud Resource Manager API に反映されるまでに最大で 24 時間かかります。また、親タイプと ID を指定するフィルタを提供しない API 呼び出しでも、API projects.list がこの遅延の影響を受けます。この遅延が発生する理由は、これらの権限が検索機能に関連しており、検索インデックスの再構築の間隔が最大で 24 時間とされるためです。

コンソール

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

   [ロール] ページに移動

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

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

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

5. ロールのメタデータを更新するには、ロールのタイトル、説明、またはロールのリリース ステージを編集します。

6. ロールの権限を更新するには、次の手順を行います。

   1. ロールに新しい権限を追加するには、[権限を追加] をクリックします。
   2. ロールから権限を削除する権限のチェックボックスをオフにします。

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

gcloud

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

   Activate Cloud Shell

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

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

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

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

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

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

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

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

     gcloud iam roles describe ROLE_ID --organization=ORGANIZATION_ID

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

     gcloud iam roles describe ROLE_ID --project=PROJECT_ID

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   次の YAML ファイルの例では、プロジェクト レベルのロールの describe コマンドからの出力が含まれ、2 つの Cloud Storage 権限が追加されています。

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

   YAML ファイルを保存し、次のいずれかのコマンドを実行します。

   • 組織レベルのロールを更新するには、次のコマンドを実行します。

     gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
         --file=YAML_FILE_PATH

   • プロジェクト レベルのロールを更新するには、次のコマンドを実行します。

     gcloud iam roles update ROLE_ID --project=PROJECT_ID \
         --file=YAML_FILE_PATH

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

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

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

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

   • YAML_FILE_PATH は、更新されたカスタムロール定義が含まれる YAML ファイルの場所のパスです。

   例

   次の例は、YAML ファイルを使用して組織レベルのロールを更新する方法を示しています。

   gcloud iam roles update ROLE_ID --organization=ORGANIZATION_ID \
       --file=YAML_FILE_PATH

   • プロジェクト レベルのロールを更新するには、次のコマンドを実行します。

     gcloud iam roles update ROLE_ID --project=PROJECT_ID \
         --file=YAML_FILE_PATH

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

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

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

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

   • YAML_FILE_PATH は、更新されたカスタムロールの定義が含まれる YAML ファイルの場所のパスです。

   例

   次の例は、YAML ファイルを使用して組織レベルのロールを更新する方法を示しています。

   gcloud iam roles update myCompanyAdmin --organization=123456789012 \
       --file=my-role-definition.yaml

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

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

   次の例は、YAML ファイルを使用してプロジェクト レベルのロールを更新する方法を示しています。

   gcloud iam roles update myCompanyAdmin --project=my-project \
       --file=my-role-definition.yaml

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

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

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

   ロールの定義の各部分は、対応するフラグを使用して更新できます。使用可能なフラグの一覧については、gcloud iam roles update トピックをご覧ください。

   次のフラグを使用して、権限を追加または削除できます。

   • --add-permissions=PERMISSIONS: 権限をロールに追加します。複数の権限を追加する場合は権限をカンマで区切ります。権限名にワイルドカード文字（*）は使用できません。

   • --remove-permissions=PERMISSIONS: 権限（複数の場合はカンマで区切る）をロールから削除します。権限名にワイルドカード文字（*）は使用できません。

   または、--permissions=PERMISSIONS フラグを使用して新しい権限を指定することもできます。権限のカンマ区切りのリストを指定すると、既存の権限のリストが置き換えられます。

   ロール定義の他の部分を更新するには、次のいずれかのコマンドを実行します。

   • 組織レベルのロールを更新するには、次のコマンドを実行します。

     gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
         --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
         --stage=LAUNCH_STAGE

   • プロジェクト レベルのロールを更新するには、次のコマンドを実行します。

     gcloud iam roles update ROLE_ID --project=PROJECT_ID \
         --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
         --stage=LAUNCH_STAGE

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

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

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

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

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

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

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

   例

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

   gcloud iam roles update myCompanyAdmin --organization=123456789012 \
       --add-permissions="storage.buckets.get,storage.buckets.list"

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

   description: My custom role description.
   etag: BwVkBwDN0lg=
   includedPermissions:
   - iam.roles.get
   - iam.roles.list
   - storage.buckets.get
   - storage.buckets.list
   name: 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_1 と PERMISSION_2: ロールに含める権限。例: storage.objects.update。権限名にワイルドカード文字（*）は使用できません。
• LAUNCH_STAGE: ロールの現在のリリース ステージ。このフィールドの値は、EAP、ALPHA、BETA、GA、DEPRECATED、DISABLED のいずれかになります。

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

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

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して自分のユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

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

API Explorer（ブラウザ）

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

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

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

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

カスタムロールを無効にするには、リリース ステージを 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"
}

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して自分のユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

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

API Explorer（ブラウザ）

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

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

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

ロールを一覧表示する

プロジェクトまたは組織で作成されたすべてのカスタムロールを一覧表示できます。

コンソール

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

[ロール] ページに移動

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

gcloud

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

   Activate Cloud Shell

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

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

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

     gcloud iam roles list --organization=ORGANIZATION_ID

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

     gcloud iam roles list --project=PROJECT_ID

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

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

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

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

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

   gcloud iam roles list

C++

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

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

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

C#

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

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

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

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

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

Go

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

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

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

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

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

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

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

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

    listRoles(projectId);
  }

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

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

Python

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

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

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: 省略可。以前のレスポンスでこのメソッドから返されたページ設定トークン。指定すると、前のリクエストが終了した時点からロールのリストが開始します。

注: 事前定義の IAM ロールを一覧表示するには、RESOURCE_TYPE フィールドと RESOURCE_ID フィールドを省略します。例: GET https://iam.googleapis.com/v1/roles

HTTP メソッドと URL:

GET https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して自分のユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

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

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

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

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

API Explorer（ブラウザ）

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

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

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

カスタムロールを削除する

プロジェクトまたは組織内のカスタムロールを削除できます。

重要: 削除されたロールは一時停止され、許可ポリシーの新しいロール バインディングの作成には使用できません。削除されたロールを含む既存のロール バインディングは効果がありません。

コンソール

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

   [ロール] ページに移動

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

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

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して自分のユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

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

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

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

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

API Explorer（ブラウザ）

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

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

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

ロールを削除しても、そのロールを参照するロール バインディングは許可ポリシーに残りますが、効果はありません。ロールは 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"
}

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して自分のユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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

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

API Explorer（ブラウザ）

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

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

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

次のステップ

• プリンシパルにロールを付与する方法を確認する。
• ロールの推奨事項を使用してプリンシパルの権限の範囲を限定する方法を確認する。
• 特定の条件を満たす場合にのみロールを付与する条件付きロールの付与について学習する。