Membuat dan mengelola daftar kontrol akses (ACL)

Ringkasan

Halaman ini menjelaskan cara mengontrol akses ke bucket dan objek menggunakan Daftar Kontrol Akses (ACL). ACL adalah mekanisme yang dapat Anda gunakan untuk menentukan siapa yang memiliki akses ke bucket dan objek Anda, serta tingkat akses yang mereka miliki.

Lihat ringkasan ACL untuk mempelajari lebih lanjut apakah Anda harus menggunakan ACL untuk mengontrol akses ke resource Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk membuat dan mengelola ACL, minta administrator untuk memberi Anda peran IAM Storage Admin (roles/storage.admin) di bucket yang berisi objek yang ingin Anda buat dan kelola ACL-nya.

Peran bawaan ini berisi izin yang diperlukan untuk membuat dan mengelola ACL. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

• storage.buckets.get
• storage.buckets.list
• Izin ini hanya diperlukan untuk menggunakan Konsol Google Cloud untuk melakukan tugas di halaman ini.
• storage.buckets.setIamPolicy
• storage.buckets.update
• storage.objects.get
• storage.objects.getIamPolicy
• storage.objects.setIamPolicy
• storage.objects.update

Anda juga bisa mendapatkan izin ini dengan peran khusus.

Untuk informasi tentang cara memberikan peran pada bucket, lihat Menggunakan IAM dengan bucket.

Menetapkan atau mengubah ACL

Konsol

Catatan: Anda tidak dapat menggunakan Konsol Google Cloud untuk menetapkan atau mengubah ACL pada bucket; Konsol Google Cloud hanya dapat digunakan untuk menetapkan atau mengubah ACL pada objek individual.

1. Buka browser Cloud Storage di konsol Google Cloud.
   Buka browser Cloud Storage

2. Dari daftar bucket, klik nama bucket yang berisi objek yang ACL-nya ingin Anda ubah.

3. Klik nama objek yang ACL-nya ingin Anda tetapkan atau ubah.

4. Klik Edit akses.

   Dialog izin dengan ACL objek saat ini akan terbuka.

5. Klik + Tambahkan entri.

6. Pilih jenis Entitas yang akan diberi izin.

   Entity menentukan jenis item yang mendapatkan izin (misalnya, pengguna atau grup). Lihat Cakupan Kontrol Akses untuk mengetahui daftar nilai yang didukung untuk Entity.

7. Masukkan nilai di bagian Nama.

   Nama mengidentifikasi pengguna, grup, atau jenis entity tertentu lainnya. Lihat Cakupan Kontrol Akses untuk mengetahui daftar nilai yang didukung untuk Nama.

   Bersama-sama, Entity dan Nama menentukan untuk siapa izin berlaku.

8. Pilih nilai di Akses.

   Akses menentukan izin yang ingin Anda tetapkan pada objek. Lihat Izin Kontrol Akses untuk mengetahui daftar nilai yang didukung untuk Akses.

9. Klik Simpan.

Untuk mempelajari cara mendapatkan informasi error mendetail tentang operasi Cloud Storage yang gagal di Konsol Google Cloud, lihat Pemecahan masalah.

Command line

Untuk menambahkan, mengubah, atau menghapus pemberian izin tertentu pada objek, gunakan perintah objects update dengan flag yang relevan:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME FLAG

Dengan keterangan:

• BUCKET_NAME adalah nama bucket yang berisi objek dengan penerapan modifikasi. Misalnya, example-travel-maps.

• OBJECT_NAME adalah nama objek yang diterapkan modifikasi. Contoh, paris.jpg.

• FLAG adalah salah satu dari berikut ini:

  • --add-acl-grant, beserta pemberian izin yang ingin Anda tambahkan atau ubah. Misalnya, --add-acl-grant=entity=[e-mail],role=READER.

  • --remove-acl-grant, beserta entity yang aksesnya ingin Anda hapus. Misalnya, --remove-acl-grant=[e-mail].

Untuk mengganti semua ACL untuk objek:

1. Menentukan ACL dalam file berformat JSON atau YAML.

2. Gunakan perintah objects update dengan flag --acl-file:

   gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --acl-file=FILE_LOCATION

   Dengan keterangan:

   • BUCKET_NAME adalah nama bucket yang berisi objek dengan penerapan ACL. Misalnya, example-travel-maps.

   • OBJECT_NAME adalah nama objek dengan penerapan ACL. Contoh, paris.jpg.

   • FILE_LOCATION adalah jalur lokal ke file yang berisi ACL yang telah Anda tentukan. Misalnya, Desktop/acls.json.

Isi contoh file ACL ditunjukkan di bawah ini. ACL ini memberikan izin kepada pemilik project 867489160491 beserta pengguna [e-mail] OWNER untuk objek paris.jpg, dan memberikan izin kepada anggota grup gs-announce READER untuk objek ini:

[
  {
    "entity": "project-owners-867489160491",
    "role": "OWNER",
    "projectTeam": {
      "projectNumber": "867489160491",
      "team": "owners"
    },
  },
  {
    "entity": "[e-mail]",
    "email": "[e-mail]",
    "role": "OWNER"
  },
  {
    "entity": "[e-mail]",
    "email": "[e-mail]",
    "role": "READER"
  }
]

Library klien

C++

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C++ API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut akan menambahkan ACL ke objek:

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& entity) {
  StatusOr<gcs::ObjectAccessControl> patched_acl =
      client.CreateObjectAcl(bucket_name, object_name, entity,
                             gcs::ObjectAccessControl::ROLE_OWNER());

  if (!patched_acl) throw std::move(patched_acl).status();
  std::cout << "ACL entry for " << patched_acl->entity() << " in object "
            << patched_acl->object() << " in bucket " << patched_acl->bucket()
            << " is now " << *patched_acl << "\n";
}

Contoh berikut akan menghapus ACL dari objek:

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& entity) {
  StatusOr<gcs::ObjectMetadata> original_metadata = client.GetObjectMetadata(
      bucket_name, object_name, gcs::Projection::Full());
  if (!original_metadata) throw std::move(original_metadata).status();

  std::vector<gcs::ObjectAccessControl> original_acl =
      original_metadata->acl();
  auto it = std::find_if(original_acl.begin(), original_acl.end(),
                         [entity](gcs::ObjectAccessControl const& entry) {
                           return entry.entity() == entity &&
                                  entry.role() ==
                                      gcs::ObjectAccessControl::ROLE_OWNER();
                         });

  if (it == original_acl.end()) {
    std::cout << "Could not find entity " << entity << " for file "
              << object_name << " with role OWNER in bucket " << bucket_name
              << "\n";
    return;
  }

  gcs::ObjectAccessControl owner = *it;
  google::cloud::Status status =
      client.DeleteObjectAcl(bucket_name, object_name, owner.entity());

  if (!status.ok()) throw std::runtime_error(status.message());
  std::cout << "Deleted ACL entry for " << owner.entity() << " for file "
            << object_name << " in bucket " << bucket_name << "\n";
}

C#

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C# API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut akan menambahkan ACL ke objek:

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class AddFileOwnerSample
{
    public Google.Apis.Storage.v1.Data.Object AddFileOwner(
        string bucketName = "your-unique-bucket-name",
        string objectName = "my-file-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var storageObject = storage.GetObject(bucketName, objectName, new GetObjectOptions
        {
            Projection = Projection.Full
        });

        storageObject.Acl.Add(new ObjectAccessControl
        {
            Bucket = bucketName,
            Entity = $"user-{userEmail}",
            Role = "OWNER",
        });
        var updatedObject = storage.UpdateObject(storageObject);
        Console.WriteLine($"Added user { userEmail} as an owner on file { objectName}.");
        return updatedObject;
    }
}

Contoh berikut akan menghapus ACL dari objek:

using Google.Cloud.Storage.V1;
using System;
using System.Linq;

public class RemoveFileOwnerSample
{
    public void RemoveFileOwner(
        string bucketName = "your-unique-bucket-name",
        string objectName = "your-object-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var storageObject = storage.GetObject(bucketName, objectName, new GetObjectOptions { Projection = Projection.Full });
        if (storageObject.Acl == null)
        {
            Console.WriteLine("No owner to remove");
        }
        else
        {
            storageObject.Acl = storageObject.Acl.Where((acl) => !(acl.Entity == $"user-{userEmail}" && acl.Role == "OWNER")).ToList();
            var updatedObject = storage.UpdateObject(storageObject);
            Console.WriteLine($"Removed user {userEmail} from file {objectName}.");
        }
    }
}

Go

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Go API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut akan menambahkan ACL ke objek:

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// addFileOwner adds ACL to the specified object.
func addFileOwner(bucket, object string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// entity := storage.AllUsers
	role := storage.RoleOwner

	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).Object(object).ACL()
	if err := acl.Set(ctx, entity, role); err != nil {
		return fmt.Errorf("ACLHandle.Set: %w", err)
	}
	return nil
}

Contoh berikut akan menghapus ACL dari objek:

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// removeFileOwner removes default ACL from the given object.
func removeFileOwner(bucket, object string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// entity := storage.AllUsers
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).Object(object).ACL()
	if err := acl.Delete(ctx, entity); err != nil {
		return fmt.Errorf("ACLHandle.Delete: %w", err)
	}
	return nil
}

Java

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut akan menambahkan ACL ke objek:

import com.google.cloud.storage.Acl;
import com.google.cloud.storage.Acl.Role;
import com.google.cloud.storage.Acl.User;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class AddFileOwner {

  public static void addFileOwner(
      String projectId, String bucketName, String userEmail, String blobName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // Email of the user you wish to add as a file owner
    // String userEmail = "[e-mail]"

    // The name of the blob/file that you wish to modify permissions on
    // String blobName = "your-blob-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Blob blob = storage.get(BlobId.of(bucketName, blobName));
    Acl newOwner = Acl.of(new User(userEmail), Role.OWNER);

    blob.createAcl(newOwner);
    System.out.println(
        "Added user "
            + userEmail
            + " as an owner on file "
            + blobName
            + " in bucket "
            + bucketName);
  }
}

Contoh berikut akan menghapus ACL dari objek:

import com.google.cloud.storage.Acl.User;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class RemoveFileOwner {

  public static void removeFileOwner(
      String projectId, String bucketName, String userEmail, String blobName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // Email of the user you wish to remove as a file owner
    // String userEmail = "[e-mail]"

    // The name of the blob/file that you wish to modify permissions on
    // String blobName = "your-blob-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Blob blob = storage.get(BlobId.of(bucketName, blobName));
    User ownerToRemove = new User(userEmail);

    boolean success = blob.deleteAcl(ownerToRemove);
    if (success) {
      System.out.println(
          "Removed user "
              + userEmail
              + " as an owner on file "
              + blobName
              + " in bucket "
              + bucketName);
    } else {
      System.out.println("User " + userEmail + " was not found");
    }
  }
}

Node.js

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Node.js API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut akan menambahkan ACL ke objek:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The name of the file to access
// const fileName = 'file.txt';

// The email address of the user to add
// const userEmail = 'user-email-to-add';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function addFileOwner() {
  await storage
    .bucket(bucketName)
    .file(fileName)
    .acl.owners.addUser(userEmail);

  console.log(`Added user ${userEmail} as an owner on file ${fileName}.`);
}

addFileOwner().catch(console.error);

Contoh berikut akan menghapus ACL dari objek:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// The email address of the user to remove
// const userEmail = 'user-email-to-remove';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function removeFileOwner() {
  // Removes the user from the access control list of the file. You can use
  // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
  // deleteAllAuthenticatedUsers() to remove access for different types of entities.
  await storage
    .bucket(bucketName)
    .file(fileName)
    .acl.owners.deleteUser(userEmail);

  console.log(`Removed user ${userEmail} from file ${fileName}.`);
}

removeFileOwner().catch(console.error);

PHP

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage PHP API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut akan menambahkan ACL ke objek:

use Google\Cloud\Storage\StorageClient;

/**
 * Add an entity and role to an object's ACL.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param string $entity The entity for which to update access controls.
 *        (e.g. '[e-mail]')
 * @param string $role The permissions to add for the specified entity.
 *        (e.g. 'OWNER')
 */
function add_object_acl(string $bucketName, string $objectName, string $entity, string $role): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $acl = $object->acl();
    $acl->add($entity, $role);
    printf('Added %s (%s) to gs://%s/%s ACL' . PHP_EOL, $entity, $role, $bucketName, $objectName);
}

Contoh berikut akan menghapus ACL dari objek:

use Google\Cloud\Storage\StorageClient;

/**
 * Delete an entity from an object's ACL.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param string $entity The entity for which to update access controls.
 *        (e.g. '[e-mail]')
 */
function delete_object_acl(string $bucketName, string $objectName, string $entity): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $acl = $object->acl();
    $acl->delete($entity);
    printf('Deleted %s from gs://%s/%s ACL' . PHP_EOL, $entity, $bucketName, $objectName);
}

Python

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Python API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut akan menambahkan ACL ke objek:

from google.cloud import storage


def add_blob_owner(bucket_name, blob_name, user_email):
    """Adds a user as an owner on the given blob."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    # Reload fetches the current ACL from Cloud Storage.
    blob.acl.reload()

    # You can also use `group`, `domain`, `all_authenticated` and `all` to
    # grant access to different types of entities. You can also use
    # `grant_read` or `grant_write` to grant different roles.
    blob.acl.user(user_email).grant_owner()
    blob.acl.save()

    print(
        "Added user {} as an owner on blob {} in bucket {}.".format(
            user_email, blob_name, bucket_name
        )
    )

Contoh berikut akan menghapus ACL dari objek:

from google.cloud import storage


def remove_blob_owner(bucket_name, blob_name, user_email):
    """Removes a user from the access control list of the given blob in the
    given bucket."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    # You can also use `group`, `domain`, `all_authenticated` and `all` to
    # remove access for different types of entities.
    blob.acl.user(user_email).revoke_read()
    blob.acl.user(user_email).revoke_write()
    blob.acl.user(user_email).revoke_owner()
    blob.acl.save()

    print(
        f"Removed user {user_email} from blob {blob_name} in bucket {bucket_name}."
    )

Ruby

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Ruby API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut akan menambahkan ACL ke objek:

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# file_name   = "Name of a file in the Storage bucket"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.acl.add_owner email

puts "Added OWNER permission for #{email} to #{file_name}"

Contoh berikut akan menghapus ACL dari objek:

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# file_name   = "Name of a file in the Storage bucket"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.acl.delete email

puts "Removed ACL permissions for #{email} from #{file_name}"

REST API

JSON API

Saat membuat objek, Anda dapat menentukan properti acl[] dalam isi permintaan atau parameter kueri predefinedAcl dalam permintaan insert. Untuk objek yang ada, tentukan properti acl[] atau parameter kueri predefinedAcl dalam permintaan patch atau update.

Untuk definisi properti ACL objek, lihat resource ObjectAccessControls.

1. Tentukan ACL dalam file.

   Misalnya, jika ACL memberikan izin kepada pemilik project 867489160491 dan pengguna [e-mail] OWNER izin, serta memberikan izin kepada anggota gs-announce grup READER sebelumnya, Anda dapat memiliki file bernama acls.json dengan konten berikut:

   {
   "acl": [
     {
       "entity": "project-owners-867489160491",
       "role": "OWNER",
       "projectTeam": {
         "projectNumber": "867489160491",
         "team": "owners"
       }
     },
     {
       "entity": "[e-mail]",
       "role": "OWNER",
       "email": "[e-mail]"
     },
     {
       "entity": "[e-mail]",
       "role": "READER",
       "email": "[e-mail]"
     }
   ]
   }
   

2. Kirim permintaan patch dengan file JSON, lalu tentukan objek untuk mengaktifkan ACL.

Misalnya, perintah cURL berikut menerapkan payload JSON dari dokumen acls.json ke objek bernama paris.jpg di example-travel-maps bucket:

curl -X PATCH --data @acls.json -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg

XML API

Di XML API, Anda menggunakan ACL dalam format XML. Anda harus melampirkan dokumen XML ke isi permintaan untuk mengubah ACL bucket dan objek. Dokumen XML ditampilkan saat Anda mendapatkan ACL bucket dan objek. Dokumen XML berisi masing-masing bucket atau entri ACL objek.

• Setelah membuat bucket dengan permintaan Bucket PUT, gunakan permintaan Bucket PUT kedua dengan parameter ?acl untuk mengubah ACL bucket.

• Setelah mengupload objek dengan permintaan Objek PUT, ubah ACL dengan permintaan PUT lainnya menggunakan parameter ?acl atau header permintaan x-googl-acl.

Misalnya, perintah cURL berikut menerapkan payload XML dari dokumen acls.xml ke objek bernama paris.jpg di example-travel-maps bucket:

curl -X PUT --data-binary @acls.xml \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Gunakan sintaksis ACL berikut untuk dokumen XML:

Elemen	Deskripsi
AccessControlList	Container untuk elemen Entries dan Owner.
Owner	Container untuk elemen DisplayName dan ID. Elemen ini tidak diperlukan untuk objek karena objek selalu dimiliki oleh pengguna yang menguploadnya. Elemen ini digunakan saat Anda menggunakan sintaksis Amazon S3 ACL dalam skenario migrasi. Amazon Simple Storage Service^TM dan Amazon S3^TM adalah merek dagang Amazon.com, Inc. atau afiliasinya di Amerika Serikat dan/atau negara lainnya.
ID	ID Cloud Storage pemilik bucket.
DisplayName	Tidak diterapkan. Nilainya selalu berupa string kosong.
Entries	Container untuk nol elemen Entry atau lebih.
Entry	Container untuk elemen Scope dan Permission. Entry hanya boleh berisi satu elemen Scope dan satu elemen Permission.
Scope	Container untuk elemen ID, EmailAddress, atau Domain yang menentukan cakupan ACL. Elemen ini harus memiliki atribut type yang berisi salah satu nilai berikut: UserByID, UserByEmail, GroupByID, GroupByEmail, GroupByDomain, AllUsers, atau AllAuthenticatedUsers.
ID	ID untuk penerima hibah saat entri izin ditentukan oleh ID.
EmailAddress	ID email untuk penerima hibah saat entri izin ditentukan melalui email.
Domain	ID domain untuk penerima hibah saat entri izin ditentukan oleh domain.
Name	Elemen opsional yang dapat ditentukan atau yang dapat otomatis ditambahkan jika cakupannya adalah UserByEmail atau GroupByEmail.
Permission	Izin diberikan READ, WRITE, atau FULL_CONTROL.

Saat bekerja dengan ACL menggunakan XML API:

• Anda hanya boleh menggunakan format XML yang dijelaskan di atas.

• Anda tidak dapat menetapkan cakupan duplikat.

  Anda dapat memiliki banyak entri dalam XML ACL, tetapi tidak dapat memiliki entri dengan cakupan duplikat. Misalnya, Anda tidak dapat memiliki dua entri dengan elemen cakupan [e-mail] yang sama.

Contoh berikut menunjukkan entri ACL bucket yang berbeda:

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlList>
  <Owner>
    <ID>00b4903a9721...</ID>
  </Owner>
  <Entries>
    <Entry>
      <Scope type="GroupById">
        <ID>00b4903a9722...</ID>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByDomain">
        <Domain>example.com</Domain>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>[e-mail]</EmailAddress>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="UserByEmail">
        <EmailAddress>[e-mail]</EmailAddress>
        <Name>jane</Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="AllUsers"/>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="AllAuthenticatedUsers"/>
      <Permission>READ</Permission>
    </Entry>
  </Entries>
</AccessControlList>

Menetapkan elemen Nama di XML ACL

Saat mengambil ACL dari bucket atau objek, Anda mungkin melihat elemen <Name> tambahan yang ditambahkan ke beberapa entri Anda. Misalnya, Anda mungkin melihat entri yang terlihat seperti berikut:

<Entry>
  <Scope type="UserByEmail">
    <EmailAddress>[e-mail]</EmailAddress>
    <Name>Jane</Name>
  </Scope>
  <Permission>FULL_CONTROL</Permission>
</Entry>

Elemen <Name> opsional ini diisi dalam dua situasi:

1. Jika ACL bucket atau objek menyertakan <Name> sebagai elemen.

   Saat menetapkan ACL, Anda dapat memilih untuk menyertakan elemen <Name> bersama entri ACL Anda. Anda dapat memberikan nilai apa pun dalam elemen <Name>, dan Cloud Storage akan mengingat nilai ini hingga ACL dihapus atau diganti. Pendekatan ini berguna jika Anda menggunakan ID yang sulit diidentifikasi.

2. Jika cakupan UserByEmail atau GroupByEmail berisi profil Google publik.

   Jika Anda menggunakan salah satu cakupan tersebut, tetapi tidak memberikan elemen <Name>, Cloud Storage akan memeriksa apakah pengguna atau Google Grup yang terkait dengan alamat email tersebut memiliki profil Google publik dengan nama publik. Jika demikian, Cloud Storage secara otomatis mengisi elemen <Name> dengan nama publik.

Menerapkan ACL yang telah ditentukan

Daripada menentukan seluruh ACL satu per satu entri seperti yang ditunjukkan di atas, Anda dapat menggunakan ACL yang telah ditetapkan, yang akan otomatis menerapkan sejumlah entri yang disesuaikan dengan skenario tertentu. Anda dapat menerapkan ACL yang telah ditetapkan ke bucket atau objek dengan menggunakan Google Cloud CLI, JSON API, atau XML API.

Pada objek baru

Untuk menerapkan ACL yang telah ditetapkan ke objek selama upload objek:

Konsol

Anda tidak dapat menerapkan ACL yang telah ditetapkan sebelumnya menggunakan Konsol Google Cloud. Sebagai gantinya, gunakan gcloud storage.

Command line

Gunakan perintah gcloud storage cp dengan flag --predefined-acl:

gcloud storage cp OBJECT gs://BUCKET_NAME --predefined-acl=PREDEFINED_ACL

Misalnya, untuk menerapkan bucketOwnerRead ACL yang telah ditetapkan saat mengupload objek paris.jpg ke bucket example-travel-maps:

gcloud storage cp paris.jpg gs://example-travel-maps --predefined-acl=bucketOwnerRead

REST API

JSON API

Gunakan parameter string kueri predefinedAcl dalam permintaan insert untuk menerapkan ACL yang telah ditentukan sebelumnya.

Misalnya, untuk menerapkan bucketOwnerRead ACL yang telah ditetapkan saat mengupload objek paris.jpg ke bucket example-travel-maps:

curl -X POST --data-binary @paris.jpg -H "Content-Type: image/jpeg" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    "https://storage.googleapis.com/upload/storage/v1/b/example-travel-maps/o?name=paris.jpg&predefinedAcl=bucketOwnerRead"

XML API

Gunakan header x-goog-acl dalam permintaan Put Object untuk menerapkan ACL yang telah ditetapkan.

Misalnya, untuk menerapkan bucket-owner-read ACL yang telah ditetapkan saat mengupload objek paris.jpg ke bucket example-travel-maps:

curl -X PUT --upload-file paris.jpg -H "x-goog-acl: bucket-owner-read" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    https://storage.googleapis.com/example-travel-maps/paris.jpg

Pada bucket atau objek yang ada

Anda juga dapat menerapkan ACL yang telah ditetapkan ke bucket atau objek yang ada. Hal ini berguna jika Anda ingin beralih dari satu ACL yang telah ditetapkan ke ACL lain, atau Anda ingin mengupdate ACL kustom ke ACL yang telah ditetapkan.

Konsol

Anda tidak dapat menerapkan ACL yang telah ditetapkan sebelumnya menggunakan Konsol Google Cloud. Sebagai gantinya, gunakan gcloud storage.

Command line

Gunakan perintah objects update dengan flag --predefined-acl:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --predefined-acl=PREDEFINED_ACL_NAME

Misalnya, untuk menerapkan private ACL yang telah ditetapkan ke objek paris.jpg dalam bucket example-travel-maps:

gcloud storage objects update gs://example-travel-maps/paris.jpg --predefined-acl=private

REST API

JSON API

Gunakan parameter string kueri predefinedAcl, dan tentukan properti acl kosong dalam permintaan patch untuk menerapkan ACL yang sudah ditentukan sebelumnya.

Misalnya, untuk menerapkan private ACL yang telah ditetapkan ke objek paris.jpg dalam bucket example-travel-maps:

curl -X PATCH --data '{"acl": []}'  -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?predefinedAcl=private

XML API

Gunakan header x-goog-acl dengan parameter string kueri acl dalam permintaan Put Object, tetapi jangan sertakan dokumen XML dalam permintaan Anda.

Misalnya, untuk menerapkan private ACL yang telah ditetapkan ke objek paris.jpg dalam bucket example-travel-maps:

curl -X PUT -H "Content-Length: 0" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-acl: private" \
    https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Menetapkan ACL objek default

Untuk menghindari penetapan ACL setiap kali membuat objek baru, Anda dapat menetapkan ACL objek default pada bucket. Setelah Anda melakukannya, setiap objek baru yang ditambahkan ke bucket tersebut, yang tidak secara eksplisit menerapkan ACL, akan menerapkan default ke objek tersebut. Misalnya, Anda mungkin ingin menentukan bahwa hanya sekelompok pengguna tertentu yang memiliki akses ke sebagian besar objek di bucket tertentu. Anda dapat mengubah ACL objek default, lalu menambahkan objek ke bucket. Objek yang ditambahkan ini memiliki ACL objek default yang Anda tentukan secara otomatis diterapkan ke objek tersebut; namun, Anda dapat memberikan ACL yang berbeda kepada objek tertentu, dalam hal ini objek tersebut tidak menerapkan ACL default ke objek tersebut.

Penting: Jika Anda mengubah ACL objek default untuk bucket, perubahan mungkin memerlukan waktu untuk diterapkan, dan objek baru yang dibuat di bucket mungkin masih mendapatkan ACL objek default lama dalam waktu singkat (lihat Konsistensi). Untuk memastikan bahwa objek baru yang dibuat di bucket mendapat ACL objek yang baru, Anda harus menunggu minimal 30 detik untuk perubahan ACL objek default dan pembuatan objek baru.

Untuk melihat dan mengubah ACL objek default untuk bucket:

Konsol

Anda tidak dapat menetapkan ACL objek default menggunakan Konsol Google Cloud. Sebagai gantinya, gunakan gcloud storage.

Command line

1. Gunakan perintah buckets describe dengan flag --format untuk mengambil ACL objek default untuk bucket:

   gcloud storage buckets describe gs://BUCKET_NAME --format="default(default_acl)"

   Dengan BUCKET_NAME adalah nama bucket yang ACL objek default-nya ingin Anda lihat. Contoh, my-bucket.

2. Gunakan perintah buckets update dengan flag yang diinginkan untuk mengubah ACL objek default untuk bucket:

   gcloud storage buckets update gs://BUCKET_NAME FLAG

   Dengan keterangan:

   • BUCKET_NAME adalah nama bucket yang ACL objek default-nya ingin Anda ubah. Misalnya, my-bucket.

   • FLAG adalah salah satu dari berikut ini:

     • --add-default-object-acl-grant dan pemberian yang ingin Anda tambahkan ke ACL objek default keseluruhan untuk bucket.

     • --default-object-acl-file dan jalur ke file lokal yang menentukan ACL objek default baru untuk bucket.

     • --predefined-default-object-acl dan nama ACL objek yang telah ditentukan sebelumnya dan Anda ingin mengganti ACL objek default yang ada untuk bucket.

     • --remove-default-object-acl-grant dan entity yang ingin Anda hapus dari keseluruhan ACL objek default untuk bucket.

Library klien

C++

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C++ API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut menambahkan ACL objek default ke bucket:

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& entity, std::string const& role) {
  StatusOr<gcs::ObjectAccessControl> default_object_acl =
      client.CreateDefaultObjectAcl(bucket_name, entity, role);
  if (!default_object_acl) throw std::move(default_object_acl).status();

  std::cout << "Role " << default_object_acl->role()
            << " will be granted default to " << default_object_acl->entity()
            << " on any new object created on bucket "
            << default_object_acl->bucket() << "\n"
            << "Full attributes: " << *default_object_acl << "\n";
}

Contoh berikut menghapus ACL objek default dari bucket:

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& entity) {
  google::cloud::Status status =
      client.DeleteDefaultObjectAcl(bucket_name, entity);

  if (!status.ok()) throw std::runtime_error(status.message());
  std::cout << "Deleted ACL entry for " << entity << " in bucket "
            << bucket_name << "\n";
}

C#

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C# API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut mencetak ACL objek default untuk bucket:

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class PrintBucketDefaultAclSample
{
    public IEnumerable<ObjectAccessControl> PrintBucketDefaultAcl(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });

        foreach (var acl in bucket.DefaultObjectAcl)
        {
            Console.WriteLine($"{acl.Role}:{acl.Entity}");
        }

        return bucket.DefaultObjectAcl;
    }
}

Contoh berikut menambahkan ACL objek default ke bucket:

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class AddBucketDefaultOwnerSample
{
    public Bucket AddBucketDefaultOwner(
        string bucketName = "your-unique-bucket-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });

        bucket.DefaultObjectAcl.Add(new ObjectAccessControl
        {
            Bucket = bucketName,
            Entity = $"user-{userEmail}",
            Role = "OWNER",
        });
        var updatedBucket = storage.UpdateBucket(bucket);
        Console.WriteLine($"Added user {userEmail} as a default owner on bucket {bucketName}.");
        return updatedBucket;
    }
}

Contoh berikut menghapus ACL objek default dari bucket:

using Google.Cloud.Storage.V1;
using System;
using System.Linq;

public class RemoveBucketDefaultOwnerSample
{
    public void RemoveBucketDefaultOwner(
        string bucketName = "your-unique-bucket-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });
        if (bucket.DefaultObjectAcl == null)
        {
            Console.WriteLine("No default owner to remove");
        }
        else
        {
            bucket.DefaultObjectAcl = bucket.DefaultObjectAcl.Where(acl => !(acl.Entity == $"user-{userEmail}" && acl.Role == "OWNER")).ToList();
            var updatedBucket = storage.UpdateBucket(bucket);
            Console.WriteLine($"Removed user {userEmail} from bucket {bucketName}.");
        }
    }
}

Go

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Go API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut menambahkan ACL objek default ke bucket:

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// addBucketDefaultOwner adds default ACL to the specified bucket.
func addBucketDefaultOwner(bucket string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// entity := storage.AllUsers
	role := storage.RoleOwner

	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).DefaultObjectACL()
	if err := acl.Set(ctx, entity, role); err != nil {
		return fmt.Errorf("ACLHandle.Set: %w", err)
	}
	return nil
}

Contoh berikut menghapus ACL objek default dari bucket:

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// deleteDefaultBucketACL removes default ACL from a bucket.
func removeBucketDefaultOwner(bucket string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// entity := storage.AllUsers
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).DefaultObjectACL()
	if err := acl.Delete(ctx, entity); err != nil {
		return fmt.Errorf("ACLHandle.Delete: %w", err)
	}
	return nil
}

Java

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut menambahkan ACL objek default ke bucket:

import com.google.cloud.storage.Acl;
import com.google.cloud.storage.Acl.Role;
import com.google.cloud.storage.Acl.User;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class AddBucketDefaultOwner {

  public static void addBucketDefaultOwner(String bucketName, String userEmail) {

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The email of the user you wish to add as a default owner
    // String userEmail = "[e-mail]"

    Storage storage = StorageOptions.newBuilder().build().getService();
    Bucket bucket = storage.get(bucketName);
    Acl newDefaultOwner = Acl.of(new User(userEmail), Role.OWNER);

    bucket.createDefaultAcl(newDefaultOwner);
    System.out.println("Added user " + userEmail + " as an owner on " + bucketName);
  }
}

Contoh berikut menghapus ACL objek default dari bucket:

import com.google.cloud.storage.Acl.User;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class RemoveBucketDefaultOwner {

  public static void removeBucketDefaultOwner(String bucketName, String userEmail) {

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The email of the user you wish to remove as a default owner
    // String userEmail = "[e-mail]"

    Storage storage = StorageOptions.newBuilder().build().getService();
    Bucket bucket = storage.get(bucketName);
    User userToRemove = new User(userEmail);

    boolean success = bucket.deleteDefaultAcl(userToRemove);
    if (success) {
      System.out.println("Removed user " + userEmail + " as an owner on " + bucketName);
    } else {
      System.out.println("User " + userEmail + " was not found");
    }
  }
}

Node.js

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Node.js API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut menambahkan ACL objek default ke bucket:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The email address of the user to add
// const userEmail = 'user-email-to-add';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function addBucketDefaultOwner() {
  // Makes the user an owner in the default ACL of the bucket. You can use
  // addAllUsers(), addDomain(), addProject(), addGroup(), and
  // addAllAuthenticatedUsers() to grant access to different types of entities.
  // You can also use "readers" and "writers" to grant different roles.
  await storage.bucket(bucketName).acl.default.owners.addUser(userEmail);

  console.log(`Added user ${userEmail} as an owner on bucket ${bucketName}.`);
}

addBucketDefaultOwner().catch(console.error);

Contoh berikut menghapus ACL objek default dari bucket:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The email address of the user to remove
// const userEmail = 'user-email-to-remove';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function removeBucketDefaultOwner() {
  // Removes the user from the access control list of the bucket. You can use
  // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
  // deleteAllAuthenticatedUsers() to remove access for different types of entities.
  await storage.bucket(bucketName).acl.default.owners.deleteUser(userEmail);

  console.log(`Removed user ${userEmail} from bucket ${bucketName}.`);
}

removeBucketDefaultOwner().catch(console.error);

PHP

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage PHP API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut menambahkan ACL objek default ke bucket:

use Google\Cloud\Storage\StorageClient;

/**
 * Add an entity and role to a bucket's default ACL.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $entity The entity for which to update access controls.
 *        (e.g. '[e-mail]')
 * @param string $role The permissions to add for the specified entity.
 *        (e.g. 'OWNER')
 */
function add_bucket_default_acl(string $bucketName, string $entity, string $role): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $acl = $bucket->defaultAcl();
    $acl->add($entity, $role);
    printf('Added %s (%s) to gs://%s default ACL' . PHP_EOL, $entity, $role, $bucketName);
}

Contoh berikut menghapus ACL objek default dari bucket:

use Google\Cloud\Storage\StorageClient;

/**
 * Delete an entity from a bucket's default ACL.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $entity The entity for which to update access controls.
 *        (e.g. '[e-mail]')
 */
function delete_bucket_default_acl(string $bucketName, string $entity): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $acl = $bucket->defaultAcl();
    $acl->delete($entity);
    printf('Deleted %s from gs://%s default ACL' . PHP_EOL, $entity, $bucketName);
}

Python

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Python API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut menambahkan ACL objek default ke bucket:

from google.cloud import storage


def add_bucket_default_owner(bucket_name, user_email):
    """Adds a user as an owner in the given bucket's default object access
    control list."""
    # bucket_name = "your-bucket-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    # Reload fetches the current ACL from Cloud Storage.
    bucket.acl.reload()

    # You can also use `group`, `domain`, `all_authenticated` and `all` to
    # grant access to different types of entities. You can also use
    # `grant_read` or `grant_write` to grant different roles.
    bucket.default_object_acl.user(user_email).grant_owner()
    bucket.default_object_acl.save()

    print(
        "Added user {} as an owner in the default acl on bucket {}.".format(
            user_email, bucket_name
        )
    )

Contoh berikut menghapus ACL objek default dari bucket:

from google.cloud import storage


def remove_bucket_default_owner(bucket_name, user_email):
    """Removes a user from the access control list of the given bucket's
    default object access control list."""
    # bucket_name = "your-bucket-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    # Reload fetches the current ACL from Cloud Storage.
    bucket.acl.reload()

    # You can also use `group`, `domain`, `all_authenticated` and `all` to
    # remove access for different types of entities.
    bucket.default_object_acl.user(user_email).revoke_read()
    bucket.default_object_acl.user(user_email).revoke_write()
    bucket.default_object_acl.user(user_email).revoke_owner()
    bucket.default_object_acl.save()

    print(
        f"Removed user {user_email} from the default acl of bucket {bucket_name}."
    )

Ruby

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Ruby API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut menambahkan ACL objek default ke bucket:

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.default_acl.add_owner email

puts "Added default OWNER permission for #{email} to #{bucket_name}"

Contoh berikut menghapus ACL objek default dari bucket:

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.default_acl.delete email

puts "Removed default ACL permissions for #{email} from #{bucket_name}"

REST API

JSON API

1. Ambil ACL objek default dengan permintaan GET. Contoh:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?projection=full
   

2. Gunakan permintaan patch untuk mengganti ACL objek default. Misalnya, permintaan berikut mengganti ACL objek default dengan ACL yang ditentukan dalam defacls.json untuk bucket example-travel-maps:

   curl -X PATCH --data @defacls.json -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       https://storage.googleapis.com/storage/v1/b/example-travel-maps
   

   Contoh defacls.json:

   {
   "defaultObjectAcl": [
     {
       "email": "[e-mail]",
       "entity": "[e-mail]",
       "role": "READER"
     }
   ]
   }
   

XML API

1. Ambil ACL objek default dengan permintaan GET yang dicakupkan ke bucket Anda dan parameter ?defaultObjectAcl. Contoh:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       https://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl
   

2. Gunakan permintaan PUT yang dicakupkan ke bucket Anda dengan parameter ?defaultObjectAcl untuk mengganti ACL objek default dengan ACL yang ditentukan dalam acls.xml. Contoh:

   curl -X PUT --data-binary @acls.xml -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl
   

   Contoh acls.xml:

   <AccessControlList>
     <Entries>
       <Entry>
         <Permission>FULL_CONTROL</Permission>
         <Scope type="UserByEmail">
           <EmailAddress>[e-mail]</EmailAddress>
         </Scope>
       </Entry>
     </Entries>
   </AccessControlList>
   

Sintaksis ACL dibahas dalam Menetapkan ACL. Anda juga dapat menentukan ACL yang telah ditetapkan sebagai ACL objek default.

Untuk menetapkan ACL objek default bagi bucket ke ACL yang telah ditentukan:

Konsol

Anda tidak dapat menetapkan ACL objek default menggunakan Konsol Google Cloud. Sebagai gantinya, gunakan gcloud storage.

Command line

Gunakan perintah buckets update dengan flag --predefined-default-object-acl:

gcloud storage buckets update gs://BUCKET_NAME --predefined-default-object-acl=PREDEFINED_ACL

Dengan keterangan:

• BUCKET_NAME adalah nama bucket yang ACL objek default-nya ingin Anda ubah. Misalnya, my-bucket.

• PREDEFINED_ACL adalah nama ACL valid yang telah ditetapkan. Contoh, projectPrivate.

REST API

JSON API

Gunakan permintaan PUT dan parameter predefinedAcl.

Contoh:

curl -X PUT -H "Content-Length: 0" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?predefinedAcl=private

XML API

Gunakan permintaan PUT yang dicakupkan ke bucket Anda dengan parameter ?defaultObjectAcl dan header x-goog-acl.

Contoh:

curl -X PUT -H "x-goog-acl: project-private" -H "Content-Length: 0" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl

ACL objek default untuk bucket yang baru dibuat:

Contoh berikut menunjukkan ACL objek default yang diterapkan secara otomatis ke bucket yang baru dibuat saat Anda tidak menentukan ACL objek default Anda sendiri sebagai bagian dari permintaan. Untuk melihat apakah ACL objek default bucket Anda telah diubah, bandingkan ACL objek default bucket Anda saat ini dengan contoh di bawah ini.

Konsol

Anda tidak dapat menggunakan ACL objek default menggunakan Konsol Google Cloud. Sebagai gantinya, gunakan gcloud storage.

Command line

Pada contoh di bawah, project ID-nya adalah "123412341234"; project ID Anda akan berbeda.

defaultObjectAcl:
– entity: project-owners-123412341234
  etag: CAE=
  kind: storage#objectAccessControl
  projectTeam:
    projectNumber: '123412341234'
    team: owners
  role: OWNER
– entity: project-editors-123412341234
  etag: CAE=
  kind: storage#objectAccessControl
  projectTeam:
    projectNumber: '123412341234'
    team: editors
  role: OWNER
– entity: project-viewers-123412341234
  etag: CAE=
  kind: storage#objectAccessControl
  projectTeam:
    projectNumber: '123412341234'
    team: viewers
  role: READER

REST API

JSON API

Pada contoh di bawah, project ID-nya adalah "123412341234"; project ID Anda akan berbeda.

"defaultObjectAcl": [
  {
    "kind": "storage#objectAccessControl",
    "entity": "project-owners-123412341234",
    "role": "OWNER",
    "projectTeam": {
      "projectNumber": "123412341234",
      "team": "owners"
    }
  },
  {
    "kind": "storage#objectAccessControl",
    "entity": "project-editors-123412341234",
    "role": "OWNER",
    "projectTeam": {
      "projectNumber": "123412341234",
      "team": "editors"
    }
  },
  {
    "kind": "storage#objectAccessControl",
    "entity": "project-viewers-123412341234",
    "role": "READER",
    "projectTeam": {
      "projectNumber": "123412341234",
      "team": "viewers"
    }
  }
]

XML API

Pada contoh di bawah, ID peran project dimulai dengan "00b4903a97..."; project ID Anda akan berbeda.

<?xml version='1.0' encoding='UTF-8'?>
<AccessControlList>
  <Entries>
    <Entry>
      <Scope type='GroupById'>
        <ID>00b4903a9721...</ID>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type='GroupById'>
        <ID>00b4903a9722...</ID>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type='GroupById'>
        <ID>00b4903a9723...</ID>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
  </Entries>
</AccessControlList>

Perlu diperhatikan bahwa ACL objek default untuk bucket yang baru dibuat setara dengan ACL projectPrivate yang telah ditetapkan.

Mengambil ACL

Untuk mendapatkan ACL resource yang ada:

Konsol

Catatan: Anda tidak dapat menggunakan Konsol Google Cloud untuk mendapatkan ACL di bucket; Konsol hanya dapat digunakan untuk mendapatkan ACL pada objek tertentu.

1. Buka browser Cloud Storage di konsol Google Cloud.
   Buka browser Cloud Storage

2. Buka objek yang ACL-nya ingin Anda lihat.

3. Pilih Akses edit dari menu drop-down untuk objek tersebut.

   Anda akan melihat dialog izin dengan izin objek.

Untuk mempelajari cara mendapatkan informasi error mendetail tentang operasi Cloud Storage yang gagal di Konsol Google Cloud, lihat Pemecahan masalah.

Command line

1. Gunakan perintah objects describe dengan flag --format untuk mengambil ACL objek:

   gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(acl)"

   Dengan keterangan:

   • BUCKET_NAME adalah nama bucket yang berisi objek yang ACL-nya ingin Anda lihat. Misalnya, my-bucket.

   • OBJECT_NAME adalah nama objek yang ACL-nya ingin Anda lihat. Contoh, paris.jpg.

Library klien

C++

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C++ API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut mendapatkan ACL objek:

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  StatusOr<std::vector<gcs::ObjectAccessControl>> items =
      client.ListObjectAcl(bucket_name, object_name);

  if (!items) throw std::move(items).status();
  std::cout << "ACLs for object=" << object_name << " in bucket "
            << bucket_name << "\n";
  for (gcs::ObjectAccessControl const& acl : *items) {
    std::cout << acl.role() << ":" << acl.entity() << "\n";
  }
}

C#

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C# API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut mendapatkan ACL objek:

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class PrintFileAclSample
{
    public IEnumerable<ObjectAccessControl> PrintObjectAcl(
        string bucketName = "your-unique-bucket-name",
        string objectName = "your-object-name")
    {
        var storage = StorageClient.Create();
        var storageObject = storage.GetObject(bucketName, objectName, new GetObjectOptions
        {
            Projection = Projection.Full
        });

        foreach (var acl in storageObject.Acl)
        {
            Console.WriteLine($"{acl.Role}:{acl.Entity}");
        }

        return storageObject.Acl;
    }
}

Go

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Go API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut mendapatkan ACL objek:

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
)

// printFileACL lists ACL of the specified object.
func printFileACL(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	rules, err := client.Bucket(bucket).Object(object).ACL().List(ctx)
	if err != nil {
		return fmt.Errorf("ACLHandle.List: %w", err)
	}
	for _, rule := range rules {
		fmt.Fprintf(w, "ACL rule: %v\n", rule)
	}
	return nil
}

Java

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut mendapatkan ACL objek:

import com.google.cloud.storage.Acl;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.List;

public class PrintFileAcl {

  public static void printFileAcl(String bucketName, String blobName) {

    // The ID to give your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The name of the blob/file that you wish to view Acls of
    // String blobName = "your-blob-name";

    Storage storage = StorageOptions.newBuilder().build().getService();
    Blob blob = storage.get(BlobId.of(bucketName, blobName));
    List<Acl> blobAcls = blob.getAcl();

    for (Acl acl : blobAcls) {

      // This will give you the role.
      // See https://cloud.google.com/storage/docs/access-control/lists#permissions
      String role = acl.getRole().name();

      // This will give you the Entity type (i.e. User, Group, Project etc.)
      // See https://cloud.google.com/storage/docs/access-control/lists#scopes
      String entityType = acl.getEntity().getType().name();

      System.out.printf("%s: %s %n", role, entityType);
    }
  }
}

Node.js

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Node.js API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut mendapatkan ACL objek:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function printFileAcl() {
  // Gets the ACL for the file
  const [acls] = await storage.bucket(bucketName).file(fileName).acl.get();

  acls.forEach(acl => {
    console.log(`${acl.role}: ${acl.entity}`);
  });
}

printFileAcl().catch(console.error);

PHP

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage PHP API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut mendapatkan ACL objek:

use Google\Cloud\Storage\StorageClient;

/**
 * Print all entities and roles for an object's ACL.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 */
function get_object_acl(string $bucketName, string $objectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $acl = $object->acl();
    foreach ($acl->get() as $item) {
        printf('%s: %s' . PHP_EOL, $item['entity'], $item['role']);
    }
}

Python

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Python API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut mendapatkan ACL objek:

from google.cloud import storage


def print_blob_acl(bucket_name, blob_name):
    """Prints out a blob's access control list."""

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    for entry in blob.acl:
        print(f"{entry['role']}: {entry['entity']}")

Ruby

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Ruby API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut mendapatkan ACL objek:

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# file_name   = "Name of a file in the Storage bucket"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

puts "ACL for #{file_name} in #{bucket_name}:"

file.acl.owners.each do |owner|
  puts "OWNER #{owner}"
end

file.acl.readers.each do |reader|
  puts "READER #{reader}"
end

REST API

JSON API

1. Pastikan Anda memiliki izin OWNER pada objek.

2. Ambil ACL objek dengan permintaan GET.

   ACL objek ditampilkan dalam format JSON, yang dilampirkan ke isi respons.

Misalnya, untuk menampilkan ACL untuk objek paris.jpg di bucket example-travel-maps:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?projection=full

Anda akan melihat respons yang terlihat seperti:

{
  "kind": "storage#object",
  "id": "example-travel-maps/paris.jpg/1412805837131000",
  "selfLink": "https://www.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg",
  "name": "paris.jpg",
    "bucket": "example-travel-maps",
  ...
  "acl": [
    {
      ...
      "entity": "project-owners-867489160491",
      "role": "OWNER",
      "projectTeam": {
        "projectNumber": "867489160491",
        "team": "owners"
      },
      ...
    },
    {
      ...
      "entity": "[e-mail]",
      "role": "OWNER",
      "email": "[e-mail]",
      ...
    },
    {
      ...
      "entity": "[e-mail]",
      "role": "READER",
      "email": "[e-mail]",
      ...
    }
    ],
  "owner": {
    "entity": "[e-mail]"
  },
  ...
}

Anda juga dapat menggunakan metode GET resource objectAccessControls untuk menampilkan setiap entri dalam ACL objek.

XML API

1. Pastikan Anda memiliki izin FULL_CONTROL pada bucket atau objek.

2. Ambil ACL bucket atau objek dengan menggunakan parameter string kueri acl dalam permintaan GET Object.

ACL dijelaskan dalam XML, yang dilampirkan pada isi respons.

Misalnya, untuk menampilkan ACL untuk objek paris.jpg di bucket example-travel-maps:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Anda akan melihat respons yang terlihat seperti:

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlList>
  <Owner>
    <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
    <Name>Owner Name</Name>
  </Owner>
  <Entries>
    <Entry>
      <Scope type="UserById">
        <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
        <Name>Name</Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="UserByEmail">
        <EmailAddress>[e-mail]</EmailAddress>
        <Name>Jane</Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>[e-mail]</EmailAddress>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
  </Entries>
</AccessControlList>

Anda juga dapat menggunakan metode GET JSON dari resource ObjectAccessControls untuk menampilkan entri ACL tertentu.

Perhatian: ACL berfungsi secara terpisah dari izin IAM. Anda dapat menggunakan dua metode kontrol akses ini untuk menyesuaikan izin. Namun, jika Anda memberikan akses ke bucket dan objek menggunakan izin IAM, izin tersebut tidak muncul di ACL untuk setiap bucket atau objek (kecuali untuk peran legacyBucket).

Langkah berikutnya

• Pelajari ACL lebih lanjut.
• Pelajari cara menyederhanakan kontrol akses menggunakan akses level bucket yang seragam.
• Pelajari praktik terbaik saat menggunakan ACL.