Membuat dan mengelola peran khusus

Halaman ini menjelaskan cara membuat dan mengelola peran khusus Identity dan Access Management (IAM). Mengelola peran termasuk mengubah, menonaktifkan, mencantumkan, menghapus, dan membatalkan penghapusan peran.

Sebelum memulai

• Aktifkan IAM API.

  Mengaktifkan API

• Siapkan autentikasi.

  Pilih tab untuk melihat bagaimana Anda berencana menggunakan contoh di halaman ini:

  Konsol

  Saat menggunakan Konsol Google Cloud untuk mengakses API dan layanan Google Cloud, Anda tidak perlu menyiapkan autentikasi.

  gcloud

  Anda dapat menggunakan sampel gcloud CLI di halaman ini dari salah satu lingkungan pengembangan berikut:

  • Cloud Shell: Untuk menggunakan terminal online dengan gcloud CLI yang sudah disiapkan, aktifkan Cloud Shell.

    Di bagian bawah halaman ini, sesi Cloud Shell akan dimulai dan menampilkan perintah command line. Perlu waktu beberapa detik hingga sesi dimulai.

  • Shell lokal: Untuk menggunakan gcloud CLI di lingkungan pengembangan lokal, instal dan initialize gcloud CLI.

  C++

  Untuk menggunakan contoh C++ di halaman ini dari lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

  1. Menginstal Google Cloud CLI.

  2. Untuk initialize gcloud CLI, jalankan perintah berikut:

     gcloud init

  3. Buat kredensial autentikasi lokal untuk Akun Google Anda:

     gcloud auth application-default login

  Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal dalam dokumentasi autentikasi Google Cloud.

  C#

  Untuk menggunakan contoh .NET di halaman ini dari lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

  1. Menginstal Google Cloud CLI.

  2. Untuk initialize gcloud CLI, jalankan perintah berikut:

     gcloud init

  3. Buat kredensial autentikasi lokal untuk Akun Google Anda:

     gcloud auth application-default login

  Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal dalam dokumentasi autentikasi Google Cloud.

  Go

  Untuk menggunakan contoh Go di halaman ini dari lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

  1. Menginstal Google Cloud CLI.

  2. Untuk initialize gcloud CLI, jalankan perintah berikut:

     gcloud init

  3. Buat kredensial autentikasi lokal untuk Akun Google Anda:

     gcloud auth application-default login

  Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal dalam dokumentasi autentikasi Google Cloud.

  Java

  Untuk menggunakan contoh Java di halaman ini dari lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

  1. Menginstal Google Cloud CLI.

  2. Untuk initialize gcloud CLI, jalankan perintah berikut:

     gcloud init

  3. Buat kredensial autentikasi lokal untuk Akun Google Anda:

     gcloud auth application-default login

  Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal dalam dokumentasi autentikasi Google Cloud.

  Python

  Untuk menggunakan contoh Python di halaman ini dari lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

  1. Menginstal Google Cloud CLI.

  2. Untuk initialize gcloud CLI, jalankan perintah berikut:

     gcloud init

  3. Buat kredensial autentikasi lokal untuk Akun Google Anda:

     gcloud auth application-default login

  Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal dalam dokumentasi autentikasi Google Cloud.

  REST

  Untuk menggunakan contoh REST API di halaman ini dalam lingkungan pengembangan lokal, gunakan kredensial yang Anda berikan ke gcloud CLI.

  Instal Google Cloud CLI, lalu initialize dengan menjalankan perintah berikut:

  gcloud init

• Pahami hierarki resource Google Cloud.

• Baca Memahami peran khusus IAM.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk membuat dan mengelola peran khusus, minta administrator untuk memberi Anda peran IAM berikut:

• Untuk mengelola peran pada sebuah project: Administrator Peran (roles/iam.roleAdmin) pada project yang perannya ingin Anda kelola
• Untuk mengelola peran bagi organisasi: Administrator Peran Organisasi (roles/iam.organizationRoleAdmin) pada organisasi yang perannya ingin Anda kelola

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Melihat izin yang tersedia untuk project, folder, dan organisasi

Anda dapat membuat peran khusus untuk seluruh organisasi, atau untuk project tertentu di organisasi tersebut. Izin yang tersedia untuk peran khusus bergantung pada tempat Anda membuat peran tersebut. Misalnya, jika izin hanya dapat digunakan di level organisasi, Anda tidak dapat menyertakan izin tersebut dalam peran khusus level project.

Untuk memeriksa izin yang tersedia untuk peran khusus level organisasi dan level project, Anda dapat menggunakan gcloud CLI atau Identity dan Access Management API untuk mencantumkan izin yang tersedia di organisasi tertentu atau proyek Anda. Misalnya, Anda bisa mendapatkan semua izin yang tersedia untuk peran khusus yang dibuat dalam project Anda.

Beberapa izin mungkin tidak terlihat oleh Anda atau tidak dapat digunakan dalam peran khusus, meskipun didukung dalam peran khusus. Misalnya, izin mungkin tidak tersedia untuk digunakan dalam peran khusus jika Anda belum mengaktifkan API untuk layanan tersebut.

Untuk mempelajari lebih lanjut izin yang dapat Anda tambahkan ke peran khusus, lihat Izin yang didukung.

gcloud

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

2. Gunakan perintah gcloud iam list-testable-permissions untuk mendapatkan daftar izin yang tersedia untuk peran khusus dalam project atau organisasi tertentu. Respons mencantumkan izin yang dapat Anda gunakan dalam peran khusus untuk project atau organisasi tersebut.

   Untuk mencantumkan izin yang tersedia dalam peran khusus untuk suatu project atau organisasi, jalankan perintah ini:

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

   Ganti FULL_RESOURCE_NAME dengan salah satu nilai berikut:

   • Project: //cloudresourcemanager.googleapis.com/projects/PROJECT_ID (misalnya, //cloudresourcemanager.googleapis.com/projects/my-project)

   • Organisasi: //cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID (misalnya, //cloudresourcemanager.googleapis.com/organizations/123456789012)

   Hasilnya menunjukkan apakah setiap izin didukung dalam peran khusus. Izin yang tidak memiliki kolom customRolesSupportLevel didukung sepenuhnya.

   Perintah list-testable-permissions mungkin menampilkan ratusan hasil. Contoh sebagian ini menunjukkan format setiap hasil:

   ---
   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++

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C++ IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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#

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C# IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Go IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Java IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Python IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

def query_testable_permissions(resource: str) -> None:
    """Lists valid permissions for a resource."""

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

REST

Metode permissions.queryTestablePermissions mencantumkan izin yang tersedia di organisasi atau project.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• FULL_RESOURCE_NAME: URI yang terdiri dari nama layanan dan jalur ke resource. Misalnya, lihat Nama resource lengkap.
• PAGE_SIZE: Opsional. Jumlah izin yang disertakan dalam respons. Nilai defaultnya adalah 100, dan nilai maksimumnya adalah 1,000. Jika jumlah izin lebih besar dari ukuran halaman, respons akan berisi token penomoran halaman yang dapat Anda gunakan untuk mengambil hasil halaman berikutnya.
• NEXT_PAGE_TOKEN: Opsional. Token penomoran halaman yang ditampilkan dalam respons sebelumnya dari metode ini. Jika ditentukan, daftar izin yang dapat diuji akan dimulai dari tempat respons sebelumnya berakhir.

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$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

APIs Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom lainnya yang wajib diisi, lalu klik Jalankan.

Responsnya berisi daftar izin.

Catatan: Izin yang tidak memiliki kolom customRolesSupportLevel didukung sepenuhnya dalam peran khusus.

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

Mendapatkan metadata peran

Sebelum membuat peran khusus, Anda mungkin ingin mendapatkan metadata untuk kedua peran bawaan dan khusus. Metadata peran mencakup ID dan izin peran yang terdapat dalam peran tersebut. Anda dapat melihat metadata ini menggunakan Google Cloud Console atau IAM API.

Untuk melihat metadata peran, gunakan salah satu metode berikut:

Konsol

1. Di Konsol Google Cloud, buka halaman Roles.

   Buka halaman Roles

2. Pilih organisasi atau project Anda dari menu drop-down di bagian atas halaman.

3. Pilih kotak centang untuk satu atau beberapa peran untuk melihat izin peran. Panel samping kanan menampilkan izin yang terdapat dalam peran, jika ada.

Ikon di kolom Type menunjukkan apakah itu merupakan peran khusus (ikon "pabrik") atau peran yang telah ditetapkan (ikon heksagon).

Jika Anda ingin menemukan semua peran yang menyertakan izin tertentu, ketik nama izin di kotak Filter di bagian atas daftar Peran.

gcloud

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

2. Gunakan perintah gcloud iam roles describe untuk melihat metadata untuk peran yang telah ditetapkan dan peran khusus.

   Untuk melihat metadata untuk peran yang telah ditentukan, jalankan perintah berikut:

   gcloud iam roles describe ROLE_ID

   ROLE_ID adalah ID peran. Peran yang telah ditetapkan menyertakan awalan role dalam ID-nya, misalnya, roles/iam.roleViewer.

   Contoh berikut menunjukkan output perintah describe saat dieksekusi pada peran roles/iam.roleViewer yang telah ditetapkan:

   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

   Untuk melihat metadata peran khusus, jalankan salah satu perintah berikut:

   • Untuk melihat metadata untuk peran khusus yang dibuat di tingkat organisasi, jalankan perintah berikut:

     gcloud iam roles describe --organization=ORGANIZATION_ID ROLE_ID

   • Untuk menampilkan metadata bagi peran khusus yang dibuat di level project, jalankan perintah berikut:

     gcloud iam roles describe --project=PROJECT_ID ROLE_ID

   Setiap nilai placeholder dijelaskan di bawah:

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   • ROLE_ID adalah ID peran, tidak termasuk awalan seperti projects/, organizations/, atau roles/. Contoh, myCompanyAdmin.

   Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi untuk gcloud iam roles describe.

C++

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C++ IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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#

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C# IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Go IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Java IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Python IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

def get_role(name: str) -> None:
    """Gets a role."""

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

REST

Metode roles.get mendapatkan definisi peran.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• ROLE_NAME: Nama peran lengkap, termasuk setiap awalan organizations/, projects/, atau roles/. Contoh, organizations/123456789012/roles/myCompanyAdmin.

Metode HTTP dan URL:

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

Untuk mengirim permintaan, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

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

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

$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

APIs Explorer (browser)

Buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Lengkapi kolom yang wajib diisi, lalu klik Jalankan.

Responsnya berisi definisi peran.

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

Membuat peran khusus

Anda dapat membuat peran khusus di level project atau organisasi.

Catatan: Anda tidak dapat menentukan peran khusus di tingkat folder. Jika Anda perlu menggunakan peran khusus dalam folder, tentukan peran khusus di tingkat organisasi.

Peran kustom level organisasi dapat mencakup izin IAM yang didukung dalam peran kustom. Peran khusus level project dapat berisi semua izin yang didukung, kecuali untuk izin yang hanya dapat digunakan di tingkat organisasi atau folder, seperti resourcemanager.organizations.get. Jika mencoba menambahkan izin ini ke peran khusus level project, Anda akan melihat pesan error:

Konsol

Pesan peringatan berikut ditampilkan: "Tidak berlaku untuk peran kustom level project". Izin tersebut akan otomatis dibatalkan pilihannya dari daftar izin yang disertakan, dan Anda dapat melanjutkan pembuatan peran.

gcloud

Pesan error berikut ditampilkan: INVALID_ARGUMENT: Permission PERMISSION is not valid. Peran khusus tidak akan dibuat hingga Anda menghapus izin dari definisi peran terlebih dahulu dan mencoba operasi ini lagi.

REST API

Pesan error berikut ditampilkan: Permission PERMISSION is not valid, bersama dengan kode error HTTP 400 dan status INVALID_ARGUMENT. Peran khusus tidak akan dibuat hingga Anda menghapus izin dari definisi peran terlebih dahulu dan mencoba operasi ini lagi.

Setiap peran khusus dapat berisi hingga 3,000 izin. Selain itu, ukuran total maksimum untuk judul, deskripsi, dan nama izin untuk peran khusus adalah 64 KB. Jika Anda perlu membuat peran khusus yang lebih besar, Anda dapat membagi izin menjadi beberapa peran khusus. Pilih judul peran yang menunjukkan hubungan antara peran khusus, seperti Custom Admin (1 of 2) dan Custom Admin (2 of 2).

Setiap peran khusus dapat memiliki tahap peluncuran. Sebagian besar tahap peluncuran bersifat informatif, dan membantu Anda melacak apakah setiap peran siap untuk digunakan secara luas. Selain itu, tahap peluncuran DISABLED memungkinkan Anda menonaktifkan peran kustom. Untuk informasi lebih lanjut tentang tahap peluncuran, lihat Menguji dan men-deploy.

Konsol

Beberapa peran yang telah ditetapkan berisi izin yang tidak digunakan lagi atau izin yang tidak diizinkan dalam peran khusus. Jika Anda mencoba membuat peran khusus berdasarkan salah satu peran yang telah ditetapkan ini, izin yang dibatasi dan tidak digunakan lagi akan dihapus.

Untuk membuat peran khusus baru dari awal:

1. Di Konsol Google Cloud, buka halaman Roles.

   Buka halaman Roles

2. Menggunakan menu drop-down di bagian atas halaman, pilih organisasi atau project tempat Anda ingin membuat peran.

3. Klik Create Role.

4. Masukkan Nama, Judul, Deskripsi, dan Role launch stage untuk peran tersebut. Nama peran tidak dapat diubah setelah peran dibuat.

5. Klik Add Permissions.

6. Pilih izin yang ingin disertakan dalam peran, lalu klik Tambahkan Izin. Gunakan menu drop-down Semua Layanan dan Semua Jenis untuk memfilter dan memilih izin menurut layanan dan jenis.

Membuat peran khusus berdasarkan peran bawaan yang ada:

1. Di Konsol Google Cloud, buka halaman Roles.

   Buka halaman Roles

2. Pilih organisasi atau project tempat Anda ingin membuat peran.
3. Pilih peran yang ingin dijadikan dasar untuk peran khusus baru.
4. Klik Buat Peran dari Pilihan.
5. Masukkan Nama, Judul, Deskripsi, dan Role launch stage untuk peran tersebut. Nama peran tidak dapat diubah setelah peran dibuat.
6. Hapus centang izin yang ingin dikecualikan dari peran.
7. Klik Tambahkan Izin untuk menyertakan izin apa pun.
8. Klik Create.

gcloud

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

2. Gunakan perintah gcloud iam roles create untuk membuat peran kustom baru. Anda dapat menggunakan perintah ini dengan dua cara:

   • Dengan memberikan file YAML yang berisi definisi peran

   • Dengan menggunakan tanda untuk menentukan definisi peran

   Saat membuat peran kustom, Anda harus menentukan apakah peran tersebut berlaku untuk level organisasi atau level project menggunakan flag --organization=ORGANIZATION_ID atau --project=PROJECT_ID. Setiap contoh di bawah ini membuat sebuah peran khusus di level project.

   Peran khusus hanya dapat berisi izin yang didukung dalam peran khusus. Jika peran khusus berisi izin lain, perintah akan gagal.

   Untuk membuat peran khusus menggunakan file YAML:

   Buat file YAML yang berisi definisi peran khusus Anda. File tersebut harus disusun dengan cara berikut:

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

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_TITLE adalah jabatan yang cocok untuk peran tersebut, seperti "My Company Admin".

   • ROLE_DESCRIPTION adalah deskripsi singkat dari peran, seperti "My custom role description".

   • LAUNCH_STAGE menunjukkan tahap peran dalam siklus proses peluncuran, seperti ALPHA, BETA, atau GA.

   • PERMISSION_1 dan PERMISSION_2 adalah izin untuk disertakan dalam peran khusus, seperti iam.roles.get. Anda tidak dapat menggunakan karakter pengganti (*) pada nama izin.

   Simpan file YAML, lalu jalankan salah satu perintah berikut:

   • Untuk membuat peran khusus di tingkat organisasi, jalankan perintah berikut:

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

   • Untuk membuat peran khusus di level project, jalankan perintah berikut:

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

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_ID adalah nama peran, misalnya myCompanyAdmin.

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   • YAML_FILE_PATH adalah jalur ke lokasi file YAML Anda yang berisi definisi peran kustom.

   Contoh

   Contoh file YAML berikut menunjukkan cara membuat definisi peran:

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

   Contoh berikut menunjukkan cara membuat peran di tingkat organisasi menggunakan file YAML:

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

   Jika peran berhasil dibuat, output perintahnya akan terlihat seperti berikut:

   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

   Contoh berikut menunjukkan cara membuat peran di level project menggunakan file YAML:

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

   Jika peran berhasil dibuat, output perintahnya akan terlihat seperti berikut:

   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

   Untuk membuat peran kustom menggunakan tanda:

   Jalankan salah satu perintah berikut:

   • Untuk membuat peran khusus di tingkat organisasi, jalankan perintah berikut:

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

   • Untuk membuat peran khusus di level project, jalankan perintah berikut:

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

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_ID adalah nama peran, misalnya myCompanyAdmin.

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   • ROLE_TITLE adalah jabatan yang cocok untuk peran tersebut, seperti "My Company Admin".

   • ROLE_DESCRIPTION adalah deskripsi singkat dari peran, seperti "My custom role description.".

   • PERMISSIONS_LIST berisi daftar izin yang dipisahkan koma yang ingin Anda sertakan dalam peran khusus. Contoh: iam.roles.get,iam.roles.list Anda tidak dapat menggunakan karakter pengganti (*) pada nama izin.

   • LAUNCH_STAGE menunjukkan tahap peran dalam siklus proses peluncuran, seperti ALPHA, BETA, atau GA.

   Contoh

   Contoh berikut menunjukkan cara membuat peran di tingkat organisasi menggunakan tanda:

   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

   Jika peran berhasil dibuat, output perintahnya akan terlihat seperti berikut:

   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

   Contoh berikut menunjukkan cara membuat peran di level project menggunakan flag:

   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

   Jika peran berhasil dibuat, output perintahnya akan terlihat seperti berikut:

   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++

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C++ IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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#

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C# IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Go IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Java IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Python IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

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

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

REST

Metode roles.create membuat peran kustom dalam project atau organisasi.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• RESOURCE_TYPE: Jenis resource yang peran khususnya ingin Anda kelola. Gunakan nilai projects atau organizations.
• RESOURCE_ID: Project ID atau ID organisasi yang peran khususnya ingin Anda kelola. ID project berupa string alfanumerik, seperti my-project. ID organisasi berupa angka, seperti 123456789012.
• ROLE_ID: Nama peran, misalnya myCompanyAdmin.
• ROLE_TITLE: Judul yang dapat dibaca manusia untuk peran. Contoh, My Company Admin.
• ROLE_DESCRIPTION: Deskripsi untuk peran. Contoh, "The company admin role allows company admins to access important resources".

• PERMISSION_1 dan PERMISSION_2: Izin yang ingin Anda sertakan dalam peran. Contohnya, storage.objects.update. Anda tidak dapat menggunakan karakter pengganti (*) pada nama izin.

  Peran khusus hanya dapat berisi izin yang didukung dalam peran khusus. Jika peran khusus berisi izin lain, permintaan akan gagal.

• LAUNCH_STAGE: Tahap peluncuran peran saat ini. Kolom ini dapat berisi salah satu nilai berikut: EAP, ALPHA, BETA, GA, DEPRECATED, atau DISABLED.

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$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

APIs Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom lainnya yang wajib diisi, lalu klik Jalankan.

Respons berisi peran yang Anda buat.

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

Mengedit peran khusus yang sudah ada

Pola umum untuk mengupdate metadata resource, seperti peran khusus, adalah pola read-modify-write. Dengan pola ini, Anda membaca status peran saat ini, memperbarui data secara lokal, lalu mengirim data yang telah diubah untuk ditulis.

Pola baca-modifikasi-tulis dapat menyebabkan konflik jika dua atau beberapa proses independen mencoba urutan secara bersamaan. Misalnya, jika dua pemilik untuk sebuah project mencoba membuat perubahan yang bertentangan pada peran secara bersamaan, beberapa perubahan dapat gagal. IAM mengatasi masalah ini menggunakan properti etag dalam peran khusus. Properti ini digunakan untuk memverifikasi apakah peran khusus telah berubah sejak permintaan terakhir. Saat Anda membuat permintaan ke IAM dengan nilai etag, IAM akan membandingkan nilai etag dalam permintaan tersebut dengan nilai etag yang ada yang terkait dengan peran khusus. Etag hanya menulis perubahan jika nilai etag cocok.

Saat Anda memperbarui peran, pertama-tama dapatkan peran menggunakan roles.get(), perbarui peran, lalu tulis peran yang diperbarui menggunakan roles.patch(). Gunakan nilai etag saat menetapkan peran hanya jika peran yang sesuai di roles.get() berisi nilai etag.

Catatan: Saat mengubah peran kustom dengan menambahkan atau menghapus salah satu izin berikut: resourcemanager.organizations.get, resourcemanager.folders.get, danresourcemanager.projects.get, perubahan ke peran khusus dapat memerlukan waktu hingga 24 jam untuk diterapkanorganizations.search danfolders.search Cloud Resource Manager API. projects.list API juga tunduk pada penundaan ini untuk panggilan API yang tidak menyediakan filter yang menentukan jenis dan ID induk. Penundaan ini terjadi karena izin ini melibatkan fungsi penelusuran, dan dapat memerlukan waktu hingga 24 jam di antara pembuatan ulang indeks penelusuran.

Konsol

1. Di Konsol Google Cloud, buka halaman Roles.

   Buka halaman Roles

2. Dengan menggunakan menu drop-down di bagian atas halaman, pilih project atau organisasi yang berisi peran yang ingin diedit.

3. Klik peran khusus.

4. Klik Edit Peran.

5. Untuk memperbarui metadata peran, edit Judul, Deskripsi, atau Tahap peluncuran peran dari peran tersebut.

6. Untuk memperbarui izin peran, lakukan hal berikut:

   1. Klik Tambahkan Izin untuk menambahkan izin baru ke peran.
   2. Hapus centang izin untuk menghapus izin dari peran.

7. Klik Perbarui untuk menyimpan peran yang diedit.

gcloud

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

2. Gunakan perintah gcloud iam roles update untuk memperbarui peran kustom. Anda dapat menggunakan perintah ini dengan dua cara:

   • Dengan memberikan file YAML yang berisi definisi peran yang diperbarui

   • Dengan menggunakan tanda untuk menentukan definisi peran yang diperbarui

   Saat memperbarui peran kustom, Anda harus menentukan apakah peran tersebut berlaku untuk level organisasi atau level project menggunakan flag --organization=ORGANIZATION_ID atau --project=PROJECT_ID. Setiap contoh di bawah ini membuat sebuah peran khusus di level project.

   Untuk memperbarui peran khusus menggunakan file YAML:

   Dapatkan definisi peran saat ini dengan menjalankan salah satu perintah berikut:

   • Untuk mendapatkan definisi peran dari peran khusus tingkat organisasi, jalankan perintah berikut:

     gcloud iam roles describe ROLE_ID --organization=ORGANIZATION_ID

   • Untuk mendapatkan definisi peran dari peran kustom level project, jalankan perintah berikut:

     gcloud iam roles describe ROLE_ID --project=PROJECT_ID

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_ID adalah nama peran yang akan diperbarui, seperti myCompanyAdmin.

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   Perintah describe menampilkan definisi peran dan menyertakan nilai etag yang secara unik mengidentifikasi versi peran saat ini. Nilai etag harus diberikan dalam definisi peran yang diperbarui untuk memastikan bahwa setiap perubahan peran serentak tidak ditimpa.

   Perintah describe menampilkan output berikut:

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

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_DESCRIPTION adalah deskripsi singkat dari peran, seperti "My custom role description".

   • ETAG adalah ID unik untuk versi peran saat ini, seperti BwVkBkbfr70=.

   • PERMISSION_1 dan PERMISSION_2 adalah izin untuk disertakan dalam peran khusus, seperti iam.roles.get. Anda tidak dapat menggunakan karakter pengganti (*) pada nama izin.

   • ROLE_NAME adalah nama peran lengkap, termasuk setiap awalan organizations/, projects/, atau roles/. Contoh, organizations/123456789012/roles/myCompanyAdmin.

   • LAUNCH_STAGE menunjukkan tahap peran dalam siklus proses peluncuran, seperti ALPHA, BETA, atau GA.

   • ROLE_TITLE adalah jabatan yang cocok untuk peran tersebut, seperti "My Company Admin".

   Untuk memperbarui peran, sertakan definisi peran yang dihasilkan ke file YAML atau perbarui file YAML asli dengan nilai etag yang dihasilkan.

   Perhatikan contoh file YAML berikut, yang berisi output dari perintah describe untuk peran level project dan menambahkan dua izin 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

   Simpan file YAML, lalu jalankan salah satu perintah berikut:

   • Untuk memperbarui peran tingkat organisasi, jalankan perintah berikut:

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

   • Untuk memperbarui peran level project, jalankan perintah berikut:

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

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_ID adalah nama peran yang akan diperbarui, seperti myCompanyAdmin.

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project-id.

   • YAML_FILE_PATH adalah jalur ke lokasi file YAML Anda yang berisi definisi peran kustom yang diperbarui.

   Contoh

   Contoh berikut menunjukkan cara memperbarui peran tingkat organisasi menggunakan file YAML:

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

   • Untuk memperbarui peran level project, jalankan perintah berikut:

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

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_ID adalah nama peran yang akan diperbarui, seperti myCompanyAdmin.

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   • YAML_FILE_PATH adalah jalur ke lokasi file YAML Anda yang berisi definisi peran kustom yang diperbarui.

   Contoh

   Contoh berikut menunjukkan cara memperbarui peran tingkat organisasi menggunakan file YAML:

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

   Jika peran berhasil diperbarui, output perintahnya akan terlihat seperti berikut:

   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

   Contoh berikut menunjukkan cara memperbarui peran level project menggunakan file YAML:

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

   Jika peran berhasil diperbarui, output perintahnya akan terlihat seperti berikut:

   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

   Untuk memperbarui peran kustom menggunakan tanda:

   Setiap bagian dari definisi peran dapat diperbarui menggunakan tanda yang sesuai. Lihat topik gcloud iam roles update untuk daftar semua kemungkinan flag.

   Anda dapat menggunakan tanda berikut untuk menambahkan atau menghapus izin:

   • --add-permissions=PERMISSIONS: Menambahkan satu atau beberapa izin yang dipisahkan koma untuk peran tersebut. Anda tidak dapat menggunakan karakter pengganti (*) pada nama izin.

   • --remove-permissions=PERMISSIONS: Menghapus satu atau beberapa izin yang dipisahkan koma dari peran. Anda tidak dapat menggunakan karakter pengganti (*) pada nama izin.

   Atau, Anda cukup menentukan izin baru menggunakan flag --permissions=PERMISSIONS dan memberikan daftar izin yang dipisahkan koma untuk menggantikan daftar izin yang ada.

   Untuk memperbarui bagian lain dari definisi peran, jalankan salah satu perintah berikut:

   • Untuk memperbarui peran tingkat organisasi, jalankan perintah berikut:

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

   • Untuk memperbarui peran level project, jalankan perintah berikut:

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

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_ID adalah nama peran, misalnya myCompanyAdmin.

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   • ROLE_TITLE adalah jabatan yang cocok untuk peran tersebut, seperti "My Company Admin".

   • ROLE_DESCRIPTION adalah deskripsi singkat dari peran, seperti "My custom role description.".

   • LAUNCH_STAGE menunjukkan tahap peran dalam siklus proses peluncuran, seperti ALPHA, BETA, atau GA.

   Contoh

   Contoh berikut menunjukkan cara menambahkan izin ke peran tingkat organisasi menggunakan flag:

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

   Jika peran berhasil diperbarui, output perintahnya akan terlihat seperti berikut:

   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

   Contoh berikut menunjukkan cara menambahkan izin ke peran level project menggunakan flag:

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

   Jika peran berhasil diperbarui, output perintahnya akan terlihat seperti berikut:

   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++

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C++ IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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#

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C# IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Go IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Java IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Python IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

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

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

REST

Metode roles.patch memperbarui peran khusus dalam project atau organisasi.

Sebelum menggunakan salah satu dari data permintaan, lakukan penggantian berikut:

Wajib diisi:

• RESOURCE_TYPE: Jenis resource yang peran khususnya ingin Anda kelola. Gunakan nilai projects atau organizations.
• RESOURCE_ID: Project ID atau ID organisasi yang peran khususnya ingin Anda kelola. ID project berupa string alfanumerik, seperti my-project. ID organisasi berupa angka, seperti 123456789012.
• ROLE_NAME: Nama peran lengkap, termasuk setiap awalan organizations/, projects/, atau roles/. Contoh, organizations/123456789012/roles/myCompanyAdmin.

Rekomendasi:

• ETAG: ID untuk versi peran. Sertakan kolom ini untuk mencegah menimpa perubahan peran lainnya.

Opsional (tentukan satu atau beberapa nilai berikut):

• ROLE_TITLE: Judul yang dapat dibaca manusia untuk peran. Contoh, My Company Admin.
• ROLE_DESCRIPTION: Deskripsi untuk peran. Contoh, "The company admin role allows company admins to access important resources".
• PERMISSION_1 dan PERMISSION_2: Izin yang ingin Anda sertakan dalam peran. Contohnya, storage.objects.update. Anda tidak dapat menggunakan karakter pengganti (*) pada nama izin.
• LAUNCH_STAGE: Tahap peluncuran peran saat ini. Kolom ini dapat berisi salah satu nilai berikut: EAP, ALPHA, BETA, GA, DEPRECATED, atau DISABLED.

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$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

APIs Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom lainnya yang wajib diisi, lalu klik Jalankan.

Responsnya berisi definisi peran singkat yang mencakup nama peran, kolom yang Anda perbarui, dan etag yang mengidentifikasi versi peran saat ini.

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

Menonaktifkan peran khusus

Anda dapat menonaktifkan peran khusus dengan mengubah tahap peluncurannya menjadi DISABLED. Jika peran dinonaktifkan, binding peran apa pun yang terkait dengan peran akan dinonaktifkan, yang berarti pemberian peran tersebut kepada pengguna tidak berpengaruh apa pun.

Konsol

1. Di Konsol Google Cloud, buka halaman Roles.

   Buka halaman Roles

2. Klik menu drop-down "Pilih project" di bagian atas halaman.

3. Pilih organisasi atau project Anda.

4. Pilih peran khusus, lalu klik Nonaktifkan.

gcloud

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

2. Gunakan perintah gcloud iam roles update untuk menonaktifkan peran kustom dengan menetapkan tahap peluncurannya ke DISABLED.

   Seperti yang dijelaskan di tab gcloud di bagian Mengedit peran kustom yang ada, Anda dapat memperbarui peran kustom yang ada dengan dua cara berikut:

   • Dengan memberikan file YAML yang berisi definisi peran yang diperbarui

   • Dengan menggunakan tanda untuk menentukan definisi peran yang diperbarui

   Cara termudah untuk menonaktifkan peran khusus yang sudah ada adalah dengan menggunakan flag --stage dan menetapkannya ke DISABLED. Jalankan salah satu perintah berikut:

   • Untuk menonaktifkan peran tingkat organisasi, jalankan perintah berikut:

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

   • Untuk menonaktifkan peran level project, jalankan perintah berikut:

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

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_ID adalah nama peran, misalnya myCompanyAdmin.

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   Contoh

   Contoh berikut menunjukkan cara menonaktifkan peran tingkat organisasi:

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

   Jika peran berhasil diperbarui, output perintahnya akan terlihat seperti berikut:

   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

   Contoh berikut menunjukkan cara menonaktifkan peran level project:

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

   Jika peran berhasil diperbarui, output perintahnya akan terlihat seperti berikut:

   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++

Perbarui kolom stage peran menjadi DISABLED.

C#

Perbarui kolom stage peran menjadi DISABLED.

Go

Perbarui kolom stage peran menjadi DISABLED.

Java

Perbarui kolom stage peran menjadi DISABLED.

Python

Perbarui kolom stage peran menjadi DISABLED.

REST

Metode roles.patch memungkinkan Anda mengubah tahap peluncuran peran khusus menjadi DISABLED, yang akan menonaktifkan peran tersebut.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• RESOURCE_TYPE: Jenis resource yang peran khususnya ingin Anda kelola. Gunakan nilai projects atau organizations.
• RESOURCE_ID: Project ID atau ID organisasi yang peran khususnya ingin Anda kelola. ID project berupa string alfanumerik, seperti my-project. ID organisasi berupa angka, seperti 123456789012.
• ROLE_NAME: Nama peran lengkap, termasuk setiap awalan organizations/, projects/, atau roles/. Contoh, organizations/123456789012/roles/myCompanyAdmin.
• ETAG: ID untuk versi peran. Sertakan kolom ini untuk mencegah menimpa perubahan peran lainnya.

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$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

APIs Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom lainnya yang wajib diisi, lalu klik Jalankan.

Anda akan melihat respons JSON seperti berikut:

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

Daftar peran

Anda dapat mencantumkan semua peran khusus yang dibuat dalam project atau organisasi.

Konsol

Di Konsol Google Cloud, buka halaman Roles.

Buka halaman Roles

Semua peran khusus untuk organisasi atau project yang telah Anda pilih akan tercantum di halaman ini.

gcloud

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

2. Gunakan perintah gcloud iam roles list untuk mencantumkan peran kustom dan peran bawaan untuk project atau organisasi:

   • Untuk mencantumkan peran khusus tingkat organisasi, jalankan perintah berikut:

     gcloud iam roles list --organization=ORGANIZATION_ID

   • Untuk mencantumkan peran kustom level project, jalankan perintah berikut:

     gcloud iam roles list --project=PROJECT_ID

   Setiap nilai placeholder dijelaskan di bawah:

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   Untuk mencantumkan peran yang dihapus, Anda juga dapat menentukan tanda --show-deleted.

   Jalankan perintah berikut untuk membuat daftar peran yang telah ditetapkan:

   gcloud iam roles list

C++

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C++ IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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#

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C# IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Go IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Java IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Python IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

def list_roles(project_id: str) -> None:
    """Lists roles."""

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

REST

Metode roles.list mencantumkan semua peran khusus dalam sebuah project atau organisasi.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• RESOURCE_TYPE: Jenis resource yang peran khususnya ingin Anda kelola. Gunakan nilai projects atau organizations.
• RESOURCE_ID: Project ID atau ID organisasi yang peran khususnya ingin Anda kelola. ID project berupa string alfanumerik, seperti my-project. ID organisasi berupa angka, seperti 123456789012.
• ROLE_VIEW: Opsional. Informasi yang disertakan untuk peran yang ditampilkan. Untuk menyertakan izin peran, tetapkan kolom ini ke FULL. Untuk mengecualikan izin peran, tetapkan kolom ini ke BASIC. Nilai defaultnya adalah BASIC.
• PAGE_SIZE: Opsional. Jumlah peran yang akan disertakan dalam respons. Nilai defaultnya adalah 300 dan nilai maksimumnya adalah 1,000. Jika jumlah peran lebih besar dari ukuran halaman, respons akan berisi token penomoran halaman yang dapat Anda gunakan untuk mengambil halaman hasil berikutnya.
• NEXT_PAGE_TOKEN: Opsional. Token penomoran halaman yang ditampilkan dalam respons sebelumnya dari metode ini. Jika ditentukan, daftar peran akan dimulai dari tempat permintaan sebelumnya berakhir.

Catatan: Untuk mencantumkan semua peran IAM yang telah ditetapkan, hapus kolom RESOURCE_TYPE dan RESOURCE_ID. Contoh: GET https://iam.googleapis.com/v1/roles.

Metode HTTP dan URL:

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

Untuk mengirim permintaan, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

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)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

$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

APIs Explorer (browser)

Buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Lengkapi kolom yang wajib diisi, lalu klik Jalankan.

Anda akan melihat respons JSON seperti berikut:

{
  "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="
    }
  ]
}

Menghapus peran khusus

Anda dapat menghapus peran khusus apa pun dalam project atau organisasi.

Penting: Peran yang dihapus akan ditangguhkan dan tidak dapat digunakan untuk membuat binding peran baru di kebijakan izinkan. Binding peran yang sudah ada, yang menyertakan peran yang dihapus tidak akan berpengaruh.

Konsol

1. Di Konsol Google Cloud, buka halaman Roles.

   Buka halaman Roles

2. Pilih peran yang ingin dihapus, lalu klik Hapus di bagian atas halaman.

gcloud

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

2. Gunakan perintah gcloud iam roles delete untuk menghapus peran kustom:

   • Untuk menghapus peran khusus tingkat organisasi, jalankan perintah berikut:

     gcloud iam roles delete ROLE_ID --organization=ORGANIZATION_ID

   • Untuk menghapus peran kustom level project, jalankan perintah berikut:

     gcloud iam roles delete ROLE_ID --project=PROJECT_ID

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_ID adalah nama peran, misalnya myCompanyAdmin.

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   Peran tersebut tidak akan disertakan dalam gcloud iam roles list, kecuali jika flag --show-deleted disertakan. Peran yang dihapus ditunjukkan oleh blok deleted: true dalam respons list, seperti:

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

C++

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C++ IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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#

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C# IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Go IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Java IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Python IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

def delete_role(name: str, project: str) -> dict:
    """Deletes a role."""

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

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

REST

Metode roles.delete menghapus peran khusus dalam project atau organisasi.

Sebelum menggunakan salah satu dari data permintaan, lakukan penggantian berikut:

• ROLE_NAME: Nama peran lengkap, termasuk setiap awalan organizations/, projects/, atau roles/. Contoh, organizations/123456789012/roles/myCompanyAdmin.

Metode HTTP dan URL:

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

Untuk mengirim permintaan, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

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

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

$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

APIs Explorer (browser)

Buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Lengkapi kolom yang wajib diisi, lalu klik Jalankan.

Respons berisi definisi peran yang dihapus.

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

Saat peran dihapus, binding peran apa pun yang merujuk ke peran tersebut tetap ada dalam kebijakan izin Anda, tetapi tidak akan berpengaruh. Anda dapat membatalkan penghapusan peran dalam waktu 7 hari. Selama periode 7 hari ini, Google Cloud Console menunjukkan bahwa peran tersebut telah dihapus. Anda juga dapat mencantumkan peran yang telah dihapus secara terprogram, tetapi peran tersebut dihilangkan secara default.

Setelah 7 hingga 14 hari, peran tersebut dijadwalkan untuk dihapus secara permanen. Pada tahap ini, peran tersebut tidak lagi diperhitungkan dalam batas 300 peran khusus per organisasi atau 300 peran khusus per project.

Catatan: Peran khusus yang dibuat dalam sebuah project tidak diperhitungkan dalam batas peran khusus organisasi Anda.

Proses penghapusan permanen membutuhkan waktu 30 hari. Selama periode 30 hari ini, peran dan semua binding terkait akan dihapus secara permanen, dan Anda tidak dapat membuat peran baru dengan ID peran yang sama.

Setelah peran dihapus secara permanen, hingga 44 hari setelah permintaan penghapusan awal, Anda dapat membuat peran baru menggunakan ID peran yang sama.

Membatalkan penghapusan peran khusus

Membatalkan penghapusan peran akan mengembalikannya ke status sebelumnya.

Penghapusan peran hanya dapat dibatalkan dalam waktu 7 hari. Setelah 7 hari, peran tersebut dapat dihapus secara permanen kapan saja, dan semua binding peran yang merujuk pada peran tersebut akan dihapus.

Konsol

1. Di Konsol Google Cloud, buka halaman Roles.

   Buka halaman Roles

2. Temukan peran yang ingin Anda batalkan penghapusannya, klik ikon lainnya di akhir baris, lalu klik Batalkan penghapusan.

gcloud

1. Di konsol Google Cloud, aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

2. Gunakan perintah gcloud iam roles undelete untuk membatalkan penghapusan peran khusus:

   • Untuk membatalkan penghapusan peran khusus tingkat organisasi, jalankan perintah berikut:

     gcloud iam roles undelete ROLE_ID --organization=ORGANIZATION_ID

   • Untuk membatalkan penghapusan peran khusus level project, jalankan perintah berikut:

     gcloud iam roles undelete ROLE_ID --project=PROJECT_ID

   Setiap nilai placeholder dijelaskan di bawah:

   • ROLE_ID adalah nama peran, misalnya myCompanyAdmin.

   • ORGANIZATION_ID adalah ID numerik organisasi, seperti 123456789012.

   • PROJECT_ID adalah nama project, seperti my-project.

   Contoh

   Contoh berikut menunjukkan cara membatalkan penghapusan peran khusus tingkat organisasi:

   gcloud iam roles undelete myCompanyAdmin --organization=123456789012

   Jika peran berhasil dibatalkan penghapusannya, output perintah akan terlihat seperti berikut:

   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

   Contoh berikut menunjukkan cara membatalkan penghapusan peran khusus level project:

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

   Jika peran berhasil dibatalkan penghapusannya, output perintah akan terlihat seperti berikut:

   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++

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C++ IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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#

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API C# IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Go IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Java IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

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

Untuk mempelajari cara menginstal dan menggunakan library klien untuk IAM, lihat library klien IAM. Untuk informasi selengkapnya, lihat dokumentasi referensi API Python IAM.

Untuk melakukan autentikasi ke IAM, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

def undelete_role(name: str, project: str) -> dict:
    """Undeletes a role."""

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

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

REST

Metode roles.undelete membatalkan penghapusan peran khusus dalam project atau organisasi.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• ROLE_NAME: Nama peran lengkap, termasuk setiap awalan organizations/, projects/, atau roles/. Contoh, organizations/123456789012/roles/myCompanyAdmin.
• ETAG: ID untuk versi peran. Sertakan kolom ini untuk mencegah menimpa perubahan peran lainnya.

Metode HTTP dan URL:

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

Meminta isi JSON:

{
  "etag": "ETAG"
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$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

APIs Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom lainnya yang wajib diisi, lalu klik Jalankan.

Respons berisi definisi peran yang dibatalkan penghapusannya.

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

Langkah selanjutnya

• Cari tahu cara memberikan peran ke akun utama.
• Pelajari cara menggunakan rekomendasi peran untuk mengurangi cakupan izin untuk entity utama.
• Pelajari pemberian peran bersyarat, yang memberikan peran hanya jika kondisi tertentu terpenuhi.