Zugriff auf eine Senke konfigurieren: Cloud Storage

Cloud Storage verwendet einen Dienst-Agent um Daten in einen Cloud Storage-Bucket zu verschieben. Dieser Dienst-Agent wird beim ersten Aufruf von googleServiceAccounts.get erstellt.

Der Ziel-Bucket muss nicht zum selben Projekt wie der Dienst-Agent gehören. Die Schritte sind unabhängig davon, in welchem Projekt sich der Bucket befindet, identisch.

Nutzerberechtigungen

Sie benötigen die entsprechenden Berechtigungen für den Ziel-Bucket, um dem Dienst-Agent die erforderlichen Berechtigungen zu erteilen:

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

Die Rollen Inhaber alter Storage-Buckets (roles/storage.legacyBucketOwner) und Storage-Administrator (roles/storage.admin) enthalten die erforderlichen Berechtigungen.

Berechtigungen in der Google Cloud Console automatisch gewähren

Wenn Sie die Übertragung in der Google Cloud Console erstellen und die Berechtigungen unter Nutzerberechtigungen haben, erhält der Dienst-Agent automatisch die erforderlichen Berechtigungen für Ihren Ziel-Bucket.

Sie können die Schritte auf dieser Seite überspringen. Konfigurieren Sie bei Bedarf den Zugriff auf Ihre Quelle, erstellen Sie dann eine Übertragung.

Erforderliche Berechtigungen

Das Dienstkonto muss die folgenden Berechtigungen für den Ziel-Bucket haben:

Berechtigung	Beschreibung
storage.buckets.get	Ermöglicht dem Dienstkonto, den Standort des Buckets abzurufen.
storage.objects.get	Ermöglicht dem Dienstkonto, Objekte und ihre Metadaten anzusehen, ausgenommen ACLs. Erforderlich, wenn die Übertragung so konfiguriert ist, dass Objekte in der Senke [überschrieben werden](/storage-transfer/docs/reference/rest/v1/TransferOptions#OverwriteWhen) , wenn sie unterschiedlich sind, oder nie. Nicht erforderlich, wenn die Übertragungseinstellung immer überschreiben lautet.
storage.objects.create	Ermöglicht dem Dienstkonto, Objekte zum Bucket hinzuzufügen.
storage.objects.delete	Ermöglicht dem Dienstkonto, Objekte im Bucket zu löschen. Erforderlich, wenn Sie overwriteObjectsAlreadyExistingInSink oder deleteObjectsUniqueInSink auf true festlegen. Wenn im Ziel-Bucket die Objekt-Versionsverwaltung aktiviert ist, löscht weder overwriteObjectsAlreadyExistingInSink noch deleteObjectsUniqueInSink Objekte endgültig. Stattdessen werden relevante Live-Objektversionen nicht aktuell.
storage.objects.list	Ermöglicht dem Dienstkonto, Objekte im Bucket aufzulisten. Erforderlich, wenn Sie overwriteObjectsAlreadyExistingInSink auf false oder deleteObjectsUniqueInSink auf true gesetzt haben.

Die folgende vordefinierte Rolle gewährt die erforderlichen Berechtigungen:

• Autor von Legacy-Storage-Buckets (roles/storage.legacyBucketWriter)

Weisen Sie dem Dienst-Agent außerdem die folgende vordefinierte Rolle für Übertragungen zu, die so konfiguriert sind, dass Objekte überschriebenwerden, wenn sie unterschiedlich sind, oder nie:

• Storage-Objekt-Betrachter (roles/storage.objectViewer)

Eine vollständige Liste der Cloud Storage-Rollen und der damit verbundenen Berechtigungen, die sie enthalten, finden Sie unter IAM-Rollen.

Erforderliche Berechtigungen erteilen

So weisen Sie dem Dienst-Agent die Rollen Autor von Legacy-Storage-Buckets und Storage-Objekt-Betrachter zu:

E-Mail-Adresse des Dienst-Agents suchen

1. Rufen Sie die Referenzseite googleServiceAccounts.get auf.

   Es wird ein interaktives Steuerfeld mit dem Titel Diese Methode testen geöffnet.

2. Geben Sie im Steuerfeld unter Anfrageparameter Ihre Projekt-ID ein. Das hier angegebene Projekt muss das Projekt sein, das Sie zum Verwalten des Storage Transfer Service verwenden. Dieses kann sich vom Projekt des Ziel-Buckets unterscheiden.

3. Klicken Sie auf Ausführen.

   Die E-Mail-Adresse des Dienst-Agents wird als Wert von accountEmail zurückgegeben. Kopieren Sie diesen Wert.

   Die E-Mail des Dienst-Agents hat das Format [e-mail].

Dienst-Agent zu einer Richtlinie auf Bucket-Ebene hinzufügen

Console

1. Wechseln Sie in der Google Cloud Console unter „Cloud Storage“ zur Seite Buckets.
   

   Buckets aufrufen

2. Klicken Sie auf das Dreipunkt-Menü  des Buckets, für den Sie einem Hauptkonto eine Rolle zuweisen möchten.

3. Wählen Sie Zugriff bearbeiten aus.

4. Klicken Sie auf den Button + Hauptkonto hinzufügen.

5. Geben Sie im Feld Neue Hauptkonten die E-Mail-Adresse des Dienst-Agents ein.

6. Wählen Sie im Drop-down- Menü Rolle auswählen die Option Storage Legacy Bucket Writer aus.

7. Klicken Sie auf Speichern.

8. Wiederholen Sie den Vorgang, um die Rolle Storage Object Viewer hinzuzufügen, wenn die Übertragung so konfiguriert ist, dass Objekte in der Senke überschrieben werden, wenn sie unterschiedlich sind, oder nie.

gcloud

Führen Sie den Befehl gcloud storage buckets add-iam-policy-binding aus:

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

Ersetzen Sie Folgendes:

• BUCKET_NAME ist der Name des Buckets, für den Sie dem Hauptkonto Zugriff gewähren. Beispiel: my-bucket.
• YOUR_AGENT_EMAIL ist die E-Mail-Adresse des Agent-Kontos, die Sie unter E-Mail-Adresse des Dienst-Agents suchen kopiert haben.

So gewähren Sie die Rolle Storage Object Viewer für Übertragungen, die so konfiguriert sind, dass Objekte in der Senke überschrieben werden, wenn sie unterschiedlich sind, oder nie:

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

Codebeispiele

C++

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier: Cloud Storage-Clientbibliotheken. Weitere Informationen finden Sie in der Cloud Storage C++ API Referenzdokumentation.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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#

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier: Cloud Storage-Clientbibliotheken. Weitere Informationen finden Sie in der Cloud Storage C# API Referenzdokumentation.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier: Cloud Storage-Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Go API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier: Cloud Storage-Clientbibliotheken. Weitere Informationen finden Sie in der Cloud Storage Java API Referenzdokumentation.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier: Cloud Storage-Clientbibliotheken. Weitere Informationen finden Sie in der Cloud Storage Node.js API Referenzdokumentation.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier: Cloud Storage-Clientbibliotheken. Weitere Informationen finden Sie in der Cloud Storage PHP API Referenzdokumentation.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier: Cloud Storage-Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier: Cloud Storage-Clientbibliotheken. Weitere Informationen finden Sie in der Cloud Storage Ruby API Referenzdokumentation.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

Hinweis:Diese Methode ersetzt alle vorhandenen IAM-Richtlinien, die für einen Bucket festgelegt sind. Rufen Sie sie mit der Methode getIamPolicy ab, bearbeiten Sie sie nach Bedarf und verwenden Sie die bearbeitete Version in der Anfrage setIamPolicy , wenn Sie die vorhandene Richtlinie ändern möchten.

1. Installieren und initialisieren Sie die gcloud CLI, um ein Zugriffstoken für den Authorization Header zu generieren.

2. Erstellen Sie eine JSON-Datei, die folgende Informationen enthält:

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

   Ersetzen Sie Folgendes:

   • YOUR_AGENT_EMAIL ist die E-Mail-Adresse des Agent-Kontos, die Sie unter E-Mail-Adresse des Dienst-Agents suchen kopiert haben.

3. Verwenden Sie cURL, um die JSON API mit einer PUT setIamPolicy-Anfrage aufzurufen:

   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"

   Ersetzen Sie Folgendes:

   • JSON_FILE_NAME ist der Pfad für die Datei, die Sie in Schritt 2 erstellt haben.
   • OAUTH2_TOKEN ist das Zugriffstoken, das Sie in Schritt 1 generiert haben.
   • BUCKET_NAME ist der Name des Buckets, für den Sie dem Hauptkonto Zugriff gewähren möchten. Beispiel: my-bucket.

Weitere Informationen zum Zuweisen von IAM-Rollen zu Cloud Storage Ressourcen finden Sie in der IAM-Dokumentation für Cloud Storage.