הגדרת גישה למקור: 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

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.