カスタム役割の作成と管理

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

始める前に

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

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

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

Console

1. GCP Console の [役割] ページに移動します。

   [役割] ページを開く

2. ページの上部にあるプルダウンからプロジェクトを選択します。
3. リソースの管理者役割のチェックボックスを選択して、このリソースに適用可能なすべての権限を表示します。たとえば、Compute インスタンス管理者役割を選択すると、Compute Engine インスタンスに適用可能なすべての権限が右側のパネルに表示されます。

gcloud コマンド

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

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

gcloud iam list-testable-permissions [PROJECT-ID]

[PROJECT-ID] は、完全なリソース名の形式 //cloudresourcemanager.googleapis.com/projects/PROJECT-ID でのプロジェクトの ID です。例: //cloudresourcemanager.googleapis.com/projects/my-project-id。

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

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

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

REST API

QueryTestablePermissions は、リソースに適用できるすべての権限を返します。返される権限は、このリソースおよびその下の階層内のリソースでカスタムの役割を作成するのに使用できる権限です。このリクエストには、//cloudresourcemanager.googleapis.com/projects/my-project のように完全なリソース名のみを入力します。

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

例

full_resource_name: '//cloudresourcemanager.googleapis.com/projects/my-project'`

エラーコード

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

役割メタデータの取得

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

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

Console

1. GCP Console の [役割] ページに移動します。

   [役割] ページを開く

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

役割の横にあるアイコンは役割の種類を表します。カスタム役割の場合には、工場のアイコンが、事前定義済み役割の場合には六角形のアイコンが表示されます。

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

gcloud コマンド

事前定義済みの役割とカスタムの役割のメタデータを表示するには、gcloud iam roles describe コマンドを使用します。

事前定義済みの役割のメタデータを表示するには、次の gcloud コマンドを実行します。

gcloud iam roles describe [ROLE-NAME]

[ROLE-NAME] は、役割の名前です。例: roles/viewer。

次の例では、事前定義済みの役割 roles/iam.roleViewer に対して describe コマンドを実行した場合の出力を示します。

gcloud iam roles describe roles/iam.roleViewer

description: Read access to all custom roles in the project.
etag: AA==
includedPermissions:
- iam.roles.get
- iam.roles.list
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
name: roles/iam.roleViewer
stage: GA
title: Role Viewer

カスタムの役割のメタデータを表示するには、まずカスタムの役割が組織レベルで作成されたか、プロジェクト レベルで作成されたかを判断します。カスタムの役割が組織レベルで作成された場合、次の gcloud コマンドを実行します。

gcloud iam roles describe --organization [ORGANIZATION-ID] [ROLE-NAME]

[ORGANIZATION-ID] は 1234567 形式の組織の ID です。 [ROLE-NAME] はカスタムの役割の名前です。例: myCustomRole。

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

gcloud iam roles describe --project [PROJECT-ID] [ROLE-NAME]

[PROJECT-ID] はプロジェクトの ID です。例: my-project-id。 [ROLE-NAME] はカスタムの役割の名前です。例: myCustomRole。

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

REST API

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

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

• roles/{ROLE-NAME} や organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME} などの役割の名前。

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

• organizations/{ORGANIZATION-ID} や projects/{PROJECT-ID} など、すべてのカスタムの役割を取得する親。

エラーコード

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

カスタムの役割の作成

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

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

Console

最初から新しいカスタムの役割を作成するには:

1. GCP Console の [役割] ページに移動します。

   [役割] ページを開く

2. [組織] プルダウンから組織を選択します。
3. [役割の作成] をクリックします。
4. 役割の [名前]、[タイトル]、[説明] を入力します。
5. [権限を追加] をクリックします。
6. 役割に含める権限を選択し、[権限を追加] をクリックします。[すべてのサービス] と [すべてのタイプ] プルダウンを使用して、サービスとタイプ別に権限をフィルタリングして選択します。

既存のキュレートされた役割に基づいてカスタムの役割を作成するには:

1. GCP Console の [役割] ページに移動します。

   [役割] ページを開く

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

gcloud コマンド

新しいカスタムの役割を作成するには、gcloud iam roles create コマンドを使用します。このコマンドは次の 2 つの方法で使用できます。

• 役割の定義が含まれる YAML ファイルを使用する
• フラグを使用して役割の定義を指定する

カスタムの役割を作成する際には、--organization [ORGANIZATION-ID] フラグまたは --project [PROJECT-ID] フラグを使用して、組織レベルまたはプロジェクト レベルのどちらに適用するかを指定する必要があります。下の各例では、プロジェクト レベルでカスタムの役割を作成します。

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

カスタムの役割の定義が含まれる YAML ファイルを作成します。このファイルは次のような構造にする必要があります。

title: [ROLE-TITLE]
description: [ROLE-DESCRIPTION]
stage: [LAUNCH-STAGE]
includedPermissions:
- [PERMISSION-1]
- [PERMISSION-2]

以下では、各プレースホルダ値について説明します。

• [ROLE-TITLE] は役割のわかりやすいタイトルです。例: "Role Viewer"。
• [ROLE-DESCRIPTION] は役割についての短い説明です。例: "My custom role description"。
• [LAUNCH-STAGE] はリリースのライフサイクルにおける役割の段階を示します。例: ALPHA、BETA、GA。
• includedPermissions はカスタムの役割に含める 1 つ以上の権限のリストを指定します。例: - iam.roles.get。

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

gcloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

以下では、各プレースホルダ値について説明します。

• [ROLE-ID] は、役割の名前です。例: viewer。
• [PROJECT-ID] はプロジェクトの名前です。例: my-project-id。
• [YAML_FILE-PATH] は、カスタムの役割の定義が含まれる YAML ファイルの場所へのパスです。

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

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

次の例では、YAML ファイルを使用して役割を作成する方法を示します。

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

役割が正常に作成された場合、次のレスポンスが返されます。

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

フラグを使用してカスタムの役割を作成するには:

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

gcloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--permissions [PERMISSIONS-LIST] --stage [LAUNCH-STAGE]

以下では、各プレースホルダ値について説明します。

• [ROLE-ID] は、役割の名前です。例: viewer。
• [PROJECT-ID] はプロジェクトの名前です。例: my-project-id。
• [ROLE-TITLE] は役割のわかりやすいタイトルです。例: Role Viewer。
• [ROLE-DESCRIPTION] は役割についての短い説明です。例: "My custom role description."。
• [PERMISSIONS-LIST] には、カスタムの役割に含める権限のカンマ区切りのリストが含まれます。例: iam.roles.get,iam.roles.list。
• [LAUNCH-STAGE] はリリースのライフサイクルにおける役割の段階を示します。例: ALPHA、BETA、GA。

次の例では、フラグを使用して役割を作成する方法を示します。

gcloud iam roles create viewer --project my-project-id \
--title "Role Viewer" --description "My custom role description." \
--permissions iam.roles.get,iam.roles.list --stage ALPHA

役割が正常に作成された場合、次のレスポンスが返されます。

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

REST API

新しいカスタムの役割を作成するには、create メソッドを使用します。

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

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

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

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

stage は、ALPHA、BETA、GA、DEPRECATED、DISABLED のいずれかの値をとります。

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

例

parent: '[PARENT-NAME]'
role_id: '[ROLE-ID]'
role {
    name: ''
    title: '[ROLE-TITLE]'
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})",

ここで

• [PARENT-NAME] は、カスタムの役割を作成する組織の名前（organizations/0000000000000001 など）か、カスタムの役割を作成するプロジェクト ID（projects/my-project など）です。
• [ROLE-ID] はカスタムの役割の ID です。例: appengine.myCustomStorageAuditor.。
• [ROLE-TITLE] は役割のタイトルです。例: Storage Auditor。
• [ROLE-DESCRIPTION] は、役割の果たす内容の説明です。
• [PERMISSION] は、カスタムの役割に含める権限です。

注: create を呼び出すときに、リクエスト内の役割の名前フィールドを設定しないでください。作成時に、カスタムの役割の名前が organizations/{ORGANIZATION-ID}/roles/{ROLE-ID} または projects/{PROJECT-ID}/roles/{ROLE-ID} に設定されます。

エラーコード

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

既存のカスタムの役割の編集

Read-Modify-Write

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

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

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

Console

1. GCP Console の [役割] ページに移動します。

   [役割] ページを開く

2. [組織] プルダウンから組織を選択します。
3. カスタムの役割をクリックします。
4. [役割を編集] をクリックします。
5. 役割に新しい権限を追加するには、[権限を追加] をクリックします。
6. 役割から権限を削除する権限のチェックボックスをオフにします。
7. [更新] をクリックして、編集した役割を保存します。

gcloud コマンド

カスタムの役割を更新するには、gcloud iam roles update コマンドを使用します。このコマンドは次の 2 つの方法で使用できます。

• 更新された役割の定義が含まれる YAML ファイルを使用する
• フラグを使用して更新された役割の定義を指定する

カスタムの役割を更新する際には、--organization [ORGANIZATION-ID] フラグまたは --project [PROJECT-ID] フラグを使用して、組織レベルまたはプロジェクト レベルのどちらに適用するかを指定する必要があります。下の各例では、プロジェクト レベルでカスタムの役割を作成します。

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

次の gcloud コマンドを実行して、役割の現在の定義を取得します。

gcloud iam roles describe [ROLE-ID] --project [PROJECT-ID]

以下では、各プレースホルダ値について説明します。

• [ROLE-ID] は更新する役割の名前です。例: viewer。
• [PROJECT-ID] はプロジェクトの名前です。例: my-project-id。

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

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

description: [ROLE-DESCRIPTION]
etag: [ETAG-VALUE]
includedPermissions:
- [PERMISSION-1]
- [PERMISSION-2]
name: [ROLE-ID]
stage: [LAUNCH-STAGE]
title: [ROLE-TITLE]

以下では、各プレースホルダ値について説明します。

• [ROLE-DESCRIPTION] は役割についての短い説明です。例: "My custom role description"。
• [ETAG-VALUE] は現在のバージョンの役割の一意の識別子です。例: BwVkBkbfr70=。
• includedPermissions はカスタムの役割に含める 1 つ以上の権限のリストを指定します。例: - iam.roles.get。
• [ROLE-ID] は役割の階層 ID で、プロジェクト レベルで作成されたか、組織レベルで作成されたかに応じて異なります。例: projects/my-project-id/roles/viewer
• [LAUNCH-STAGE] はリリースのライフサイクルにおける役割の段階を示します。例: ALPHA、BETA、GA。
• [ROLE-TITLE] は役割のわかりやすいタイトルです。例: "Role Viewer"。

役割を更新するには、出力された役割の定義を 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/viewer
stage: ALPHA
title: Role Viewer

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

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

以下では、各プレースホルダ値について説明します。

• [ROLE-ID] は更新する役割の名前です。例: viewer。
• [PROJECT-ID] はプロジェクトの名前です。例: my-project-id。
• [YAML_FILE-PATH] は、更新されたカスタムの役割の定義が含まれる YAML ファイルの場所へのパスです。

次の例では、YAML ファイルを使用して役割を更新する方法を示します。

gcloud iam roles update viewer --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/viewer
stage: ALPHA
title: Role Viewer

フラグを使用してカスタムの役割を更新するには:

役割の定義の各部分は、対応するフラグを使用して更新できます。使用できるすべてのフラグのリストについては、gcloud iam roles update トピックをご覧ください。

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

• --add-permissions [PERMISSIONS]: 1 つ以上のカンマ区切りの権限を役割に追加します。
• --remove-permissions [PERMISSIONS]: 1 つ以上のカンマ区切りの権限を役割から削除します。

または、単純に --permissions [PERMISSIONS] フラグを使用して新しい権限を指定し、権限のカンマ区切りのリストを指定して、既存の権限のリストを置き換えます。

役割の定義の他の側面を更新するには、次の gcloud コマンドを実行します。

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--stage [LAUNCH-STAGE]

以下では、各プレースホルダ値について説明します。

• [ROLE-ID] は、役割の名前です。例: viewer。
• [PROJECT-ID] はプロジェクトの名前です。例: my-project-id。
• [ROLE-TITLE] は役割のわかりやすいタイトルです。例: Role Viewer。
• [ROLE-DESCRIPTION] は役割についての短い説明です。例: "My custom role description."。
• [LAUNCH-STAGE] はリリースのライフサイクルにおける役割の段階を示します。例: ALPHA、BETA、GA。

次の例では、フラグを使用して役割に権限を追加する方法を示します。

gcloud iam roles update viewer --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/viewer
stage: ALPHA
title: Role Viewer

REST API

既存のカスタムの役割を編集するには、Role UpdateRole(UpdateRoleRequest) メソッドを使用します。

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

編集するカスタムの役割の役割 ID がわからない場合は、ListRoles() を使用してすべての役割を一覧表示し、役割を識別します。roles.list() は、リソースを参照するすべての役割の一覧を返します。次に、roles.patch() を使用して役割を更新します。

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

• organizations/{ORGANIZATION-ID}/roles/{ROLE-ID} などの役割の名前。

必要に応じて update_mask フィールドを設定し、将来更新できるフィールドを指定します。

例

name: '[ROLE-NAME]'
role {
    name: '[ROLE-NAME]'
    title: '[ROLE-TITLE]'`
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})"

ここで

• [ROLE-NAME] は役割の名前です。例: organizations/123456/roles/appengine.customRoleEditor. 形式は roles/{ROLE-NAME}、organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}、projects/{PROJECT-ID}/roles/{ROLE-NAME} のいずれかです。

  注: 役割の中にある [ROLE_NAME] は空のままにすることをおすすめします。2 つの名前が同じでなく、役割内の名前が空でない場合、メソッドはエラーを返します。

• [ROLE-TITLE] は役割のタイトルです。例: New custom editor.。

• [ROLE-DESCRIPTION] は役割の説明です。例: 「編集者の新しい詳細な説明」。
• [PERMISSION] は役割に含める権限です。例: storage.objects.update。

エラーコード

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

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

カスタムの役割の無効化

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

Console

1. GCP Console の [役割] ページに移動します。

   [役割] ページを開く

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

gcloud コマンド

開始ステージを DISABLED に設定して、カスタムの役割を無効にするには、gcloud iam roles update コマンドを使用します。既存のカスタムの役割の編集の gcloud タブで説明されているように、次の 2 つの方法で既存のカスタムの役割を更新できます。

• 更新された役割の定義が含まれる YAML ファイルを使用する
• フラグを使用して更新された役割の定義を指定する

既存のカスタムの役割を無効にする最も簡単な方法は、--stage フラグを使用して、DISABLED に設定します。次の gcloud コマンドを実行します。

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--stage DISABLED

以下では、各プレースホルダ値について説明します。

• [ROLE-ID] は、役割の名前です。例: viewer。
• [PROJECT-ID] はプロジェクトの名前です。例: my-project-id。また、役割が組織レベルで作成された場合は、--organization [ORGANIZATION-ID] フラグを使用することもできます。例: 1234567。

次の例では、役割を無効にする方法を示します。

gcloud iam roles update viewer --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/viewer
stage: DISABLED
title: Role Viewer

REST API

カスタムの役割を無効にするには roles.patch() メソッドを使用します。

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

無効にするカスタムの役割の ID がわからない場合は、roles.list() を使用してすべての役割を一覧表示し、役割を見つけます。roles.list() は、リソースを参照するすべての役割のリストを返します。無効にする役割を特定し、その rolelaunchstage プロパティを DISABLED, に変更してから、roles.patch() メソッドを呼び出して役割を更新します。

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

• 名前を役割のフルネームに設定します（organizations/{organization-id}/roles/{role}.）。
• Role, で stage を DISABLED. に設定します。
• update_mask を「paths: stage」に設定します。

役割を再度有効にするには、上記の役割の無効化と同じプロセスを行いますが、役割の stage プロパティを ALPHA、BETA、GA のいずれかに設定します。

例

name: 'organizations/123456/roles/appengine.customRoleEditor'
role {
    name: 'organizations/123456/roles/appengine.customRoleEditor'`
    stage: 'DISABLED'
}
update_mask {
    paths:  stage
}

エラーコード

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

役割の一覧表示

Console

1. GCP Console の [役割] ページに移動します。

   [役割] ページを開く

   
   プロジェクトのすべてのカスタムの役割がページに一覧表示されます。

gcloud コマンド

プロジェクトまたは組織のカスタムの役割および事前定義済みの役割を一覧表示するには、gcloud iam roles list コマンドを使用します。

プロジェクト レベルまたは組織レベルのカスタム役割を指定して、次の gcloud コマンドを実行し、カスタムの役割を一覧表示します。

gcloud iam roles list --project [PROJECT-ID]

[PROJECT-ID] はプロジェクトの名前です。例: my-project-id。また、役割が組織レベルで作成された場合は、--organization [ORGANIZATION-ID] フラグを使用することもできます。例: 1234567。

削除された役割を一覧表示するには、--show-deleted フラグを使用することもできます。

事前定義済みの役割を一覧表示するには、次の gcloud コマンドを実行します。

gcloud iam roles list

REST API

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

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

• すべてのカスタムの役割を取得するために使用する次のような親。
  • projects/{PROJECT-ID}
  • organizations/{ORGANIZATION-ID}

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

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

すべてのキュレートされた役割の一覧を表示する場合は、親を ''（空文字列）に設定します。

エラーコード

エラーコード	ステータス メッセージ
PERMISSION_DENIED	{path} の役割を一覧表示する権限がありません。
INVALID_ARGUMENT	親 {path} が無効です。親は organizations/{organization-id}、projects/{project-id} の形式か空である必要があります。
INVALID_ARGUMENT	役割ビューが無効です。

カスタムの役割の削除

Console

1. GCP Console の [役割] ページに移動します。

   [役割] ページを開く

2. 削除する役割を選択し、ページ上部のゴミ箱アイコンをクリックします。

gcloud コマンド

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

次の gcloud コマンドを実行して、カスタムの役割を削除します。

gcloud iam roles delete [ROLE-ID] --project [PROJECT-ID]

以下では、各プレースホルダ値について説明します。

• [ROLE-ID] は、役割の名前です。例: viewer。
• [PROJECT-ID] はプロジェクトの名前です。例: my-project-id。また、役割が組織レベルで作成された場合は、--organization [ORGANIZATION-ID] フラグを使用することもできます。例: 1234567。

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

---
deleted: true
description: My custom role description.
etag: BwVkB5NLIQw=
name: projects/my-project-id/roles/viewer
title: Role Viewer
---

REST API

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

name の形式は次のとおりです。

• organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
• projects/{PROJECT-ID}/roles/{ROLE-NAME}

エラーコード

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

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

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

最初の削除リクエストの 37 日後に役割が完全に削除された後、同じ役割 ID を使用して新しい役割を作成できます。

カスタムの役割の削除の取り消し

Console

1. GCP Console の [役割] ページに移動します。

   [役割] ページを開く

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

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

gcloud コマンド

カスタムの役割の削除を取り消すには、gcloud iam roles undelete コマンドを使用します。役割の削除を取り消すと、以前の状態に戻ります。

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

次の gcloud コマンドを実行して、カスタムの役割の削除を取り消します。

gcloud iam undelete [ROLE-ID] --project [PROJECT-ID]

以下では、各プレースホルダ値について説明します。

• [ROLE-ID] は、役割の名前です。例: viewer。
• [PROJECT-ID] はプロジェクトの名前です。例: my-project-id。また、役割が組織レベルで作成された場合は、--organization [ORGANIZATION-ID] フラグを使用することもできます。例: 1234567。

次の例では、カスタムの役割の削除を取り消す方法を示します。

gcloud iam roles undelete viewer --project my-project-id

役割の削除が正常に取り消された場合、次のレスポンスが返されます。

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

REST API

roles.undelete は役割を以前の状態に戻します。

name の形式は次のとおりです。

• organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
• projects/{PROJECT-ID}/roles/{ROLE-NAME}

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

エラーコード

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