Mengonfigurasi akses ke sumber: Cloud Storage

Storage Transfer Service menggunakan a agen layanan untuk memindahkan data dari bucket sumber Cloud Storage. Agen layanan ini dibuat saat pertama kali Anda memanggil googleServiceAccounts.get.

Bucket sumber tidak harus berada dalam project yang sama dengan agen layanan. Langkah-langkahnya sama, terlepas dari project tempat bucket berada.

Izin pengguna

Untuk memberikan izin yang diperlukan kepada agen layanan, Anda harus memiliki izin yang relevan pada bucket sumber:

• storage.buckets.getIamPolicy
• storage.buckets.setIamPolicy

Peran Storage Legacy Bucket Owner (roles/storage.legacyBucketOwner) atau peran Storage Admin (roles/storage.admin) memberikan izin yang diperlukan.

Memberikan izin secara otomatis di Google Cloud konsol

Jika Anda menggunakan Google Cloud konsol untuk membuat transfer, dan memiliki izin yang tercantum di Izin pengguna, agen layanan akan otomatis diberi izin yang diperlukan di bucket sumber Anda.

Anda dapat melewati langkah-langkah di halaman ini dan langsung ke membuat transfer.

Izin yang diperlukan

Agen layanan harus memiliki izin berikut untuk bucket sumber:

Izin	Deskripsi
storage.buckets.get	Mengizinkan agen layanan mendapatkan lokasi bucket.
storage.objects.list	Mengizinkan agen layanan mencantumkan objek dalam bucket.
storage.objects.get	Mengizinkan agen layanan membaca objek dalam bucket.
storage.objects.create	Mengizinkan agen layanan membuat objek dalam bucket. Diperlukan jika transfer dilakukan ke sistem file. Storage Transfer Service creates and populates two folders in the source bucket: cloud-ingest/ berisi informasi sistem file, dan storage-transfer/ berisi log transfer.
storage.objects.delete	Mengizinkan agen layanan menghapus objek dalam bucket. Diperlukan jika Anda menetapkan deleteObjectsFromSourceAfterTransfer ke true.
storage.objects.getIamPolicy	Mengizinkan agen layanan membaca ACL pada objek sumber. Diperlukan jika pelestarian ACL objek (ACL_PRESERVE) diaktifkan.

Peran bawaan berikut bersama-sama memberikan izin yang diperlukan:

• Salah satu dari:
  • Storage Object Viewer (roles/storage.objectViewer) jika transfer dilakukan ke bucket Cloud Storage lain.
  • Storage Object Creator (roles/storage.objectCreator) jika transfer dilakukan ke sistem file.
• Ditambah salah satu dari:
  • Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter) jika izin penghapusan objek diperlukan.
  • Storage Legacy Bucket Reader (roles/storage.legacyBucketReader) jika izin penghapusan objek tidak diperlukan.
• Selain itu, jika mempertahankan objek ACL dengan ACL_PRESERVE:
  • Storage Legacy Object Owner (roles/storage.legacyObjectOwner)

Peran Cloud Storage apa pun yang ditandai sebagai peran legacy hanya dapat diberikan di tingkat bucket.

Untuk mengetahui daftar lengkap peran Cloud Storage dan izin yang dikandungnya, lihat Peran IAM.

Memberikan izin yang diperlukan

Untuk memberikan izin yang diperlukan kepada agen layanan, ikuti langkah-langkah di bawah.

Menemukan email agen layanan

1. Buka halaman referensi googleServiceAccounts.get.

   Panel interaktif akan terbuka, berjudul Try this method.

2. Di panel, di bagian Request parameters, masukkan project ID Anda. Project yang Anda tentukan di sini harus berupa project yang Anda gunakan untuk mengelola Storage Transfer Service, yang mungkin berbeda dengan bucket sumber project.

3. Klik Execute.

   Email agen layanan Anda akan ditampilkan sebagai nilai accountEmail. Salin nilai ini.

   Email agen layanan menggunakan format project-PROJECT_NUMBER@storage-transfer-service..

Menambahkan agen layanan ke kebijakan tingkat bucket

Konsol

1. Di Google Cloud konsol, buka halaman Buckets Cloud Storage.
   

   Buka Buckets

2. Klik menu Bucket overflow () yang terkait dengan bucket yang ingin Anda beri peran entitas.

3. Pilih akses edit.

4. Klik tombol + Add principal.

5. Di kolom New principals, masukkan email akun agen layanan Anda.

6. Pilih Storage Object Viewer atau Storage Object Creator dari menu drop-down Select a role.

7. Klik Add another role.

8. Pilih Storage Legacy Bucket Writer atau Storage Legacy Bucket Reader.

9. Klik Save.

gcloud

Gunakan perintah gcloud storage buckets add-iam-policy-binding:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member=serviceAccount:YOUR_AGENT_EMAIL --role=roles/storage.objectViewer

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member=serviceAccount:YOUR_AGENT_EMAIL --role=roles/storage.legacyBucketReader

Ganti kode berikut:

• BUCKET_NAME adalah nama bucket yang aksesnya Anda berikan ke akun utama. Contoh, my-bucket.
• YOUR_AGENT_EMAIL adalah email akun agen yang Anda salin di Menemukan email agen layanan.

Contoh kode

C++

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud Storage, lihat Library klien Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Cloud Storage C++ API.

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

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& role, std::string const& member) {
  auto policy = client.GetNativeBucketIamPolicy(
      bucket_name, gcs::RequestedPolicyVersion(3));

  if (!policy) throw std::move(policy).status();

  policy->set_version(3);
  for (auto& binding : policy->bindings()) {
    if (binding.role() != role || binding.has_condition()) {
      continue;
    }
    auto& members = binding.members();
    if (std::find(members.begin(), members.end(), member) == members.end()) {
      members.emplace_back(member);
    }
  }

  auto updated = client.SetNativeBucketIamPolicy(bucket_name, *policy);
  if (!updated) throw std::move(updated).status();

  std::cout << "Updated IAM policy bucket " << bucket_name
            << ". The new policy is " << *updated << "\n";
}

C#

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud Storage, lihat Library klien Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Cloud Storage C# API.

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

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

public class AddBucketIamMemberSample
{
    public Policy AddBucketIamMember(
        string bucketName = "your-unique-bucket-name",
        string role = "roles/storage.objectViewer",
        string member = "serviceAccount:[e-mail]")
    {
        var storage = StorageClient.Create();
        var policy = storage.GetBucketIamPolicy(bucketName, new GetBucketIamPolicyOptions
        {
            RequestedPolicyVersion = 3
        });
        // Set the policy schema version. For more information, please refer to https://cloud.google.com/iam/docs/policies#versions.
        policy.Version = 3;

        Policy.BindingsData bindingToAdd = new Policy.BindingsData
        {
            Role = role,
            Members = new List<string> { member }
        };

        policy.Bindings.Add(bindingToAdd);
        var bucketIamPolicy = storage.SetBucketIamPolicy(bucketName, policy);
        Console.WriteLine($"Added {member} with role {role} " + $"to {bucketName}");
        return bucketIamPolicy;
    }
}

Go

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud Storage, lihat Library klien Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Cloud Storage Go API.

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

import (
	"context"
	"fmt"
	"io"
	"time"

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

// addBucketIAMMember adds the bucket IAM member to permission role.
func addBucketIAMMember(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	policy, err := bucket.IAM().Policy(ctx)
	if err != nil {
		return fmt.Errorf("Bucket(%q).IAM().Policy: %w", bucketName, err)
	}
	// Other valid prefixes are "serviceAccount:", "user:"
	// See the documentation for more values.
	// https://cloud.google.com/storage/docs/access-control/iam
	identity := "group:[e-mail]"
	var role iam.RoleName = "roles/storage.objectViewer"

	policy.Add(identity, role)
	if err := bucket.IAM().SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("Bucket(%q).IAM().SetPolicy: %w", bucketName, err)
	}
	// NOTE: It may be necessary to retry this operation if IAM policies are
	// being modified concurrently. SetPolicy will return an error if the policy
	// was modified since it was retrieved.
	fmt.Fprintf(w, "Added %v with role %v to %v\n", identity, role, bucketName)
	return nil
}

Java

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud Storage, lihat Library klien Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Java API dokumentasi referensi.

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

import com.google.cloud.Binding;
import com.google.cloud.Policy;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

public class AddBucketIamMember {
  /** Example of adding a member to the Bucket-level IAM */
  public static void addBucketIamMember(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

    // For more information please read:
    // https://cloud.google.com/storage/docs/access-control/iam
    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    Policy originalPolicy =
        storage.getIamPolicy(bucketName, Storage.BucketSourceOption.requestedPolicyVersion(3));

    String role = "roles/storage.objectViewer";
    String member = "group:[e-mail]";

    // getBindingsList() returns an ImmutableList and copying over to an ArrayList so it's mutable.
    List<Binding> bindings = new ArrayList(originalPolicy.getBindingsList());

    // Create a new binding using role and member
    Binding.Builder newMemberBindingBuilder = Binding.newBuilder();
    newMemberBindingBuilder.setRole(role).setMembers(Arrays.asList(member));
    bindings.add(newMemberBindingBuilder.build());

    // Update policy to add member
    Policy.Builder updatedPolicyBuilder = originalPolicy.toBuilder();
    updatedPolicyBuilder.setBindings(bindings).setVersion(3);
    Policy updatedPolicy = storage.setIamPolicy(bucketName, updatedPolicyBuilder.build());

    System.out.printf("Added %s with role %s to %s\n", member, role, bucketName);
  }
}

Node.js

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud Storage, lihat Library klien Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Node.js API dokumentasi referensi.

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

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

// The role to grant
// const roleName = 'roles/storage.objectViewer';

// The members to grant the new role to
// const members = [
//   'user:[e-mail]',
//   'group:[e-mail]',
// ];

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

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

async function addBucketIamMember() {
  // Get a reference to a Google Cloud Storage bucket
  const bucket = storage.bucket(bucketName);

  // For more information please read:
  // https://cloud.google.com/storage/docs/access-control/iam
  const [policy] = await bucket.iam.getPolicy({requestedPolicyVersion: 3});

  // Adds the new roles to the bucket's IAM policy
  policy.bindings.push({
    role: roleName,
    members: members,
  });

  // Updates the bucket's IAM policy
  await bucket.iam.setPolicy(policy);

  console.log(
    `Added the following member(s) with role ${roleName} to ${bucketName}:`
  );

  members.forEach(member => {
    console.log(`  ${member}`);
  });
}

addBucketIamMember().catch(console.error);

PHP

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud Storage, lihat Library klien Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Cloud Storage PHP API dokumentasi referensi.

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

use Google\Cloud\Storage\StorageClient;

/**
 * Adds a new member / role IAM pair to a given Cloud Storage bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $role The role to which the given member should be added.
 *        (e.g. 'roles/storage.objectViewer')
 * @param string[] $members The member(s) to be added to the role.
 *        (e.g. ['group:[e-mail]'])
 */
function add_bucket_iam_member(string $bucketName, string $role, array $members): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $policy = $bucket->iam()->policy(['requestedPolicyVersion' => 3]);
    $policy['version'] = 3;

    $policy['bindings'][] = [
        'role' => $role,
        'members' => $members
    ];

    $bucket->iam()->setPolicy($policy);

    printf('Added the following member(s) to role %s for bucket %s' . PHP_EOL, $role, $bucketName);
    foreach ($members as $member) {
        printf('    %s' . PHP_EOL, $member);
    }
}

Python

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud Storage, lihat Library klien Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Python API dokumentasi referensi.

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

from google.cloud import storage


def add_bucket_iam_member(bucket_name, role, member):
    """Add a new member to an IAM Policy"""
    # bucket_name = "your-bucket-name"
    # role = "IAM role, e.g., roles/storage.objectViewer"
    # member = "IAM identity, e.g., user: [e-mail]"

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

    policy = bucket.get_iam_policy(requested_policy_version=3)

    policy.bindings.append({"role": role, "members": {member}})

    bucket.set_iam_policy(policy)

    print(f"Added {member} with role {role} to {bucket_name}.")

Ruby

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Cloud Storage, lihat Library klien Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Ruby API dokumentasi referensi.

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

def add_bucket_iam_member bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

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

  role   = "roles/storage.objectViewer"
  member = "group:[e-mail]"

  bucket.policy requested_policy_version: 3 do |policy|
    policy.bindings.insert role: role, members: [member]
  end

  puts "Added #{member} with role #{role} to #{bucket_name}"
end

Rust

use google_cloud_iam_v1::model::Binding;
use google_cloud_storage::client::StorageControl;

pub async fn sample(
    client: &StorageControl,
    bucket_id: &str,
    role: &str,
    member: &str,
) -> anyhow::Result<()> {
    let mut policy = client
        .get_iam_policy()
        .set_resource(format!("projects/_/buckets/{bucket_id}"))
        .send()
        .await?;
    policy
        .bindings
        .push(Binding::new().set_role(role).set_members([member]));
    let updated_policy = client
        .set_iam_policy()
        .set_resource(format!("projects/_/buckets/{bucket_id}"))
        .set_policy(policy)
        .send()
        .await?;
    println!(
        "Successfully added binding for {member} to bucket {bucket_id} policy: {updated_policy:?}"
    );
    Ok(())
}

JSON

Catatan: Metode ini menggantikan kebijakan IAM yang ada yang ditetapkan pada bucket. Jika Anda ingin mengubah kebijakan yang ada, ambil kebijakan tersebut dengan metode getIamPolicy, edit sesuai kebutuhan, dan gunakan versi yang diedit dalam permintaan setIamPolicy Anda.

1. Pastikan gcloud CLI telah diinstal dan diinisialisasi, yang memungkinkan Anda membuat token akses untuk header Authorization.

2. Buat file JSON yang berisi informasi berikut:

   {
   "bindings":[
     {
       "role": "roles/storage.objectViewer",
       "members":[
         "YOUR_AGENT_EMAIL"
       ]
     },
     {
       "role": "roles/storage.legacyBucketReader",
       "members":[
         "YOUR_AGENT_EMAIL"
       ]
     }
   ]
   }

   Ganti kode berikut:

   • YOUR_AGENT_EMAIL adalah email akun agen yang Anda salin di Menemukan email agen layanan.

3. Gunakan cURL untuk memanggil JSON API dengan permintaan PUT setIamPolicy:

   curl -X PUT --data-binary @JSON_FILE_NAME \
   -H "Authorization: Bearer OAUTH2_TOKEN" \
   -H "Content-Type: application/json" \
   "https://storage./storage/v1/b/BUCKET_NAME/iam"

   Ganti kode berikut:

   • JSON_FILE_NAME adalah jalur untuk file yang Anda buat di Langkah 2.
   • OAUTH2_TOKEN adalah token akses yang Anda buat pada Langkah 1.
   • BUCKET_NAME adalah nama bucket yang ingin Anda beri akses utama. Contoh, my-bucket.