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

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

始める前に

IAM API を有効にします。
API を有効にする
Google Cloud のリソース階層について理解する。
IAM のカスタムロールについてを読む。

必要なロール

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

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

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

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

カスタムロールは、組織全体、または組織内の特定のプロジェクトに対して作成できます。

カスタムロールには、すべてではありませんが、多くの IAM 権限を含めることができます。各権限には、カスタムロールで使用する次のいずれかのサポートレベルがあります。

サポートレベル	説明
`SUPPORTED`	この権限は、カスタムロールで完全にサポートされます。
`TESTING`	Google では、カスタムロールとの互換性を確認する権限をテストしています。カスタムロールに権限を含めることはできますが、予期しない動作が発生することがあります。本番環境での使用は推奨されていません。
`NOT_SUPPORTED`	この権限は、カスタムロールではサポートされません。

組織レベルのカスタムロールには、カスタムロールでサポートされる任意の IAM 権限を含めることができます。プロジェクトレベルのカスタムロールには、サポートされている任意の権限を含めることができます。ただし、resourcemanager.organizations.get など、組織レベルまたはフォルダレベルだけに関連する権限は除きます。

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

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

gcloud CLI

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-id）
組織: //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
---

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）

リクエスト本文を 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"
}

C++

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

GitHub で表示フィードバック

namespace iam = ::google::cloud::iam;
[](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 const& permission : client.QueryTestablePermissions(request)) {
    if (!permission) throw std::runtime_error(permission.status().message());
    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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック


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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

import (
	"context"
	"fmt"
	"io"

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

// queryTestablePermissions lists testable permissions on a resource.
func queryTestablePermissions(w io.Writer, fullResourceName string) ([]*iam.Permission, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

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

Python

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

GitHub で表示フィードバック

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

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

ロールメタデータの取得

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

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

コンソール

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

[ロール] ページに移動
ページの上部にあるプルダウンリストから組織またはプロジェクトを選択します。
1 つ以上のロールのチェックボックスを選択して、ロールの権限を表示します。ロールに含まれている権限があれば、右側のパネルに表示されます。

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

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

gcloud CLI

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

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

REST

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

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

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

HTTP メソッドと URL:

GET https://iam.googleapis.com/v1/full-role-id

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

curl（Linux、macOS、Cloud Shell）

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

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

PowerShell（Windows）

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

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/full-role-id" | 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="
}

C++

GitHub で表示フィードバック

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully retrieved: " << response->DebugString()
            << "\n";
}

C#

GitHub で表示フィードバック


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

GitHub で表示フィードバック

import (
	"context"
	"fmt"
	"io"

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

// getRole gets role metadata.
func getRole(w io.Writer, name string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

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

Python

GitHub で表示フィードバック

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

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

カスタムロールの作成

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

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

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

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

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

コンソール

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

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

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

[ロール] ページに移動
ページの上部にあるプルダウンリストを使用して、ロールを作成する組織またはプロジェクトを選択します。
[ロールの作成] をクリックします。
ロールの名前、タイトル、説明、ロールのリリースステージを入力します。ロールの作成後にロール名を変更することはできません。
[権限を追加] をクリックします。
ロールに含める権限を選択し、[権限を追加] をクリックします。[すべてのサービス] と [すべての種類] プルダウンリストを使用して、サービスと種類別に権限をフィルタリングして選択します。

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

Google Cloud コンソールで、[ロール] ページに移動します。
[ロール] ページに移動
ロールを作成する組織またはプロジェクトを選択します。
新しいカスタムロールのベースにするロールを選択します。
[選択内容からロールを作成] をクリックします。
ロールの名前、タイトル、説明、ロールのリリースステージを入力します。ロールの作成後にロール名を変更することはできません。
ロールから除外する権限のチェックボックスをオフにします。
[権限を追加] をクリックして権限を追加します。
[作成] をクリックします。

gcloud CLI

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-id など）。
yaml-file-path は、カスタムロール定義が含まれる YAML ファイルの場所へのパスです。

例

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

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

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

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

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

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

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

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

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

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

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

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

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

gcloud iam roles create role-id --organization=organization-id \
    --title=role-title --description=role-description \
    --permissions="permissions-list" --stage=launch-stage

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

gcloud iam roles create role-id --project=project-id \
    --title=role-title --description=role-description \
    --permissions="permissions-list" --stage=launch-stage

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

role-id はロールの名前です（myCompanyAdmin など）。
organization-id は組織の数値 ID です（123456789012 など）。
project-id はプロジェクトの名前です（my-project-id など）。
role-title は、ロールのわかりやすいタイトルです（"My Company Admin" など）。
role-description は、ロールに関する簡単な説明です（"My custom role description." など）。
permissions-list には、カスタムロールに含める権限のカンマ区切りのリストが含まれます。例: iam.roles.get,iam.roles.list。権限名にワイルドカード文字（*）は使用できません。
launch-stage は、リリースのライフサイクルにおけるロールの段階を示します（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-id \
    --title="My Company Admin" --description="My custom role description." \
    --permissions="iam.roles.get,iam.roles.list" --stage=ALPHA

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

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

REST

roles.create メソッドを使用すると、プロジェクトまたは組織にカスタムロールを作成できます。

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

resource-type: カスタムロールを管理するリソースタイプ。値 projects または organizations を使用します。
resource-id: カスタムロールを管理するプロジェクト ID または組織 ID。プロジェクト ID は英数字からなる文字列です（例: my-project）。組織 ID は数値で指定します（例: 123456789012）。
role-id: ロールの名前（myCompanyAdminなど）。
role-title: 人が読める形式のロールタイトル。例: My Company Admin
role-description: ロールの説明。例: "The company admin role allows company admins to access important resources"
permission-1 と permission-2: ロールに含める権限。例: storage.objects.update。権限名にワイルドカード文字（*）は使用できません。

カスタムロールには、カスタムロールでサポートされる権限のみを含めることができます。カスタムロールに他のロールが含まれている場合、リクエストは失敗します。
launch-stage: ロールの現在のリリースステージ。このフィールドの値は、EAP、ALPHA、BETA、GA、DEPRECATED、DISABLED のいずれかになります。

HTTP メソッドと URL:

POST https://iam.googleapis.com/v1/resource-type/resource-id/roles

JSON 本文のリクエスト:

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

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

curl（Linux、macOS、Cloud Shell）

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

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

PowerShell（Windows）

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

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

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

API Explorer（ブラウザ）

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

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

C++

GitHub で表示フィードバック

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully created: " << response->DebugString()
            << "\n";
}

C#

GitHub で表示フィードバック


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

GitHub で表示フィードバック

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

GitHub で表示フィードバック

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

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

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

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

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

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

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

コンソール

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

[ロール] ページに移動
ページの上部にあるプルダウンリストを使用して、編集するロールを含むプロジェクトまたは組織を選択します。
カスタムロールをクリックします。
[ロールを編集] をクリックします。
ロールのメタデータを更新するには、ロールのタイトル、説明、またはロールのリリースステージを編集します。
ロールの権限を更新するには、次の手順を行います。
1. ロールに新しい権限を追加するには、[権限を追加] をクリックします。
2. ロールから権限を削除する権限のチェックボックスをオフにします。
[更新] をクリックして、編集したロールを保存します。

gcloud CLI

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

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

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

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

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

role-description は、ロールに関する簡単な説明です（"My custom role description" など）。
etag-value は、ロールの現在のバージョンの一意の識別子です（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-id/roles/myCompanyAdmin
stage: ALPHA
title: My Company Admin

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

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

gcloud iam roles update role-id --organization=organization-id \
    --file=yaml-file-path

プロジェクトレベルのロールを更新するには、次のコマンドを実行します。
```
gcloud iam roles update role-id --project=project-id \
    --file=yaml-file-path
```

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

role-id は、更新するロールの名前です（myCompanyAdmin など）。
organization-id は組織の数値 ID です（123456789012 など）。
project-id はプロジェクトの名前です（my-project-id など）。
yaml-file-path は、更新されたカスタムロール定義が含まれる YAML ファイルの場所のパスです。

例

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

gcloud iam roles update role-id --organization=organization-id \
    --title=role-title --description=role-description \
    --stage=launch-stage

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

gcloud iam roles update role-id --project=project-id \
    --title=role-title --description=role-description \
    --stage=launch-stage

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

role-id はロールの名前です（myCompanyAdmin など）。
organization-id は組織の数値 ID です（123456789012 など）。
project-id はプロジェクトの名前です（my-project-id など）。
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-id \
    --add-permissions="storage.buckets.get,storage.buckets.list"

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

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

REST

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": "full-role-id",
  "title": "role-title",
  "description": "role-description",
  "includedPermissions": [
    "permission-1",
    "permission-2"
  ],
  "stage": "launch-stage",
  "etag": "etag"
}

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

curl（Linux、macOS、Cloud Shell）

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

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

PowerShell（Windows）

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

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

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

API Explorer（ブラウザ）

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

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

C++

GitHub で表示フィードバック

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully updated: " << response->DebugString()
            << "\n";
}

C#

GitHub で表示フィードバック


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

GitHub で表示フィードバック

import (
	"context"
	"fmt"
	"io"

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

// editRole modifies a custom role.
func editRole(w io.Writer, projectID, name, newTitle, newDescription, newStage string, newPermissions []string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %v", err)
	}

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

Python

GitHub で表示フィードバック

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

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

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

カスタムロールの無効化

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

コンソール

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

[ロール] ページに移動
ページの上部にある [プロジェクトを選択] プルダウンリストをクリックします。
組織またはプロジェクトを選択します。
カスタムロールを選択し、[無効] をクリックします。

gcloud CLI

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

例

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

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

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

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

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

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

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

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

REST

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/resource-id/roles

JSON 本文のリクエスト:

{
  "roleId": "full-role-id",
  "stage": DISABLED,
  "etag": "etag"
}

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

curl（Linux、macOS、Cloud Shell）

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

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

PowerShell（Windows）

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

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

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

API Explorer（ブラウザ）

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

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

C++

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

C#

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

Go

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

Python

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

ロールの一覧表示

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

コンソール

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

[ロール] ページに移動

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

gcloud CLI

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

組織レベルのカスタムロールを一覧表示するには、次のコマンドを実行します。
```
gcloud iam roles list --organization=organization-id
```
プロジェクトレベルのカスタムロールを一覧表示するには、次のコマンドを実行します。
```
gcloud iam roles list --project=project-id
```

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

organization-id は組織の数値 ID です（123456789012 など）。
project-id はプロジェクトの名前です（my-project-id など）。

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

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

gcloud iam roles list

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）

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

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token"

PowerShell（Windows）

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

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token" | Select-Object -Expand Content

API Explorer（ブラウザ）

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

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

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

C++

GitHub で表示フィードバック

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

C#

GitHub で表示フィードバック


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

GitHub で表示フィードバック

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

GitHub で表示フィードバック

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

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

カスタムロールの削除

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

コンソール

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

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

gcloud CLI

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

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

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

REST

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

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

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

HTTP メソッドと URL:

DELETE https://iam.googleapis.com/v1/full-role-id

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

curl（Linux、macOS、Cloud Shell）

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

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

PowerShell（Windows）

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

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

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

API Explorer（ブラウザ）

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

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

C++

GitHub で表示フィードバック

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully deleted: " << response->DebugString()
            << "\n";
}

C#

GitHub で表示フィードバック


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

GitHub で表示フィードバック

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

GitHub で表示フィードバック

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

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

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

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

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

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

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

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

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

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

コンソール

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

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

gcloud CLI

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

例

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

gcloud iam roles undelete myCompanyAdmin --organization=123456789012

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

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

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

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

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

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

REST

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

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

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

HTTP メソッドと URL:

POST https://iam.googleapis.com/v1/full-role-id:undelete

JSON 本文のリクエスト:

{
  "etag": "etag"
}

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

curl（Linux、macOS、Cloud Shell）

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

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

PowerShell（Windows）

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

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

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

API Explorer（ブラウザ）

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

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

C++

GitHub で表示フィードバック

namespace iam = ::google::cloud::iam;
[](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::runtime_error(response.status().message());
  std::cout << "Role successfully undeleted: " << response->DebugString()
            << "\n";
}

C#

GitHub で表示フィードバック


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

GitHub で表示フィードバック

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

GitHub で表示フィードバック

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

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

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

次のステップ

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

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

始める前に

必要なロール

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

gcloud CLI

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

C++

C#

Go

Python

ロール メタデータの取得

コンソール

gcloud CLI

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

C++

C#

Go

Python

カスタムロールの作成

コンソール

gcloud CLI

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

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

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

C++

C#

Go

Python

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

コンソール

gcloud CLI

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

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

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

C++

C#

Go

Python

カスタムロールの無効化

コンソール

gcloud CLI

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

C++

C#

Go

Python

ロールの一覧表示

コンソール

gcloud CLI

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

C++

C#

Go

Python

カスタムロールの削除

コンソール

gcloud CLI

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

API Explorer（ブラウザ）

C++

ロールメタデータの取得