הגדרת גישה למקור: Cloud Storage

כדי להעביר נתונים מקטגוריית מקור ב-Cloud Storage, שירות Storage Transfer Service משתמש בסוכן שירות. סוכן השירות הזה נוצר בפעם הראשונה שאתם מפעילים את googleServiceAccounts.get.

קטגוריית המקור לא חייבת להיות באותו פרויקט שבו נמצא סוכן השירות. השלבים זהים בכל הפרויקטים שבהם נמצאת הקטגוריה.

הרשאות של משתמשים

כדי לתת לסוכן השירות את ההרשאות הנדרשות, צריכות להיות לכם ההרשאות הרלוונטיות בקטגוריית המקור:

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

התפקידים בעלים של קטגוריית אחסון מדור קודם (roles/storage.legacyBucketOwner) ואדמין של אחסון (roles/storage.admin) מספקים את ההרשאות הנדרשות.

מתן הרשאות אוטומטי במסוף Google Cloud

אם אתם משתמשים במסוף Google Cloud כדי ליצור את ההעברה, ויש לכם את ההרשאות שמפורטות בקטע הרשאות משתמש, סוכן השירות יקבל באופן אוטומטי את ההרשאות הנדרשות בקטגוריית המקור.

אתם יכולים לדלג על השלבים שבדף הזה ולעבור ישירות ליצירת העברה.

ההרשאות הנדרשות

לסוכן השירות צריכות להיות ההרשאות הבאות בקטגוריית המקור:

הרשאה	תיאור
storage.buckets.get	מאפשרת לסוכן השירות לקבל את המיקום של הקטגוריה.
storage.objects.list	מאפשרת לסוכן השירות להציג רשימה של אובייקטים בקטגוריה.
storage.objects.get	מאפשר לסוכן השירות לקרוא אובייקטים בקטגוריה.
storage.objects.create	מאפשרת לסוכן השירות ליצור אובייקטים בקטגוריה. חובה אם ההעברה היא למערכת קבצים. ‫Storage Transfer Service יוצר שתי תיקיות בקטגוריית המקור ומאכלס אותן: cloud-ingest/ מכילה מידע על מערכת הקבצים, ו-storage-transfer/ מכילה יומני העברה.
storage.objects.delete	מאפשר לסוכן השירות למחוק אובייקטים בקטגוריה. חובה אם מגדירים את deleteObjectsFromSourceAfterTransfer בתור true.
storage.objects.getIamPolicy	מאפשרת לסוכן השירות לקרוא רשימות ACL באובייקטים של המקור. חובה אם מופעלת שמירה של רשימות ACL של אובייקטים (ACL_PRESERVE).

התפקידים המוגדרים מראש הבאים מעניקים יחד את ההרשאות הנדרשות:

• אחת מהאפשרויות:
  • צפייה באובייקטים באחסון (roles/storage.objectViewer) אם ההעברה היא לקטגוריה אחרת של Cloud Storage.
  • יצירת אובייקטים באחסון (roles/storage.objectCreator) אם ההעברה היא למערכת קבצים.
• בנוסף לאחד מהמסמכים הבאים:
  • כתיבה בקטגוריה באחסון מדור קודם (roles/storage.legacyBucketWriter) אם נדרשת הרשאה למחיקת אובייקטים.
  • קריאה בקטגוריה באחסון מדור קודם (roles/storage.legacyBucketReader), אם לא נדרשת הרשאה למחיקת אובייקטים.
• בנוסף, אם שומרים את רשימות ה-ACL של האובייקטים באמצעות ACL_PRESERVE:
  • בעלים של אובייקטים באחסון מדור קודם (roles/storage.legacyObjectOwner)

כל תפקיד ב-Cloud Storage שמסומן כתפקיד legacy אפשר להקצות רק ברמת הקטגוריה.

רשימה מלאה של התפקידים ב-Cloud Storage וההרשאות שהם כוללים מופיעה במאמר תפקידי IAM.

מתן ההרשאות הנדרשות

כדי לתת לסוכן השירות את ההרשאות הנדרשות, פועלים לפי השלבים הבאים.

איך מוצאים את כתובת האימייל של סוכן השירות

1. עוברים אל דף העזר של googleServiceAccounts.get.

   נפתחת חלונית אינטראקטיבית בשם Try this method.

2. בחלונית, בקטע Request parameters, מזינים את מזהה הפרויקט. הפרויקט שמציינים כאן צריך להיות הפרויקט שבו משתמשים כדי לנהל את Storage Transfer Service, והוא יכול להיות שונה מהפרויקט של קטגוריית המקור.

3. לוחצים על Execute.

   כתובת האימייל של סוכן השירות מוחזרת כערך של accountEmail. מעתיקים את הערך הזה.

   כתובת האימייל של סוכן השירות היא בפורמט project-PROJECT_NUMBER@storage-transfer-service..

הוספת סוכן השירות למדיניות ברמת הקטגוריה

המסוף

1. במסוף Google Cloud , נכנסים לדף Buckets של Cloud Storage.
   

   כניסה לדף Buckets

2. לוחצים על התפריט Bucket overflow () שמשויך לקטגוריה שבה רוצים להקצות תפקיד לחשבון המשתמש.

3. בוחרים באפשרות Edit access.

4. לוחצים על הכפתור ‎+ Add principal.

5. בשדה New principals, מזינים את כתובת האימייל של החשבון של סוכן השירות.

6. בתפריט הנפתח Select a role, בוחרים באפשרות Storage Object Viewer או Storage Object Creator.

7. לוחצים על הוספת תפקיד.

8. בוחרים באפשרות Storage Legacy Bucket Writer או Storage Legacy Bucket Reader.

9. לוחצים על Save.

gcloud

משתמשים בפקודה 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

מחליפים את מה שכתוב בשדות הבאים:

• ‫BUCKET_NAME הוא שם הקטגוריה שאליה מעניקים גישה לחשבון המשתמש. לדוגמה, my-bucket.
• ‫YOUR_AGENT_EMAIL הוא כתובת האימייל של חשבון הסוכן שהעתקתם בקטע איך מוצאים את כתובת האימייל של סוכן השירות.

דוגמאות קוד

C++

במאמר ספריות הלקוח של Cloud Storage מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Cloud Storage. למידע נוסף, קראו את מאמרי העזרה של Cloud Storage C++ API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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#

במאמר ספריות הלקוח של Cloud Storage מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Cloud Storage. למידע נוסף, קראו את מאמרי העזרה של Cloud Storage C# API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

במאמר ספריות הלקוח של Cloud Storage מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Cloud Storage. למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Go API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

במאמר ספריות הלקוח של Cloud Storage מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Cloud Storage. למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Java API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

במאמר ספריות הלקוח של Cloud Storage מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Cloud Storage. למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Node.js API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

/**
 * 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

במאמר ספריות הלקוח של Cloud Storage מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Cloud Storage. למידע נוסף, קראו את מאמרי העזרה של Cloud Storage PHP API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

במאמר ספריות הלקוח של Cloud Storage מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Cloud Storage. למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Python API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

במאמר ספריות הלקוח של Cloud Storage מוסבר איך להתקין את ספריית הלקוח ולהשתמש בה ב-Cloud Storage. למידע נוסף, קראו את מאמרי העזרה של Cloud Storage Ruby API.

כדי לבצע אימות ב-Cloud Storage, אתם צריכים להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

הערה: השיטה הזו מחליפה את כל מדיניות ה-IAM שמוגדרת בקטגוריה. אם רוצים לשנות את המדיניות הקיימת, מאחזרים אותה באמצעות השיטה getIamPolicy, עורכים אותה לפי הצורך ומשתמשים בגרסה הערוכה בבקשה setIamPolicy.

1. להתקין ולהפעיל את ה-CLI של gcloud, כדי שתוכלו ליצור אסימון גישה לכותרת Authorization.

2. יוצרים קובץ JSON שמכיל את הפרטים הבאים:

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

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫YOUR_AGENT_EMAIL היא כתובת האימייל של חשבון הסוכן שהעתקתם בקטע איך מוצאים את כתובת האימייל של סוכן השירות.

3. משתמשים ב-cURL כדי לשלוח קריאה ל-API בפורמט JSON באמצעות בקשת 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"

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫JSON_FILE_NAME הוא הנתיב לקובץ שיצרתם בשלב 2.
   • ‫OAUTH2_TOKEN הוא אסימון הגישה שיצרתם בשלב 1.
   • BUCKET_NAME הוא שם הקטגוריה שאליה אתם רוצים לתת גישה לחשבון המשתמש. לדוגמה, my-bucket.