הגדרת גישה ל-sink: Cloud Storage

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

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

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

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

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

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

הענקת הרשאות אוטומטית במסוף Google Cloud

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

אפשר לדלג על השלבים בדף הזה. אם צריך, מגדירים גישה למקור ואז יוצרים העברה.

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

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

הרשאה תיאור
storage.buckets.get מאפשרת לחשבון השירות לקבל את המיקום של קטגוריית ה-bucket.
storage.objects.get התפקיד הזה מאפשר לחשבון השירות לראות אובייקטים ואת המטא-נתונים שלהם, לא כולל רשימות ACL. חובה אם ההעברה מוגדרת ל[החלפת אובייקטים](/storage-transfer/docs/reference/rest/v1/TransferOptions#OverwriteWhen) ביעד כשהם שונים, או אף פעם לא. לא נדרש אם הגדרת ההעברה היא תמיד להחליף את הקובץ.
storage.objects.create מאפשרת לחשבון השירות להוסיף אובייקטים לקטגוריה.
storage.objects.delete

מאפשרת לחשבון השירות למחוק אובייקטים בקטגוריה. חובה אם מגדירים את overwriteObjectsAlreadyExistingInSink או את deleteObjectsUniqueInSink לערך true.

שימו לב: אם בקטגוריית היעד מופעל ניהול גרסאות של אובייקטים, אף אחת מהפקודות overwriteObjectsAlreadyExistingInSink ו-deleteObjectsUniqueInSink לא מוחקת אובייקטים באופן סופי. במקום זאת, גרסאות פעילות רלוונטיות של אובייקטים הופכות ללא עדכניות.
storage.objects.list מאפשרת לחשבון השירות להציג רשימה של אובייקטים בקטגוריה. חובה אם הגדרתם את overwriteObjectsAlreadyExistingInSink לערך false או את deleteObjectsUniqueInSink לערך true.

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

  • Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)

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

  • צפייה באובייקטים באחסון (roles/storage.objectViewer)

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

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

כדי להעניק לסוכן השירות את התפקידים Storage Legacy Bucket Writer ו-Storage Object Viewer, פועלים לפי השלבים הבאים.

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

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

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

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

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

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

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

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

המסוף

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

    כניסה לדף Buckets

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

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

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

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

  6. בתפריט הנפתח Select a role, בוחרים באפשרות Storage Legacy Bucket Writer.

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

  8. חוזרים על הפעולה כדי להוסיף את התפקיד Storage Object Viewer אם ההעברה מוגדרת להחלפת אובייקטים ביעד כשהם שונים, או אף פעם לא.

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.legacyBucketWriter

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

כדי להעניק את התפקיד Storage Object Viewer להעברות שהוגדרו להחלפת אובייקטים במאגר היעד במקרים שבהם האובייקטים שונים או אף פעם לא:

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

דוגמאות קוד

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:dev@iam.gserviceaccount.com")
    {
        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:cloud-logs@google.com"
	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:example@google.com";

    // 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:jdoe@example.com',
//   'group:admins@example.com',
// ];

// 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:example@google.com'])
 */
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: name@example.com"

    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:example@google.com"

  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

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

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

    {
"bindings":[
  {
    "role": "roles/storage.legacyBucketWriter",
    "members":[
      "YOUR_AGENT_EMAIL"
    ]
  },
  {
    "role": "roles/storage.objectViewer",
    "members":[
      "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.

מידע נוסף על הקצאת תפקידי IAM למשאבי Cloud Storage זמין במאמרי העזרה בנושא IAM ב-Cloud Storage.