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

ב-Cloud Storage משתמשים בסוכן שירות כדי להעביר נתונים לקטגוריה של 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.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.

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

  • כתיבה בקטגוריה באחסון מדור קודם (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 להגדרות העברה שמוגדרות לדרוס אובייקטים ב-sink כשהם שונים או אף פעם:

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

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

  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.

במאמרי העזרה של Cloud Storage IAM מוסבר איך מקצים תפקידי IAM למשאבים של Cloud Storage.