Zugriff auf eine Quelle konfigurieren: Cloud Storage

Storage Transfer Service verwendet ein von Google verwaltetes Dienstkonto, das als Dienst-Agent bezeichnet wird, um Daten aus einem Cloud Storage-Quell-Bucket zu verschieben. Dieser Dienst-Agent wird beim ersten Aufruf von googleServiceAccounts.get erstellt.

Der Quell-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 Quell-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 Cloud Console erstellen und die Berechtigungen unter Nutzerberechtigungen haben, erhält der Dienst-Agent automatisch die erforderlichen Berechtigungen für Ihren Quell-Bucket.

Sie können die Schritte auf dieser Seite überspringen und direkt mit Erstellen einer Übertragung fortfahren.

Erforderliche Berechtigungen

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

Berechtigung Beschreibung
storage.buckets.get Ermöglicht dem Dienstkonto, den Standort des Buckets abzurufen
storage.objects.list Ermöglicht dem Dienstkonto, Objekte im Bucket aufzulisten
storage.objects.get Ermöglicht dem Dienstkonto, Objekte im Bucket zu lesen
storage.objects.create

Ermöglicht dem Dienst-Agent, Objekte im Bucket zu erstellen. Erforderlich, wenn die Übertragung in ein Dateisystem erfolgt

Storage Transfer Service erstellt und füllt zwei Ordner im Quell-Bucket aus: cloud-ingest/ enthält Dateisysteminformationen und storage-transfer/ enthält Übertragungslogs.

storage.objects.delete Ermöglicht dem Dienstkonto, Objekte im Bucket zu löschen. Erforderlich, wenn Sie deleteObjectsFromSourceAfterTransfer auf true festlegen

Die folgenden vordefinierten Rollen gewähren die erforderlichen Berechtigungen:

  • Eine der Folgenden:
    • Storage-Objekt-Betrachter (roles/storage.objectViewer), wenn die Übertragung in einen anderen Cloud Storage-Bucket erfolgt.
    • Storage-Objekt-Ersteller (roles/storage.objectCreator), wenn die Übertragung in ein Dateisystem erfolgt.
  • Plus:
    • Autor von Legacy-Storage-Buckets (roles/storage.legacyBucketWriter), wenn die Berechtigung zum Löschen von Objekten erforderlich ist.
    • Leser von Legacy-Storage-Buckets (roles/storage.legacyBucketReader), wenn die Berechtigung zum Löschen von Objekten nicht erforderlich ist.

Jede als legacy-Rolle markierte Cloud Storage-Rolle kann nur auf Bucket-Ebene zugewiesen werden.

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

Wenn für Objekt-ACLs ACL_PRESERVE festgelegt ist, ist für das Quellobjekt zusätzlich die Rolle Inhaber alter Storage-Objekte (roles/storage.legacyObjectOwner) erforderlich. Fügen Sie für ACL_PRESERVE das Dienstkonto manuell hinzu, damit es die Rolle Storage Legacy Object Owner hat, um dem Quellobjekt die Berechtigung storage.objects.getIamPolicy zu gewähren.

Erforderliche Berechtigungen erteilen

Führen Sie die folgenden Schritte aus, um dem Dienst-Agent die erforderlichen Berechtigungen zu erteilen.

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 Quell-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 project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com.

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

Console

  1. Wechseln Sie in der Cloud Console zur Seite Cloud Storage-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 die Schaltfläche + 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 Object Viewer oder Storage Object Creator aus.

  7. Klicken Sie auf Weitere Rolle hinzufügen.

  8. Wählen Sie entweder Storage Legacy Bucket Writer oder Storage Legacy Bucket Reader aus.

  9. Klicken Sie auf Speichern.

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.objectViewer
gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member=serviceAccount:YOUR_AGENT_EMAIL --role=roles/storage.legacyBucketReader

Dabei gilt:

  • BUCKET_NAME ist der Name des Buckets, auf den Sie dem Hauptkonto Zugriff erteilen. 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.

Codebeispiele

C++

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier. Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C++ 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.

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. Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C# 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.


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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier. 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: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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier. Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java 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 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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier. Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Node.js 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.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier. Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage PHP 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.

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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier. 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: 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

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud Storage finden Sie hier. Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Ruby 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.

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. Die gcloud CLI installieren und initialisieren, um ein Zugriffstoken für den Header Authorization zu generieren.

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

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

    Wobei:

  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"

    Dabei gilt:

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