커스텀 역할 생성 및 관리

이 페이지에서는 커스텀 역할을 만들고 관리하는 방법을 설명합니다.

시작하기 전에

커스텀 역할을 만드는 데 필요한 권한 및 권장사항에 대해 설명하는 IAM 커스텀 역할 이해를 읽어보세요.
gcloud 명령줄 유틸리티를 사용하는 경우 버전 188.0.0 이상을 사용하는지 확인하세요. gcloud를 버전 188.0.0으로 업데이트하려면 gcloud components update --version 188.0.0 명령어를 실행합니다.

리소스에 사용 가능한 권한 보기

커스텀 역할을 만들기 전에 리소스에 적용할 수 있는 권한이 무엇인지 확인하는 것이 좋습니다. 리소스에 적용 가능한 모든 권한 및 계층 구조에서 해당 리소스에 속하는 리소스를 확인하려면 gcloud 명령줄 도구, Google Cloud Console 또는 ID 및 액세스 관리 API를 사용합니다. 예를 들어 조직 및 해당 조직의 프로젝트에 적용 가능한 모든 권한을 가져올 수 있습니다.

Console

Cloud Console에서 역할 페이지로 이동합니다.

역할 페이지로 이동
페이지 상단의 드롭다운에서 프로젝트를 선택합니다.
리소스의 관리자 역할 체크박스를 선택하여 해당 리소스에 적용 가능한 모든 권한을 확인합니다. 예를 들어 Compute 인스턴스 관리자 역할을 선택하면 오른쪽 패널에는 Compute Engine 인스턴스에 적용할 수 있는 모든 권한이 표시됩니다.

gcloud 명령어

대상 리소스에 적용할 수 있는 권한 목록을 가져오려면 gcloud iam list-testable-permissions 명령어를 사용합니다. 반환되는 권한은 이 리소스와 계층구조에서 해당 리소스에 속하는 모든 리소스에 커스텀 역할을 만드는 데 사용할 수 있는 권한입니다.

다음 예시에서는 프로젝트 리소스에서 테스트 가능한 권한을 나열하는 방법을 보여줍니다.

gcloud iam list-testable-permissions project-id

project-id는 프로젝트 ID이며 전체 리소스 이름은 //cloudresourcemanager.googleapis.com/projects/project-id 형식을 따릅니다(예: //cloudresourcemanager.googleapis.com/projects/my-project-id).

list-testable-permissions 명령어는 결과 수백 개를 반환할 수 있습니다. 결과를 제한하려면 필터식을 지정하면 됩니다. 다음은 가능한 결과를 발췌한 예시입니다.

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

각 권한에 커스텀 역할 지원 여부가 표시됩니다. 지원되는 권한 및 지원되지 않는 권한의 전체 목록은 커스텀 역할 권한 지원을 참조하세요.

REST API

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)

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default 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 application-default 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 탐색기(브라우저)

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 요청 본문을 이 도구에 붙여넣고 다른 필수 필드를 입력한 후 실행을 클릭합니다.

다음과 비슷한 JSON 응답이 표시됩니다.

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

C#

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 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 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 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 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 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 및 역할에 포함된 권한 등이 있습니다. Cloud Console 또는 IAM API를 사용하여 메타데이터를 볼 수 있습니다.

역할 메타데이터를 보려면 아래 방법 중 하나를 사용합니다.

Console

Cloud Console에서 역할 페이지로 이동합니다.

역할 페이지로 이동
페이지 상단의 드롭다운 목록에서 조직 또는 프로젝트를 선택합니다.
권한을 확인할 역할의 체크박스를 하나 이상 선택합니다. 역할에 포함된 권한이 있으면 오른쪽 패널에 이 권한이 표시됩니다.

유형 열의 아이콘은 커스텀 역할 또는 사전 정의된 역할

특정 권한을 포함하는 역할을 모두 찾으려는 경우 역할 목록 상단의 필터 상자에 권한 이름을 입력합니다.

gcloud 명령어

사전 정의된 역할과 커스텀 역할의 메타데이터를 보려면 gcloud iam roles describe 명령어를 사용합니다.

사전 정의된 역할의 메타데이터를 보려면 다음 gcloud 명령어를 실행합니다.

gcloud iam roles describe role-id

role-id는 역할 ID입니다. 사전 정의된 역할의 ID에는 role 프리픽스가 포함됩니다(예: roles/iam.roleViewer).

다음 예시에서는 사전 정의된 역할 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-id
```
프로젝트 수준에서 생성된 커스텀 역할의 메타데이터를 보려면 다음 명령어를 실행합니다.
```
gcloud iam roles describe --project=project-id role-id
```

각 자리표시자 값은 아래에 설명되어 있습니다.

organization-id는 조직의 숫자 ID입니다(예: 123456789012).
project-id는 프로젝트 이름입니다(예: my-project-id).
role-id는 역할 ID이며 projects/, organizations/, roles/와 같은 프리픽스는 제외됩니다. 예를 들면 myCompanyAdmin입니다.

자세한 내용은 gcloud iam roles describe 참조 문서를 확인하세요.

REST API

roles.get 메서드는 역할의 정의를 가져옵니다.

아래의 요청 데이터를 사용하기 전에 다음을 바꿉니다.

full-role-id: organizations/, projects/, roles/ 프리픽스를 포함한 전체 역할 ID입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin입니다.

참고: 전체 역할 ID를 모르는 경우 roles.list 메서드를 사용하여 조직 또는 프로젝트의 모든 커스텀 역할 또는 모든 IAM 사전 정의된 역할을 나열합니다. 전체 역할 ID는 응답 본문의 name 필드입니다.

HTTP 메서드 및 URL:

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

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

다음 명령어를 실행합니다.

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

PowerShell(Windows)

다음 명령어를 실행합니다.

$cred = gcloud auth application-default 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 탐색기(브라우저)

메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 모든 필수 필드를 입력하고 실행을 클릭합니다.

응답에 역할 정의가 포함됩니다.

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

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 IAM C# API 참조 문서를 확인하세요.

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

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 IAM Go API 참조 문서를 확인하세요.

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 역할 관리자 역할을 할당해야 합니다.

커스텀 역할의 제목, 설명, 권한 이름의 총 크기는 64KB로 제한됩니다. 더 큰 커스텀 역할을 만들어야 하는 경우에는 권한을 커스텀 역할 여러 개로 분할하면 됩니다. 커스텀 역할 간의 관계(예: Custom Admin (1 of 2) 및 Custom Admin (2 of 2))를 보여주는 역할 제목을 선택합니다.

Console

커스텀 역할을 처음부터 새로 만들려면 다음 안내를 따르세요.

Cloud Console에서 역할 페이지로 이동합니다.

역할 페이지로 이동
페이지 상단의 드롭다운 목록을 사용하여 역할을 만들려는 조직 또는 프로젝트를 선택합니다.
역할 만들기를 클릭합니다.
역할의 이름, 제목, 설명을 입력합니다.
권한 추가를 클릭합니다.
역할에 포함할 권한을 선택하고 권한 추가를 클릭합니다. 모든 서비스 및 모든 유형 드롭다운을 사용하여 서비스와 유형에 따라 권한을 필터링하고 선택합니다.

기존의 선별된 역할을 기반으로 커스텀 역할을 만드는 방법은 다음과 같습니다.

Cloud Console에서 역할 페이지로 이동합니다.
역할 페이지로 이동
역할을 만들려는 조직 또는 프로젝트를 선택합니다.
새 커스텀 역할을 만드는 데 사용할 역할을 선택합니다.
기존 역할에서 역할 만들기를 클릭합니다.
역할의 이름, 제목, 설명을 입력합니다.
역할에서 제외할 권한을 선택 해제합니다.
권한 추가를 클릭하여 권한을 포함합니다.
만들기를 클릭합니다.

gcloud 명령어

새 커스텀 역할을 만들려면 gcloud iam roles create 명령어를 사용합니다. 두 가지 방법으로 이 명령어를 사용할 수 있습니다.

역할 정의를 포함하는 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 API

roles.create 메서드는 프로젝트 또는 조직에 커스텀 역할을 만듭니다.

아래의 요청 데이터를 사용하기 전에 다음을 바꿉니다.

resource-type: 관리하려는 커스텀 역할을 포함하는 리소스 유형입니다. projects 또는 organizations 값을 사용합니다.
resource-id: 관리하려는 커스텀 역할을 포함하는 프로젝트 ID 또는 조직 ID입니다.
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 application-default 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 application-default 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 탐색기(브라우저)

응답에 생성된 역할이 포함됩니다.

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

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 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 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 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 IAM Go API 참조 문서를 확인하세요.

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

기존 커스텀 역할 수정

읽기-수정-쓰기

리소스의 커스텀 역할과 같은 메타데이터를 업데이트하는 일반적인 패턴은 현재 상태를 읽고, 데이터를 로컬에서 업데이트하고, 수정된 데이터를 전송하여 기록하는 것입니다. 이 패턴에서는 서로 독립된 둘 이상의 프로세스가 동시에 시퀀스를 시도할 경우 충돌이 발생할 수 있습니다. 예를 들어 프로젝트 소유자 두 명이 동시에 상충하는 역할 변경을 시도할 경우 변경이 일부 실패할 수 있습니다. IAM은 커스텀 역할에서 etag 속성을 사용해 이 문제를 해결합니다. 이 속성은 마지막 요청 이후 커스텀 역할의 변경 여부를 확인하는 데 사용됩니다. etag 값으로 IAM에 요청을 수행하면 IAM이 요청의 etag 값을 커스텀 역할과 연결된 기존 etag 값과 비교합니다. 이때 etag 값이 일치하는 경우에만 정책을 씁니다.

역할을 업데이트할 때는 일단 roles.get()를 사용해 역할을 가져와 업데이트한 다음 roles.patch()를 사용해 업데이트된 정책을 씁니다. 역할을 설정할 때는 roles.get()에서 해당하는 역할에 etag 값이 있는 경우에만 etag 값을 사용하세요.

Console

Cloud Console에서 역할 페이지로 이동합니다.

역할 페이지로 이동
페이지 상단의 드롭다운 목록을 사용하여 편집하려는 역할이 포함된 프로젝트 또는 조직을 선택합니다.
커스텀 역할을 클릭합니다.
역할 수정을 클릭합니다.
권한 추가를 클릭하여 역할에 새 권한을 추가합니다.
권한을 선택 해제하여 역할에서 권한을 삭제합니다.
업데이트를 클릭하여 수정한 역할을 저장합니다.

gcloud 명령어

커스텀 역할을 업데이트하려면 gcloud iam roles update 명령어를 사용합니다. 두 가지 방법으로 이 명령어를 사용할 수 있습니다.

업데이트된 역할 정의를 포함하는 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: full-role-id
stage: launch-stage
title: role-title

각 자리표시자 값은 아래에 설명되어 있습니다.

role-description은 역할에 대한 간단한 설명입니다(예: "My custom role description").
etag-value는 역할의 현재 버전에 대한 고유 식별자입니다(예: BwVkBkbfr70=).
permission-1 및 permission-2는 커스텀 역할(예: iam.roles.get)에 포함할 권한입니다.
full-role-id는 organizations/, projects/ 또는 roles/ 프리픽스가 포함된 전체 역할 ID입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin.입니다.
launch-stage는 출시 수명 주기에서 역할의 단계를 나타냅니다(예: ALPHA, BETA, GA).
role-title은 역할의 별칭입니다(예: "My Company Admin").

역할을 업데이트하려면 출력된 역할 정의를 YAML 파일에 포함하거나 원본 YAML 파일을 출력된 etag 값으로 업데이트합니다.

다음 YAML 파일 예시에는 프로젝트 수준 역할에서 describe 명령어의 결과를 포함하고 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 API

roles.patch 메서드는 프로젝트 또는 조직에 커스텀 역할을 업데이트합니다.

아래의 요청 데이터를 사용하기 전에 다음을 바꿉니다.

필수:

resource-type: 관리하려는 커스텀 역할을 포함하는 리소스 유형입니다. projects 또는 organizations 값을 사용합니다.
resource-id: 관리하려는 커스텀 역할을 포함하는 프로젝트 ID 또는 조직 ID입니다.
full-role-id: organizations/, projects/, roles/ 프리픽스를 포함한 전체 역할 ID입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin입니다.

참고: 전체 역할 ID를 모르는 경우 roles.list 메서드를 사용하여 조직 또는 프로젝트의 모든 커스텀 역할 또는 모든 IAM 사전 정의된 역할을 나열합니다. 전체 역할 ID는 응답 본문의 name 필드입니다.

다음을 권장합니다.

etag: 역할의 버전 식별자입니다. 다른 역할 변경사항을 덮어쓰지 않도록 하려면 이 필드를 포함하세요.

선택사항(다음 값 중 하나 이상 정의):

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 application-default 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 application-default 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 탐색기(브라우저)

응답에는 역할 이름이 포함된 축약된 역할 정의, 업데이트한 필드, 현재 역할 버전을 식별하는 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#

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 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 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 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 IAM Go API 참조 문서를 확인하세요.

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

커스텀 역할 사용 중지

커스텀 역할을 사용 중지할 수 있습니다. 역할을 사용 중지하면 역할과 관련된 정책 바인딩이 비활성화됩니다. 즉, 사용자에게 역할을 부여해도 역할의 권한이 부여되지 않습니다.

Console

Cloud Console에서 역할 페이지로 이동합니다.

역할 페이지로 이동
페이지 상단에서 '프로젝트 선택' 드롭다운을 클릭합니다.
조직 또는 프로젝트를 선택합니다.
커스텀 역할을 선택하고 사용 중지를 클릭합니다.

gcloud 명령어

커스텀 역할을 중지하려면 gcloud iam roles update 명령어를 사용하여 실행 단계를 DISABLED로 설정합니다. 기존 커스텀 역할 수정 섹션의 gcloud 탭의 설명대로 다음 두 가지 방법으로 기존 커스텀 역할을 업데이트할 수 있습니다.

업데이트된 역할 정의를 포함하는 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 API

roles.patch 메서드를 사용하면 역할을 사용 중지하는 DISABLED로 커스텀 역할의 실행 단계를 변경할 수 있습니다.

아래의 요청 데이터를 사용하기 전에 다음을 바꿉니다.

resource-type: 관리하려는 커스텀 역할을 포함하는 리소스 유형입니다. projects 또는 organizations 값을 사용합니다.
resource-id: 관리하려는 커스텀 역할을 포함하는 프로젝트 ID 또는 조직 ID입니다.
full-role-id: organizations/, projects/, roles/ 프리픽스를 포함한 전체 역할 ID입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin입니다.

참고: 전체 역할 ID를 모르는 경우 roles.list 메서드를 사용하여 조직 또는 프로젝트의 모든 커스텀 역할 또는 모든 IAM 사전 정의된 역할을 나열합니다. 전체 역할 ID는 응답 본문의 name 필드입니다.
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 application-default 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 application-default 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 탐색기(브라우저)

다음과 비슷한 JSON 응답이 표시됩니다.

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

C#

역할의 stage 필드를 DISABLED로 업데이트합니다.

Go

역할의 stage 필드를 DISABLED로 업데이트합니다.

Python

역할의 stage 필드를 DISABLED로 업데이트합니다.

역할 나열

프로젝트 또는 조직에 생성된 모든 커스텀 역할을 나열할 수 있습니다.

Console

Cloud Console에서 역할 페이지로 이동합니다.

역할 페이지로 이동

선택한 조직 또는 프로젝트의 모든 커스텀 역할이 페이지에 나열됩니다.

gcloud 명령어

프로젝트 또는 조직의 커스텀 역할과 사전 정의된 역할을 나열하려면 gcloud iam roles list 명령어를 사용합니다.

커스텀 역할을 나열하려면 다음 명령어 중 하나를 실행합니다.

조직 수준 커스텀 역할을 나열하려면 다음 명령어를 실행합니다.
```
gcloud iam roles list --organization=organization-id
```
프로젝트 수준 커스텀 역할을 나열하려면 다음 명령어를 실행합니다.
```
gcloud iam roles list --project=project-id
```

각 자리표시자 값은 아래에 설명되어 있습니다.

organization-id는 조직의 숫자 ID입니다(예: 123456789012).
project-id는 프로젝트 이름입니다(예: my-project-id).

삭제된 역할을 나열하려면 --show-deleted 플래그를 지정하면 됩니다.

다음 gcloud 명령어를 실행하여 사전 정의된 역할을 나열합니다.

gcloud iam roles list

REST API

roles.list 메서드는 프로젝트 또는 조직의 모든 커스텀 역할을 나열합니다.

아래의 요청 데이터를 사용하기 전에 다음을 바꿉니다.

resource-type: 관리하려는 커스텀 역할을 포함하는 리소스 유형입니다. projects 또는 organizations 값을 사용합니다.
resource-id: 관리하려는 커스텀 역할을 포함하는 프로젝트 ID 또는 조직 ID입니다.
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 application-default 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 application-default 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 탐색기(브라우저)

다음과 비슷한 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#

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 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<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 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 IAM Go API 참조 문서를 확인하세요.

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'])

커스텀 역할 삭제

프로젝트 또는 조직의 커스텀 역할을 삭제할 수 있습니다.

Console

Cloud Console에서 역할 페이지로 이동합니다.

역할 페이지로 이동
삭제하려는 역할을 선택하고 페이지 상단에 있는 삭제를 클릭합니다.

gcloud 명령어

커스텀 역할을 삭제하려면 gcloud iam roles delete 명령어를 사용합니다. 역할이 새 IAM 정책 binding을 만드는 데 사용될 수 없도록 정지됩니다.

커스텀 역할을 삭제하려면 다음 명령어 중 하나를 실행합니다.

조직 수준 커스텀 역할을 삭제하려면 다음 명령어를 실행합니다.
```
gcloud iam roles delete role-id --organization=organization-id
```
프로젝트 수준 커스텀 역할을 삭제하려면 다음 명령어를 실행합니다.
```
gcloud iam roles delete role-id --project=project-id
```

각 자리표시자 값은 아래에 설명되어 있습니다.

role-id는 역할 이름입니다(예: myCompanyAdmin).
organization-id는 조직의 숫자 ID입니다(예: 123456789012).
project-id는 프로젝트 이름입니다(예: my-project-id).

--show-deleted 플래그가 포함되어 있지 않으면 역할이 gcloud iam roles list에 포함되지 않습니다. 삭제된 역할은 list 응답에 deleted: true 블록으로 표시됩니다. 예를 들면 다음과 같습니다.

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

REST API

roles.delete 메서드는 프로젝트 또는 조직에서 커스텀 역할을 삭제합니다.

아래의 요청 데이터를 사용하기 전에 다음을 바꿉니다.

full-role-id: organizations/, projects/, roles/ 프리픽스를 포함한 전체 역할 ID입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin입니다.

참고: 전체 역할 ID를 모르는 경우 roles.list 메서드를 사용하여 조직 또는 프로젝트의 모든 커스텀 역할 또는 모든 IAM 사전 정의된 역할을 나열합니다. 전체 역할 ID는 응답 본문의 name 필드입니다.

HTTP 메서드 및 URL:

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

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

다음 명령어를 실행합니다.

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

PowerShell(Windows)

다음 명령어를 실행합니다.

$cred = gcloud auth application-default 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 탐색기(브라우저)

응답에 삭제된 역할 정의가 포함됩니다.

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

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 IAM C# API 참조 문서를 확인하세요.

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

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 IAM Go API 참조 문서를 확인하세요.

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일 동안 역할은 Cloud Console에 삭제됨으로 표시되며 요청에서 showDeleted가 설정되기 전까지 프로그래매틱 방식으로 list 명령어에 표시되지 않습니다.

7일이 지나면 역할은 영구 삭제되도록 예약됩니다. 이 시점에서 역할은 더 이상 조직당 커스텀 역할 300개 또는 프로젝트당 커스텀 역할 300개 한도에 포함되지 않습니다.

영구 삭제하는 데 30일이 소요됩니다. 30일 동안 역할과 역할에 연결된 모든 binding이 영구 삭제되며 이 기간 동안에는 같은 역할 ID로 새 역할을 만들 수 없습니다.

최초 삭제 요청 후 37일에 역할이 영구 삭제되면 같은 역할 ID로 새 역할을 만들 수 있습니다.

커스텀 역할 삭제 취소

역할을 삭제 취소하면 이전 상태로 돌아갑니다.

역할은 7일 이내에만 삭제 취소할 수 있습니다. 7일이 지나면 역할이 영구적으로 삭제되고 역할에 연결된 모든 binding이 삭제됩니다.

Console

Cloud Console에서 역할 페이지로 이동합니다.

역할 페이지로 이동
삭제 취소할 역할을 찾아서 행 끝의 더보기 아이콘을 클릭하고 삭제 취소를 클릭합니다.

gcloud 명령어

커스텀 역할을 삭제 취소하려면 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 API

roles.undelete 메서드는 프로젝트 또는 조직에서 커스텀 역할을 삭제 취소합니다.

아래의 요청 데이터를 사용하기 전에 다음을 바꿉니다.

full-role-id: organizations/, projects/, roles/ 프리픽스를 포함한 전체 역할 ID입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin입니다.

참고: 전체 역할 ID를 모르는 경우 roles.list 메서드를 사용하여 조직 또는 프로젝트의 모든 커스텀 역할 또는 모든 IAM 사전 정의된 역할을 나열합니다. 전체 역할 ID는 응답 본문의 name 필드입니다.
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 application-default 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 application-default 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 탐색기(브라우저)

응답에 삭제 취소된 역할 정의가 포함됩니다.

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

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 IAM C# API 참조 문서를 확인하세요.

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

이 샘플을 사용해 보기 전에 IAM 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 IAM Go API 참조 문서를 확인하세요.

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

다음 단계

구성원에게 역할을 부여하는 방법 알아보기
특정 조건이 충족되는 경우에만 역할을 부여하는 조건부 역할 부여 알아보기