커스텀 역할 생성 및 관리

이 페이지에서는 Identity and Access Management(IAM) 커스텀 역할을 만들고 관리하는 방법을 설명합니다. 역할 관리에는 역할 수정, 사용 중지, 나열, 삭제, 삭제 취소가 포함됩니다.

시작하기 전에

• Enable the IAM API.

  Enable the API

• 인증을 설정합니다.

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

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

  C#

  로컬 개발 환경에서 이 페이지의 .NET 샘플을 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

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

     gcloud auth application-default login

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

  자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경용 ADC 설정을 참고하세요.

  C++

  로컬 개발 환경에서 이 페이지의 C++ 샘플을 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

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

     gcloud auth application-default login

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

  자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경용 ADC 설정을 참고하세요.

  Go

  로컬 개발 환경에서 이 페이지의 Go 샘플을 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

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

     gcloud auth application-default login

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

  자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경용 ADC 설정을 참고하세요.

  Java

  로컬 개발 환경에서 이 페이지의 Java 샘플을 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

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

     gcloud auth application-default login

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

  자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경용 ADC 설정을 참고하세요.

  Python

  로컬 개발 환경에서 이 페이지의 Python 샘플을 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

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

     gcloud auth application-default login

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

  자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경용 ADC 설정을 참고하세요.

  REST

  로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

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

  gcloud init

  자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참고하세요.

• Google Cloud 리소스 계층 구조를 이해합니다.

• IAM 커스텀 역할 이해를 읽어보세요.

필요한 역할

커스텀 역할을 만들고 관리하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• 프로젝트에 대한 역할을 관리하려는 경우: 역할을 관리할 프로젝트에 대한 역할 관리자(roles/iam.roleAdmin)
• 조직에 대한 역할을 관리하려는 경우: 역할을 관리할 조직에 대한 조직 역할 관리자(roles/iam.organizationRoleAdmin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

프로젝트, 폴더, 조직에 사용 가능한 권한 보기

전체 조직이나 해당 조직의 특정 프로젝트에 대한 커스텀 역할을 만들 수 있습니다. 커스텀 역할에 사용할 수 있는 권한은 역할을 만드는 위치에 따라 다릅니다. 예를 들어 권한이 조직 수준에서만 사용될 수 있으면 프로젝트 수준 커스텀 역할에 이 권한을 포함할 수 없습니다.

조직 수준 및 프로젝트 수준 커스텀 역할에 사용할 수 있는 권한을 확인하려면 gcloud CLI나 Identity and Access Management API를 사용하여 특정 조직 또는 프로젝트에서 사용할 수 있는 권한을 나열할 수 있습니다. 예를 들어 프로젝트에서 생성된 커스텀 역할에 사용할 수 있는 모든 권한을 가져올 수 있습니다.

일부 권한이 커스텀 역할에서 지원되더라도 사용자에게 표시되지 않거나 커스텀 역할에서 사용되지 않을 수 있습니다. 예를 들어 서비스에 API를 사용 설정하지 않으면 커스텀 역할에서 사용할 수 있는 권한을 사용하지 못할 수 있습니다.

커스텀 역할에 추가할 수 있는 권한에 대한 자세한 내용은 지원되는 권한을 참조하세요.

gcloud

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

   Activate Cloud Shell

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

2. 특정 프로젝트나 조직에서 커스텀 역할에 사용할 수 있는 권한의 목록을 가져오려면 gcloud iam list-testable-permissions 명령어를 사용합니다. 응답에는 프로젝트나 조직의 커스텀 역할에 사용할 수 있는 권한이 나열됩니다.

   프로젝트나 조직의 커스텀 역할에서 사용할 수 있는 권한을 나열하려면 다음 명령어를 실행합니다.

   gcloud iam list-testable-permissions FULL_RESOURCE_NAME \
       --filter="customRolesSupportLevel!=NOT_SUPPORTED"

   FULL_RESOURCE_NAME을 다음 값 중 하나로 바꿉니다.

   • 프로젝트: //cloudresourcemanager.googleapis.com/projects/PROJECT_ID(예: //cloudresourcemanager.googleapis.com/projects/my-project)

   • 조직: //cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID(예: //cloudresourcemanager.googleapis.com/organizations/123456789012)

   결과에는 각 권한이 커스텀 역할에서 지원되는지 여부가 표시됩니다. customRolesSupportLevel 필드가 없는 권한은 완전히 지원됩니다.

   list-testable-permissions 명령어는 결과 수백 개를 반환할 수 있습니다. 이 부분 예시에서는 각 결과의 형식을 보여줍니다.

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

C++

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C++ API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& resource) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::QueryTestablePermissionsRequest request;
  request.set_full_resource_name(resource);
  int count = 0;
  for (auto& permission : client.QueryTestablePermissions(request)) {
    if (!permission) throw std::move(permission).status();
    std::cout << "Permission successfully retrieved: " << permission->name()
              << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No testable permissions found in resource: " << resource
              << "\n";
  }
}

C#

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C# API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

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

        var request = new QueryTestablePermissionsRequest
        {
            FullResourceName = fullResourceName
        };
        var response = service.Permissions.QueryTestablePermissions(request)
            .Execute();
        foreach (var p in response.Permissions)
        {
            Console.WriteLine(p.Name);
        }
        return response.Permissions;
    }
}

Go

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Go API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Java API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.cloud.iam.admin.v1.IAMClient.QueryTestablePermissionsPagedResponse;
import com.google.iam.admin.v1.QueryTestablePermissionsRequest;
import java.io.IOException;

/** View available permissions in a project. */
public class QueryTestablePermissions {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    // Full resource names can take one of the following forms:
    // cloudresourcemanager.googleapis.com/projects/PROJECT_ID
    // cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID
    String fullResourceName = "your-full-resource-name";

    queryTestablePermissions(fullResourceName);
  }

  public static void queryTestablePermissions(String fullResourceName) throws IOException {
    QueryTestablePermissionsRequest queryTestablePermissionsRequest =
        QueryTestablePermissionsRequest.newBuilder().setFullResourceName(fullResourceName).build();

    try (IAMClient iamClient = IAMClient.create()) {
      QueryTestablePermissionsPagedResponse queryTestablePermissionsPagedResponse =
          iamClient.queryTestablePermissions(queryTestablePermissionsRequest);
      queryTestablePermissionsPagedResponse
          .iterateAll()
          .forEach(permission -> System.out.println(permission.getName()));
    }
  }
}

Python

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Python API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

from typing import List

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2, policy_pb2


def query_testable_permissions(
    project_id: str, permissions: List[str]
) -> policy_pb2.Policy:
    """
    Tests IAM permissions of the caller.

    project_id: ID or number of the Google Cloud project you want to use.
    """

    client = resourcemanager_v3.ProjectsClient()
    request = iam_policy_pb2.TestIamPermissionsRequest()
    request.resource = f"projects/{project_id}"
    request.permissions.extend(permissions)

    permissions_reponse = client.test_iam_permissions(request)
    print(permissions_reponse)
    return permissions_reponse.permissions

REST

permissions.queryTestablePermissions 메서드는 조직이나 프로젝트에서 사용할 수 있는 권한을 나열합니다.

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

• FULL_RESOURCE_NAME: 서비스 이름과 리소스 경로로 구성된 URI입니다. 예시는 전체 리소스 이름을 참조하세요.
• PAGE_SIZE: 선택사항. 응답에 포함할 권한 수입니다. 기본값은 100이고 최댓값은 1,000입니다. 권한 수가 페이지 크기보다 크면 다음 결과 페이지를 검색하기 위해 사용할 수 있는 페이지로 나누기 토큰이 응답에 포함됩니다.
• NEXT_PAGE_TOKEN: 선택사항. 이 메서드의 이전 응답에서 반환된 페이지 나누기 토큰입니다. 지정된 경우 이전 응답이 종료된 위치에서 테스트 가능한 권한 목록이 시작됩니다.

HTTP 메서드 및 URL:

POST https://iam.googleapis.com/v1/permissions:queryTestablePermissions

JSON 요청 본문:

{
  "fullResourceName": "FULL_RESOURCE_NAME"
  "pageSize": PAGE_SIZE,
  "pageToken": "NEXT_PAGE_TOKEN"
}

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

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

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

API 탐색기(브라우저)

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

응답에는 권한 목록이 포함됩니다.

참고: customRolesSupportLevel 필드가 없는 권한은 커스텀 역할에서 완전히 지원됩니다.

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

역할 메타데이터 가져오기

커스텀 역할을 만들기 전에 사전 정의된 역할과 커스텀 역할의 메타데이터를 가져오는 것이 좋습니다. 역할 메타데이터로는 역할 ID 및 역할에 포함된 권한 등이 있습니다. Google Cloud Console 또는 IAM API를 사용하여 메타데이터를 볼 수 있습니다.

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

Console

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

   역할 페이지로 이동

2. 페이지 상단의 드롭다운 목록에서 조직 또는 프로젝트를 선택합니다.

3. 권한을 확인할 역할의 체크박스를 하나 이상 선택합니다. 역할에 포함된 권한이 있으면 오른쪽 패널에 이 권한이 표시됩니다.

유형 열의 아이콘은 커스텀 역할('공장' 아이콘) 또는 사전 정의된 역할(육각형 아이콘)인지를 나타냅니다.

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

gcloud

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

   Activate Cloud Shell

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

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

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

   gcloud iam roles describe ROLE_ID

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

   다음 예시에서는 사전 정의된 역할 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 iam roles describe --organization=ORGANIZATION_ID ROLE_ID

   • 프로젝트 수준에서 생성된 커스텀 역할의 메타데이터를 보려면 다음 명령어를 실행합니다.

     gcloud iam roles describe --project=PROJECT_ID ROLE_ID

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

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

   • ROLE_ID는 역할 ID이며 projects/, organizations/, roles/와 같은 프리픽스는 제외됩니다. 예를 들면 myCompanyAdmin입니다.

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

C++

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C++ API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::GetRoleRequest request;
  request.set_name(name);
  auto response = client.GetRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully retrieved: " << response->DebugString()
            << "\n";
}

C#

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C# API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

public partial class CustomRoles
{
    public static Role GetRole(string name)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = service.Roles.Get(name).Execute();
        Console.WriteLine(role.Name);
        Console.WriteLine(String.Join(", ", role.IncludedPermissions));
        return role;
    }
}

Go

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Go API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Java API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.GetRoleRequest;
import com.google.iam.admin.v1.Role;
import java.io.IOException;

/** Get role metadata. Specifically, printing out role permissions. */
public class GetRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    String roleId = "a unique identifier (e.g. testViewer)";

    getRole(roleId);
  }

  public static void getRole(String roleId) throws IOException {
    GetRoleRequest getRoleRequest = GetRoleRequest.newBuilder().setName(roleId).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role role = iamClient.getRole(getRoleRequest);
      role.getIncludedPermissionsList().forEach(permission -> System.out.println(permission));
    }
  }
}

Python

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Python API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

from google.api_core.exceptions import NotFound
from google.cloud.iam_admin_v1 import GetRoleRequest, IAMClient, Role


def get_role(project_id: str, role_id: str) -> Role:
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = GetRoleRequest(name=name)
    try:
        role = client.get_role(request)
        print(f"Retrieved role: {role_id}: {role}")
        return role
    except NotFound:
        raise f"Role with id [{role_id}] not found, take some actions"

REST

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

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

• ROLE_NAME: organizations/, projects/ 또는 roles/ 프리픽스가 포함된 전체 역할 이름입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin입니다.

HTTP 메서드 및 URL:

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

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

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

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

API 탐색기(브라우저)

메서드 참조 페이지를 엽니다. 페이지 오른쪽에 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="
}

맞춤 역할 만들기

프로젝트 또는 조직 수준에서 커스텀 역할을 만들 수 있습니다.

참고: 폴더 수준에서는 커스텀 역할을 정의할 수 없습니다. 폴더 내에서 커스텀 역할을 사용해야 하는 경우 조직 수준에서 커스텀 역할을 정의합니다.

조직 수준 커스텀 역할에는 커스텀 역할에서 지원되는 IAM 권한이 포함될 수 있습니다. 프로젝트 수준 커스텀 역할에는 resourcemanager.organizations.get과 같은 조직이나 폴더 수준에서만 사용할 수 있는 권한을 제외한 지원되는 모든 권한이 포함될 수 있습니다. 이러한 권한을 프로젝트 수준 커스텀 역할에 추가하려고 하면 오류 메시지가 표시됩니다.

콘솔

'프로젝트 수준의 커스텀 역할에 적용 불가'라는 경고 메시지가 표시됩니다. 권한이 포함된 권한 목록에서 자동으로 선택 취소되며 역할 만들기를 계속 진행할 수 있습니다.

gcloud

다음과 같은 오류 메시지가 반환됩니다. INVALID_ARGUMENT: Permission PERMISSION is not valid. 먼저 역할 정의에서 권한을 삭제하고 다시 작업을 시도할 때까지 커스텀 역할을 만들 수 없습니다.

REST API

HTTP 400 오류 코드 및 INVALID_ARGUMENT 상태 코드와 함께 Permission PERMISSION is not valid 오류 메시지가 반환됩니다. 먼저 역할 정의에서 권한을 삭제하고 다시 작업을 시도할 때까지 커스텀 역할을 만들 수 없습니다.

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

각 커스텀 역할에는 출시 단계가 포함될 수 있습니다. 대부분의 출시 단계는 정보 제공용이며, 각 역할을 광범위하게 사용할 준비가 되었는지 여부를 추적하는 데 도움이 됩니다. 또한 DISABLED 출시 단계에서는 커스텀 역할을 사용 중지할 수 있습니다. 출시 단계에 대한 상세 내용은 테스트 및 배포를 참조하세요.

Console

일부 사전 정의된 역할에는 지원 중단된 권한 또는 커스텀 역할에서 허용되지 않는 권한이 포함되어 있습니다. 이렇게 사전 정의된 역할을 기반으로 커스텀 역할을 만들면 커스텀 역할은 지원 중단된 권한 및 제한된 권한을 생략합니다.

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

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

   역할 페이지로 이동

2. 페이지 상단의 드롭다운 목록을 사용하여 역할을 만들려는 조직 또는 프로젝트를 선택합니다.

3. 역할 만들기를 클릭합니다.

4. 역할의 제목, 설명, ID, 역할 실행 단계를 입력합니다. 역할을 만든 후에는 역할 ID를 변경할 수 없습니다.

5. 권한 추가를 클릭합니다.

6. 역할에 포함할 권한을 선택하고 권한 추가를 클릭합니다. 모든 서비스 및 모든 유형 드롭다운 목록을 사용하여 서비스 및 유형별로 권한을 필터링하고 선택합니다.

기존의 사전 정의된 역할을 기반으로 커스텀 역할을 만들려면 다음 안내를 따르세요.

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

   역할 페이지로 이동

2. 역할을 만들려는 조직 또는 프로젝트를 선택합니다.
3. 새 커스텀 역할을 만드는 데 사용할 역할을 선택합니다.
4. 기존 역할에서 역할 만들기를 클릭합니다.
5. 역할의 제목, 설명, ID, 역할 실행 단계를 입력합니다. 역할을 만든 후에는 역할 ID를 변경할 수 없습니다.
6. 역할에서 제외할 권한을 선택 해제합니다.
7. 권한 추가를 클릭하여 권한을 포함합니다.
8. 만들기를 클릭합니다.

gcloud

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

   Activate Cloud Shell

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

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

   • 역할 정의를 포함하는 YAML 파일 제공

   • 플래그를 사용하여 역할 정의 지정

   커스텀 역할을 만들 때 --organization=ORGANIZATION_ID 또는 --project=PROJECT_ID 플래그를 사용하여 조직 수준 또는 프로젝트 수준에 적용되는지 여부를 지정해야 합니다. 아래의 각 예에서는 프로젝트 수준으로 커스텀 역할을 만듭니다.

   커스텀 역할에는 커스텀 역할에서 지원되는 권한만 포함할 수 있습니다. 커스텀 역할에 다른 권한이 포함되어 있으면 명령어가 실패합니다.

   YAML 파일을 사용하여 커스텀 역할 만들기

   커스텀 역할의 정의를 포함하는 YAML 파일을 만듭니다. 파일의 구조는 다음과 같아야 합니다.

   title: ROLE_TITLE
   description: ROLE_DESCRIPTION
   stage: LAUNCH_STAGE
   includedPermissions:
   - PERMISSION_1
   - PERMISSION_2

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

   • ROLE_TITLE은 역할의 별칭입니다(예: "My Company Admin").

   • ROLE_DESCRIPTION은 역할에 대한 간단한 설명입니다(예: "My custom role description").

   • LAUNCH_STAGE는 출시 수명 주기에서 역할의 단계를 나타냅니다(예: ALPHA, BETA, GA).

   • PERMISSION_1 및 PERMISSION_2는 커스텀 역할(예: iam.roles.get)에 포함할 권한입니다. 권한 이름에는 와일드 카드 문자(*)를 사용할 수 없습니다.

   YAML 파일을 저장한 후 다음 명령어 중 하나를 실행합니다.

   • 조직 수준에서 커스텀 역할을 만들려면 다음 명령어를 실행합니다.

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

   • 프로젝트 수준에서 커스텀 역할을 만들려면 다음 명령어를 실행합니다.

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

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

   • ROLE_ID는 역할 이름입니다(예: myCompanyAdmin).

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

   • YAML_FILE_PATH는 커스텀 역할 정의가 포함된 YAML 파일의 위치에 대한 경로입니다.

   예시

   다음은 역할 정의를 만드는 방법을 보여주는 YAML 파일의 예입니다.

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

   다음 예시에서는 YAML 파일을 사용하여 조직 수준에서 역할을 만드는 방법을 보여줍니다.

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

   역할이 성공적으로 생성되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

   다음 예시에서는 YAML 파일을 사용하여 프로젝트 수준에서 역할을 만드는 방법을 보여줍니다.

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

   역할이 성공적으로 생성되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

   플래그를 사용하여 커스텀 역할 만들기

   다음 명령어 중 하나를 실행합니다.

   • 조직 수준에서 커스텀 역할을 만들려면 다음 명령어를 실행합니다.

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

   • 프로젝트 수준에서 커스텀 역할을 만들려면 다음 명령어를 실행합니다.

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

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

   • ROLE_ID는 역할 이름입니다(예: myCompanyAdmin).

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

   • ROLE_TITLE은 역할의 별칭입니다(예: "My Company Admin").

   • ROLE_DESCRIPTION은 역할에 대한 간단한 설명입니다(예: "My custom role description.").

   • PERMISSIONS_LIST는 커스텀 역할에 포함할 권한의 쉼표로 구분된 목록을 포함합니다. 예를 들면 iam.roles.get,iam.roles.list입니다. 권한 이름에는 와일드 카드 문자(*)를 사용할 수 없습니다.

   • LAUNCH_STAGE는 출시 수명 주기에서 역할의 단계를 나타냅니다(예: ALPHA, BETA, GA).

   예시

   다음 예시에서는 플래그를 사용하여 조직 수준에서 역할을 만드는 방법을 보여줍니다.

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

   역할이 성공적으로 생성되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

   다음 예시에서는 플래그를 사용하여 프로젝트 수준에서 역할을 만드는 방법을 보여줍니다.

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

   역할이 성공적으로 생성되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

C++

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C++ API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

C#

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C# API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

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

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

Go

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Go API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Java API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

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

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

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

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

Python

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Python API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

from typing import List, Optional

from google.api_core.exceptions import AlreadyExists, FailedPrecondition
from google.cloud.iam_admin_v1 import CreateRoleRequest, IAMClient, Role


def create_role(
    project_id: str, role_id: str, permissions: List[str], title: Optional[str] = None
) -> Role:
    """
    Creates iam role with given parameters.
    Args:
        project_id: GCP project id
        role_id: id of GCP iam role
        permissions: list of iam permissions to assign to role. f.e ["iam.roles.get", "iam.roles.list"]
        title: title for iam role. role_id will be used in case of None

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()

    parent = f"projects/{project_id}"

    request = CreateRoleRequest(
        parent=parent,
        role_id=role_id,
        role=Role(title=title, included_permissions=permissions),
    )
    try:
        role = client.create_role(request)
        print(f"Created iam role: {role_id}: {role}")
        return role
    except AlreadyExists:
        print(f"Role with id [{role_id}] already exists, take some actions")
    except FailedPrecondition:
        print(
            f"Role with id [{role_id}] already exists and in deleted state, take some actions"
        )

REST

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

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

• RESOURCE_TYPE: 관리하려는 커스텀 역할을 포함하는 리소스 유형입니다. projects 또는 organizations 값을 사용합니다.
• RESOURCE_ID: 관리하려는 커스텀 역할을 포함하는 프로젝트 ID 또는 조직 ID입니다. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다. 조직 ID는 123456789012 같은 숫자입니다.
• ROLE_ID: 역할의 이름입니다(예: myCompanyAdmin).
• ROLE_TITLE: 사람이 읽을 수 있는 역할 이름입니다. 예를 들면 My Company Admin입니다.
• ROLE_DESCRIPTION: 역할에 대한 설명입니다. 예를 들면 "The company admin role allows company admins to access important resources"입니다.

• PERMISSION_1 및 PERMISSION_2: 역할에 포함하려는 권한입니다. 예를 들면 storage.objects.update입니다. 권한 이름에는 와일드 카드 문자(*)를 사용할 수 없습니다.

  커스텀 역할에는 커스텀 역할에서 지원되는 권한만 포함할 수 있습니다. 커스텀 역할에 다른 권한이 포함된 경우 요청이 실패합니다.

• LAUNCH_STAGE: 역할의 현재 실행 단계입니다. 이 필드에는 EAP, ALPHA, BETA, GA, DEPRECATED, DISABLED 값 중 하나가 포함될 수 있습니다.

HTTP 메서드 및 URL:

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

JSON 요청 본문:

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

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

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

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

API 탐색기(브라우저)

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 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="
}

기존 커스텀 역할 수정

리소스의 메타데이터(예: 커스텀 역할)를 업데이트하는 일반적인 패턴은 읽기-수정-쓰기 패턴입니다. 이 패턴을 사용하면 역할의 현재 상태를 읽고 데이터를 로컬에서 업데이트한 다음 쓰기를 수행하기 위해 수정된 데이터를 전송합니다.

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

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

참고: 커스텀 역할을 수정하면서 resourcemanager.organizations.get, resourcemanager.folders.get, resourcemanager.projects.get 권한 중 하나라도 추가 또는 삭제하는 경우 organizations.search 및 folders.search Cloud Resource Manager API에 커스텀 역할 변경사항이 적용되기까지 최대 24시간이 걸릴 수 있습니다. projects.list API를 호출할 때도 상위 유형 및 ID를 지정하는 필터를 제공하지 않으면 이와 같은 지연 시간이 적용됩니다. 이러한 지연 시간이 발생하는 이유는 권한에 검색 기능이 포함되어 있으며 검색 색인이 다시 빌드되기까지 최대 24시간이 걸릴 수 있기 때문입니다.

Console

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

   역할 페이지로 이동

2. 페이지 상단의 드롭다운 목록을 사용하여 편집하려는 역할이 포함된 프로젝트 또는 조직을 선택합니다.

3. 커스텀 역할을 클릭합니다.

4. 역할 수정을 클릭합니다.

5. 역할의 메타데이터를 업데이트하려면 역할의 제목, 설명 또는 역할 실행 단계를 수정합니다.

6. 역할의 권한을 업데이트하려면 다음을 수행합니다.

   1. 권한 추가를 클릭하여 역할에 새 권한을 추가합니다.
   2. 권한을 선택 해제하여 역할에서 권한을 삭제합니다.

7. 업데이트를 클릭하여 수정한 역할을 저장합니다.

gcloud

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

   Activate Cloud Shell

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

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

   • 업데이트된 역할 정의를 포함하는 YAML 파일 제공

   • 플래그를 사용하여 업데이트된 역할 정의 지정

   커스텀 역할을 업데이트할 때 --organization=ORGANIZATION_ID 또는 --project=PROJECT_ID 플래그를 사용하여 조직 수준 또는 프로젝트 수준에 적용되는지 여부를 지정해야 합니다. 아래의 각 예에서는 프로젝트 수준으로 커스텀 역할을 만듭니다.

   YAML 파일을 사용하여 커스텀 역할 업데이트:

   다음 명령어 중 하나를 실행하여 역할의 현재 정의를 가져옵니다.

   • 조직 수준 커스텀 역할의 역할 정의를 가져오려면 다음 명령어를 실행합니다.

     gcloud iam roles describe ROLE_ID --organization=ORGANIZATION_ID

   • 프로젝트 수준 커스텀 역할의 역할 정의를 가져오려면 다음 명령어를 실행합니다.

     gcloud iam roles describe ROLE_ID --project=PROJECT_ID

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

   • ROLE_ID는 업데이트할 역할의 이름입니다(예: myCompanyAdmin).

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

   describe 명령어는 역할의 정의를 반환하고 역할의 현재 버전을 고유하게 식별하는 etag 값을 포함합니다. 동시에 발생하는 역할 변경사항을 덮어쓰지 않도록 업데이트된 역할 정의에 etag 값을 제공해야 합니다.

   describe 명령어는 다음 출력을 반환합니다.

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

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

   • ROLE_DESCRIPTION은 역할에 대한 간단한 설명입니다(예: "My custom role description").

   • ETAG는 역할의 현재 버전에 대한 고유 식별자입니다(예: BwVkBkbfr70=).

   • PERMISSION_1 및 PERMISSION_2는 커스텀 역할(예: iam.roles.get)에 포함할 권한입니다. 권한 이름에는 와일드 카드 문자(*)를 사용할 수 없습니다.

   • ROLE_NAME은 organizations/, projects/ 또는 roles/ 프리픽스가 포함된 전체 역할 이름입니다. 예를 들면 다음과 같습니다. organizations/123456789012/roles/myCompanyAdmin.

   • LAUNCH_STAGE는 출시 수명 주기에서 역할의 단계를 나타냅니다(예: ALPHA, BETA, GA).

   • ROLE_TITLE은 역할의 별칭입니다(예: "My Company Admin").

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

   다음 YAML 파일 예시에는 프로젝트 수준 역할에서 describe 명령어의 결과를 포함하고 Cloud Storage 권한 두 개를 추가합니다.

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

   YAML 파일을 저장한 후 다음 명령어 중 하나를 실행합니다.

   • 조직 수준 역할을 업데이트하려면 다음 명령어를 실행합니다.

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

   • 프로젝트 수준 역할을 업데이트하려면 다음 명령어를 실행합니다.

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

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

   • ROLE_ID는 업데이트할 역할의 이름입니다(예: myCompanyAdmin).

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project-id).

   • YAML_FILE_PATH는 업데이트된 커스텀 역할 정의가 포함된 YAML 파일의 위치에 대한 경로입니다.

   예시

   다음 예시에서는 YAML 파일을 사용하여 조직 수준 역할을 업데이트하는 방법을 보여줍니다.

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

   • 프로젝트 수준 역할을 업데이트하려면 다음 명령어를 실행합니다.

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

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

   • ROLE_ID는 업데이트할 역할의 이름입니다(예: myCompanyAdmin).

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

   • YAML_FILE_PATH는 업데이트된 커스텀 역할 정의가 포함된 YAML 파일의 위치에 대한 경로입니다.

   예시

   다음 예시에서는 YAML 파일을 사용하여 조직 수준 역할을 업데이트하는 방법을 보여줍니다.

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

   역할이 성공적으로 업데이트되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

   다음 예시에서는 YAML 파일을 사용하여 프로젝트 수준 역할을 업데이트하는 방법을 보여줍니다.

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

   역할이 성공적으로 업데이트되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

   플래그를 사용하여 커스텀 역할 업데이트:

   해당 플래그를 사용하여 역할 정의의 각 부분을 업데이트할 수 있습니다. 가능한 모든 플래그 목록은 gcloud iam roles update 주제를 참조하세요.

   다음 플래그를 사용하여 권한을 추가하거나 삭제할 수 있습니다.

   • --add-permissions=PERMISSIONS: 역할에 쉼표로 구분된 권한을 한 개 이상 추가합니다. 권한 이름에는 와일드 카드 문자(*)를 사용할 수 없습니다.

   • --remove-permissions=PERMISSIONS: 역할에서 쉼표로 구분된 권한을 한 개 이상 삭제합니다. 권한 이름에는 와일드 카드 문자(*)를 사용할 수 없습니다.

   또는 --permissions=PERMISSIONS 플래그를 사용하고 기존 권한 목록을 대체할 쉼표로 구분된 권한 목록을 제공하여 간단하게 새 권한을 지정할 수 있습니다.

   역할 정의의 다른 부분을 업데이트하려면 다음 명령어 중 하나를 실행합니다.

   • 조직 수준 역할을 업데이트하려면 다음 명령어를 실행합니다.

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

   • 프로젝트 수준 역할을 업데이트하려면 다음 명령어를 실행합니다.

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

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

   • ROLE_ID는 역할 이름입니다(예: myCompanyAdmin).

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

   • ROLE_TITLE은 역할의 별칭입니다(예: "My Company Admin").

   • ROLE_DESCRIPTION은 역할에 대한 간단한 설명입니다(예: "My custom role description.").

   • LAUNCH_STAGE는 출시 수명 주기에서 역할의 단계를 나타냅니다(예: ALPHA, BETA, GA).

   예시

   다음 예시에서는 플래그를 사용하여 조직 수준 역할에 권한을 추가하는 방법을 보여줍니다.

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

   역할이 성공적으로 업데이트되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

   다음 예시에서는 플래그를 사용하여 프로젝트 수준 역할에 권한을 추가하는 방법을 보여줍니다.

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

   역할이 성공적으로 업데이트되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

C++

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C++ API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name, std::string const& title) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::UpdateRoleRequest request;
  request.set_name(name);
  google::iam::admin::v1::Role role;
  role.set_title(title);
  google::protobuf::FieldMask update_mask;
  *update_mask.add_paths() = "title";
  *request.mutable_role() = role;
  *request.mutable_update_mask() = update_mask;
  auto response = client.UpdateRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully updated: " << response->DebugString()
            << "\n";
}

C#

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C# API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

public partial class CustomRoles
{
    public static Role EditRole(string name, string projectId, string newTitle,
        string newDescription, IList<string> newPermissions, string newStage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });
        // First, get a Role using List() or Get().
        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Get(resource).Execute();
        // Then you can update its fields.
        role.Title = newTitle;
        role.Description = newDescription;
        role.IncludedPermissions = newPermissions;
        role.Stage = newStage;
        role = service.Projects.Roles.Patch(role, resource).Execute();
        Console.WriteLine("Updated role: " + role.Name);
        return role;
    }
}

Go

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Go API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Java API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.Role.RoleLaunchStage;
import com.google.iam.admin.v1.UpdateRoleRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

/** Edit role metadata. Specifically, update description and launch stage. */
public class EditRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";
    String description = "a new description of the role";

    editRole(projectId, roleId, description);
  }

  public static void editRole(String projectId, String roleId, String description)
      throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    Role.Builder roleBuilder =
        Role.newBuilder()
            .setName(roleName)
            .setDescription(description)
            // See launch stage enums at
            // https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage
            .setStage(RoleLaunchStage.GA);
    FieldMask fieldMask = FieldMask.newBuilder().addPaths("description").addPaths("stage").build();
    UpdateRoleRequest updateRoleRequest =
        UpdateRoleRequest.newBuilder()
            .setName(roleName)
            .setRole(roleBuilder)
            .setUpdateMask(fieldMask)
            .build();

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

Python

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Python API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

from google.api_core.exceptions import NotFound
from google.cloud.iam_admin_v1 import IAMClient, Role, UpdateRoleRequest

from snippets.get_role import get_role


def edit_role(role: Role) -> Role:
    """
    Edits an existing IAM role in a GCP project.
    Args:
        role: google.cloud.iam_admin_v1.Role object to be updated

    Returns: Updated google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    request = UpdateRoleRequest(name=role.name, role=role)
    try:
        role = client.update_role(request)
        print(f"Edited role: {role.name}: {role}")
        return role
    except NotFound:
        print(f"Role [{role.name}] not found, take some actions")

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

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

• ROLE_TITLE: 사람이 읽을 수 있는 역할 이름입니다. 예를 들면 My Company Admin입니다.
• ROLE_DESCRIPTION: 역할에 대한 설명입니다. 예를 들면 "The company admin role allows company admins to access important resources"입니다.
• PERMISSION_1 및 PERMISSION_2: 역할에 포함하려는 권한입니다. 예를 들면 storage.objects.update입니다. 권한 이름에는 와일드 카드 문자(*)를 사용할 수 없습니다.
• LAUNCH_STAGE: 역할의 현재 실행 단계입니다. 이 필드에는 EAP, ALPHA, BETA, GA, DEPRECATED, DISABLED 값 중 하나가 포함될 수 있습니다.

HTTP 메서드 및 URL:

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

JSON 요청 본문:

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

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

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

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

API 탐색기(브라우저)

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 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="
}

커스텀 역할 사용 중지

커스텀 역할을 사용 중지하려면 출시 단계를 DISABLED로 변경합니다. 역할을 사용 중지하면 역할과 관련된 역할 바인딩이 비활성화됩니다. 즉, 사용자에게 역할을 부여해도 효과가 없습니다.

Console

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

   역할 페이지로 이동

2. 페이지 상단에서 '프로젝트 선택' 드롭다운 목록을 클릭합니다.

3. 조직 또는 프로젝트를 선택합니다.

4. 커스텀 역할을 선택하고 사용 중지를 클릭합니다.

gcloud

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

   Activate Cloud Shell

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

2. 커스텀 역할을 중지하려면 gcloud iam roles update 명령어를 사용하여 실행 단계를 DISABLED로 설정합니다.

   기존 커스텀 역할 수정 섹션의 gcloud 탭의 설명대로 다음 두 가지 방법으로 기존 커스텀 역할을 업데이트할 수 있습니다.

   • 업데이트된 역할 정의를 포함하는 YAML 파일 제공

   • 플래그를 사용하여 업데이트된 역할 정의 지정

   기존 커스텀 역할을 중지하는 가장 간편한 방법은 --stage 플래그를 사용하여 DISABLED로 설정하는 것입니다. 다음 명령어 중 하나를 실행합니다.

   • 조직 수준 역할을 중지하려면 다음 명령어를 실행합니다.

     gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
         --stage=DISABLED

   • 프로젝트 수준 역할을 중지하려면 다음 명령어를 실행합니다.

     gcloud iam roles update ROLE_ID --project=PROJECT_ID \
         --stage=DISABLED

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

   • ROLE_ID는 역할 이름입니다(예: myCompanyAdmin).

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

   예시

   다음 예시에서는 조직 수준 역할을 중지하는 방법을 보여줍니다.

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

   역할이 성공적으로 업데이트되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

   다음 예시에서는 프로젝트 수준 역할을 중지하는 방법을 보여줍니다.

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

   역할이 성공적으로 업데이트되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

C++

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

C#

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

Go

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

Java

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Java API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.UpdateRoleRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class DisableRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "testRole";

    Role role = disableRole(projectId, roleId);
    System.out.println("Role name: " + role.getName());
    System.out.println("Role stage: " + role.getStage());
  }

  public static Role disableRole(String projectId, String roleId)
          throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    Role role = Role.newBuilder()
                    .setName(roleName)
                    .setStage(Role.RoleLaunchStage.DISABLED)
                    .build();

    FieldMask fieldMask = FieldMask.newBuilder().addPaths("stage").build();
    UpdateRoleRequest updateRoleRequest =
              UpdateRoleRequest.newBuilder()
                      .setName(roleName)
                      .setRole(role)
                      .setUpdateMask(fieldMask)
                      .build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      return iamClient.updateRole(updateRoleRequest);
    }
  }
}

Python

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Python API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

from google.cloud.iam_admin_v1 import GetRoleRequest, IAMClient, Role, UpdateRoleRequest


def disable_role(project_id: str, role_id: str) -> Role:
    """
    Disables an IAM role in a GCP project.
    Args:
        project_id: GCP project ID
        role_id: ID of GCP IAM role

    Returns: Updated google.cloud.iam_admin_v1.Role object with disabled stage
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    get_request = GetRoleRequest(name=name)
    try:
        role = client.get_role(get_request)
        role.stage = Role.RoleLaunchStage.DISABLED
        update_request = UpdateRoleRequest(name=role.name, role=role)
        client.update_role(update_request)
        print(f"Disabled role: {role_id}: {role}")
        return role
    except NotFound:
        raise f"Role with id [{role_id}] not found, take some actions"

REST

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

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

• RESOURCE_TYPE: 관리하려는 커스텀 역할을 포함하는 리소스 유형입니다. projects 또는 organizations 값을 사용합니다.
• RESOURCE_ID: 관리하려는 커스텀 역할을 포함하는 프로젝트 ID 또는 조직 ID입니다. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다. 조직 ID는 123456789012 같은 숫자입니다.
• ROLE_NAME: organizations/, projects/ 또는 roles/ 프리픽스가 포함된 전체 역할 이름입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin입니다.
• ETAG: 역할의 버전 식별자입니다. 다른 역할 변경사항을 덮어쓰지 않도록 하려면 이 필드를 포함하세요.

HTTP 메서드 및 URL:

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

JSON 요청 본문:

{
  "roleId": "ROLE_NAME",
  "stage": DISABLED,
  "etag": "ETAG"
}

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

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

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

API 탐색기(브라우저)

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

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

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

역할 나열

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

Console

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

역할 페이지로 이동

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

gcloud

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

   Activate Cloud Shell

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

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

   • 조직 수준 커스텀 역할을 나열하려면 다음 명령어를 실행합니다.

     gcloud iam roles list --organization=ORGANIZATION_ID

   • 프로젝트 수준 커스텀 역할을 나열하려면 다음 명령어를 실행합니다.

     gcloud iam roles list --project=PROJECT_ID

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

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

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

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

   gcloud iam roles list

C++

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C++ API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

C#

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C# API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

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

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

Go

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Go API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Java API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

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

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

    listRoles(projectId);
  }

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

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

Python

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Python API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

from google.cloud.iam_admin_v1 import IAMClient, ListRolesRequest, RoleView
from google.cloud.iam_admin_v1.services.iam.pagers import ListRolesPager


def list_roles(
    project_id: str, show_deleted: bool = True, role_view: RoleView = RoleView.BASIC
) -> ListRolesPager:
    """
    Lists IAM roles in a GCP project.
    Args:
        project_id: GCP project ID
        show_deleted: Whether to include deleted roles in the results
        role_view: Level of detail for the returned roles (e.g., BASIC or FULL)

    Returns: A pager for traversing through the roles
    """
    client = IAMClient()
    parent = f"projects/{project_id}"
    request = ListRolesRequest(parent=parent, show_deleted=show_deleted, view=role_view)
    roles = client.list_roles(request)
    for page in roles.pages:
        for role in page.roles:
            print(role)
    print("Listed all iam roles")
    return roles

REST

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

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

• RESOURCE_TYPE: 관리하려는 커스텀 역할을 포함하는 리소스 유형입니다. projects 또는 organizations 값을 사용합니다.
• RESOURCE_ID: 관리하려는 커스텀 역할을 포함하는 프로젝트 ID 또는 조직 ID입니다. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다. 조직 ID는 123456789012 같은 숫자입니다.
• ROLE_VIEW: 선택사항. 반환된 역할에 포함할 정보입니다. 역할의 권한을 포함하려면 이 필드를 FULL로 설정합니다. 역할의 권한을 제외하려면 이 필드를 BASIC으로 설정합니다. 기본값은 BASIC입니다.
• PAGE_SIZE: 선택사항. 응답에 포함할 역할 수입니다. 기본값은 300이고 최댓값은 1,000입니다. 역할 수가 페이지 크기보다 크면 다음 결과 페이지를 검색하기 위해 사용할 수 있는 페이지로 나누기 토큰이 응답에 포함됩니다.
• NEXT_PAGE_TOKEN: 선택사항. 이 메서드의 이전 응답에서 반환된 페이지 나누기 토큰입니다. 지정된 경우 이전 응답이 종료된 위치에서 역할 목록이 시작됩니다.

참고: 사전 정의된 모든 IAM 역할을 나열하려면 RESOURCE_TYPE 및 RESOURCE_ID 필드를 생략합니다. 예를 들면 GET https://iam.googleapis.com/v1/roles입니다.

HTTP 메서드 및 URL:

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

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

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

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

API 탐색기(브라우저)

메서드 참조 페이지를 엽니다. 페이지 오른쪽에 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="
    }
  ]
}

맞춤 역할 삭제

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

중요: 삭제된 역할이 정지되고 이를 사용하여 허용 정책에서 새 역할 결합을 만들 수 없습니다. 삭제된 역할을 포함하는 기존 역할 결합은 영향을 받지 않습니다.

Console

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

   역할 페이지로 이동

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

gcloud

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

   Activate Cloud Shell

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

2. 커스텀 역할을 삭제하려면 gcloud iam roles delete 명령어를 사용합니다.

   • 조직 수준 커스텀 역할을 삭제하려면 다음 명령어를 실행합니다.

     gcloud iam roles delete ROLE_ID --organization=ORGANIZATION_ID

   • 프로젝트 수준 커스텀 역할을 삭제하려면 다음 명령어를 실행합니다.

     gcloud iam roles delete ROLE_ID --project=PROJECT_ID

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

   • ROLE_ID는 역할 이름입니다(예: myCompanyAdmin).

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

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

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

C++

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C++ API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::DeleteRoleRequest request;
  request.set_name(name);
  auto response = client.DeleteRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully deleted: " << response->DebugString()
            << "\n";
}

C#

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C# API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

public partial class CustomRoles
{
    public static void DeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        service.Projects.Roles.Delete(
            $"projects/{projectId}/roles/{name}").Execute();
        Console.WriteLine("Deleted role: " + name);
    }
}

Go

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Go API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Java API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

/** Delete role. */
public class DeleteRole {

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

    deleteRole(projectId, roleId);
  }

  public static void deleteRole(String projectId, String roleId) throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    DeleteRoleRequest deleteRoleRequest = DeleteRoleRequest.newBuilder().setName(roleName).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      iamClient.deleteRole(deleteRoleRequest);
      System.out.println("Role deleted.");
    }
  }
}

Python

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Python API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

from google.api_core.exceptions import FailedPrecondition, NotFound
from google.cloud.iam_admin_v1 import (
    DeleteRoleRequest,
    IAMClient,
    Role,
    UndeleteRoleRequest,
)

def delete_role(project_id: str, role_id: str) -> Role:
    """
    Deletes iam role in GCP project. Can be undeleted later
    Args:
        project_id: GCP project id
        role_id: id of GCP iam role

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = DeleteRoleRequest(name=name)
    try:
        role = client.delete_role(request)
        print(f"Deleted role: {role_id}: {role}")
        return role
    except NotFound:
        print(f"Role with id [{role_id}] not found, take some actions")
    except FailedPrecondition as err:
        print(f"Role with id [{role_id}] already deleted, take some actions)", err)

REST

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

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

• ROLE_NAME: organizations/, projects/ 또는 roles/ 프리픽스가 포함된 전체 역할 이름입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin입니다.

HTTP 메서드 및 URL:

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

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

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

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

API 탐색기(브라우저)

메서드 참조 페이지를 엽니다. 페이지 오른쪽에 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
}

역할이 삭제되면 해당 역할을 참조하는 모든 역할 결합이 허용 정책에 유지되지만 영향을 주지 않습니다. 삭제 후 7일 이내에 역할을 삭제 취소할 수 있습니다. 이 7일 동안 Google Cloud Console에는 해당 역할이 삭제된 것으로 표시됩니다. 또한 삭제된 역할을 프로그래매틱 방식으로 나열할 수도 있지만 기본적으로 생략됩니다.

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

참고: 프로젝트에서 생성된 커스텀 역할은 조직의 커스텀 역할 한도에 포함되지 않습니다.

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

최초 삭제 요청 후 최대 44일까지 역할이 영구 삭제된 후 같은 역할 ID로 새 역할을 만들 수 있습니다.

커스텀 역할 삭제 취소

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

역할은 7일 이내에만 삭제 취소할 수 있습니다. 7일이 지나면 언제든 역할이 영구적으로 삭제될 수 있고 이 역할을 참조하는 모든 역할 결합이 삭제됩니다.

Console

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

   역할 페이지로 이동

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

gcloud

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

   Activate Cloud Shell

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

2. 커스텀 역할을 삭제 취소하려면 gcloud iam roles undelete 명령어를 사용합니다.

   • 조직 수준 커스텀 역할을 삭제 취소하려면 다음 명령어를 실행합니다.

     gcloud iam roles undelete ROLE_ID --organization=ORGANIZATION_ID

   • 프로젝트 수준 커스텀 역할을 삭제 취소하려면 다음 명령어를 실행합니다.

     gcloud iam roles undelete ROLE_ID --project=PROJECT_ID

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

   • ROLE_ID는 역할 이름입니다(예: myCompanyAdmin).

   • ORGANIZATION_ID는 조직의 숫자 ID입니다(예: 123456789012).

   • PROJECT_ID는 프로젝트 이름입니다(예: my-project).

   예시

   다음 예시에서는 조직 수준 커스텀 역할을 삭제 취소하는 방법을 보여줍니다.

   gcloud iam roles undelete myCompanyAdmin --organization=123456789012

   역할이 성공적으로 삭제 취소되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

   다음 예시에서는 프로젝트 수준 커스텀 역할을 삭제 취소하는 방법을 보여줍니다.

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

   역할이 성공적으로 삭제 취소되면 다음과 비슷한 명령어 결과가 출력됩니다.

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

C++

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C++ API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::UndeleteRoleRequest request;
  request.set_name(name);
  auto response = client.UndeleteRole(request);
  if (!response) throw std::move(response).status();
  std::cout << "Role successfully undeleted: " << response->DebugString()
            << "\n";
}

C#

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM C# API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

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

public partial class CustomRoles
{
    public static Role UndeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Undelete(
            new UndeleteRoleRequest(), resource).Execute();
        Console.WriteLine("Undeleted role: " + role.Name);
        return role;
    }
}

Go

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Go API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Java API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.UndeleteRoleRequest;
import java.io.IOException;

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

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

    undeleteRole(projectId, roleId);
  }

  public static void undeleteRole(String projectId, String roleId) throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    UndeleteRoleRequest undeleteRoleRequest =
        UndeleteRoleRequest.newBuilder().setName(roleName).build();

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

Python

IAM용 클라이언트 라이브러리를 설치하고 사용하는 방법은 IAM 클라이언트 라이브러리를 참조하세요. 자세한 내용은 IAM Python API 참고 문서를 참조하세요.

IAM에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 시작하기 전에를 참조하세요.

from google.api_core.exceptions import FailedPrecondition, NotFound
from google.cloud.iam_admin_v1 import (
    DeleteRoleRequest,
    IAMClient,
    Role,
    UndeleteRoleRequest,
)

def undelete_role(project_id: str, role_id: str) -> Role:
    """
    Undeleted deleted iam role in GCP project
    Args:
        project_id: GCP project id
        role_id: id of GCP iam role

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = UndeleteRoleRequest(name=name)
    try:
        role = client.undelete_role(request)
        print(f"Undeleted role: {role_id}: {role}")
        return role
    except NotFound:
        print(f"Role with id [{role_id}] not found, take some actions")
    except FailedPrecondition as err:
        print(f"Role with id [{role_id}] is not deleted, take some actions)", err)

REST

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

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

• ROLE_NAME: organizations/, projects/ 또는 roles/ 프리픽스가 포함된 전체 역할 이름입니다. 예를 들면 organizations/123456789012/roles/myCompanyAdmin입니다.
• ETAG: 역할의 버전 식별자입니다. 다른 역할 변경사항을 덮어쓰지 않도록 하려면 이 필드를 포함하세요.

HTTP 메서드 및 URL:

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

JSON 요청 본문:

{
  "etag": "ETAG"
}

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

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

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

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

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

API 탐색기(브라우저)

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 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="
}

다음 단계

• 주 구성원에 역할을 부여하는 방법 알아보기
• 역할 권장사항을 사용하여 주 구성원의 권한을 축소하는 방법 알아보기
• 특정 조건이 충족되는 경우에만 역할을 부여하는 조건부 역할 부여 알아보기