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

‫Storage Transfer Service משתמש בחשבון שירות בניהול Google, שנקרא סוכן שירות, כדי להעביר נתונים מקטגוריית מקור ב-Cloud Storage. סוכן השירות הזה נוצר בפעם הראשונה שמתקשרים אל 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.

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

• אחת מהאפשרויות:
  • צפייה באובייקטים באחסון (roles/storage.objectViewer) אם ההעברה היא לקטגוריה אחרת של Cloud Storage.
  • יצירת אובייקטים של אחסון (roles/storage.objectCreator) אם ההעברה היא למערכת קבצים.
• בנוסף לאחת מהאפשרויות הבאות:
  • ‫Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter) אם נדרשת הרשאת מחיקת אובייקט.
  • ‫Storage Legacy Bucket Reader (roles/storage.legacyBucketReader) אם לא נדרשת הרשאת מחיקת אובייקטים.

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

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

כשמגדירים את ACL_PRESERVE, נדרשת גם ההרשאה בעלי אובייקט ב-Storage מדור קודם (roles/storage.legacyObjectOwner) לאובייקט המקור ברשימות ACL של אובייקטים. במקרה של ACL_PRESERVE, צריך להוסיף ידנית את חשבון השירות עם התפקיד בעלים של אובייקט מדור קודם באחסון כדי לתת לאובייקט המקור את ההרשאה storage.objects.getIamPolicy.

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

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

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

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

   תיפתח חלונית אינטראקטיבית עם הכותרת Try this method (כדאי לנסות את השיטה הזו).

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

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

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

   כתובת האימייל של סוכן השירות היא בפורמט [e-mail].

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

המסוף

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

   כניסה לדף Buckets

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

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

4. לוחצים על הלחצן + Add principal.

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

6. בתפריט הנפתח בחירת תפקיד, בוחרים באפשרות 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.googleapis.com/storage/v1/b/BUCKET_NAME/iam"

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

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