Configurare l'accesso a una sorgente: Cloud Storage

Storage Transfer Service utilizza un account di servizio gestito da Google, noto come agente di servizio, per spostare i dati da un bucket di origine Cloud Storage. Questo agente di servizio viene creato la prima volta che chiami googleServiceAccounts.get

Il bucket di origine non deve necessariamente appartenere allo stesso progetto dell'agente di servizio. I passaggi sono gli stessi indipendentemente dal progetto in cui si trova il bucket.

Autorizzazioni utente

Per concedere le autorizzazioni richieste all'agente di servizio, devi avere le autorizzazioni pertinenti sul bucket di origine:

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

Il ruolo Proprietario bucket legacy Storage (roles/storage.legacyBucketOwner) oppure il ruolo Storage Admin (roles/storage.admin) fornisce i requisiti autorizzazioni aggiuntive.

Concessione automatica delle autorizzazioni nella console Google Cloud

Se utilizzi la console Google Cloud per creare il trasferimento e hai le autorizzazioni elencate in Autorizzazioni utente, all'agente di servizio verranno concesse automaticamente del bucket di origine.

Puoi saltare i passaggi in questa pagina direttamente alla creazione di un trasferimento.

Autorizzazioni obbligatorie

L'agente di servizio deve disporre delle seguenti autorizzazioni per il bucket di origine:

Autorizzazione	Descrizione
storage.buckets.get	Consente all'agente di servizio di ottenere la località del bucket.
storage.objects.list	Consente all'agente di servizio di elencare gli oggetti nel bucket.
storage.objects.get	Consente all'agente di servizio di leggere gli oggetti nel bucket.
storage.objects.create	Consente all'agente di servizio di creare oggetti nel bucket. Obbligatorio se il trasferimento avviene in un file system. Storage Transfer Service crea compila due cartelle nel bucket di origine: cloud-ingest/ contiene informazioni sul file system e storage-transfer/ contiene i log di trasferimento.
storage.objects.delete	Consente all'agente di servizio di eliminare gli oggetti nel bucket. Obbligatorio se imposti deleteObjectsFromSourceAfterTransfer su true.

I seguenti ruoli predefiniti insieme concedono le autorizzazioni richieste:

• Uno dei seguenti:
  • Visualizzatore oggetti Storage (roles/storage.objectViewer) se il trasferimento avviene in un altro bucket Cloud Storage.
  • Creatore oggetti Storage (roles/storage.objectCreator), se il trasferimento in un file system.
• Più uno dei seguenti:
  • Writer bucket legacy Storage (roles/storage.legacyBucketWriter) se è richiesta l'autorizzazione di eliminazione degli oggetti.
  • Lettore bucket Storage legacy (roles/storage.legacyBucketReader) se l'autorizzazione di eliminazione degli oggetti non è obbligatoria.

Qualsiasi ruolo di Cloud Storage contrassegnato come legacy può essere concesso solo al a livello di bucket.

Per un elenco completo dei ruoli di Cloud Storage e delle autorizzazioni che contengono, consulta Ruoli IAM.

Per gli ACL dell'oggetto, quando è impostato ACL_PRESERVE, è richiesto anche il ruolo Proprietario oggetti legacy Storage (roles/storage.legacyObjectOwner) per l'oggetto di origine. Per ACL_PRESERVE, aggiungi manualmente l'account di servizio con il ruolo Proprietario oggetti legacy Storage in modo da concedere all'oggetto di origine l'autorizzazione storage.objects.getIamPolicy.

Concedi le autorizzazioni richieste

Per concedere le autorizzazioni necessarie all'agente di servizio, segui i passaggi riportati di seguito.

Trovare l'email dell'agente di servizio

1. Vai alla pagina di riferimento di googleServiceAccounts.get.

   Viene visualizzato un riquadro interattivo denominato Prova questo metodo.

2. Nel riquadro, in Parametri di richiesta, inserisci il tuo ID progetto. Il progetto specificato qui deve essere quello che stai per gestire Storage Transfer Service, che potrebbe essere diverso dall'origine progetto del bucket.

3. Fai clic su Execute (Esegui).

   L'email dell'agente di servizio viene restituita come valore di accountEmail. Copia questo valore.

   L'email dell'agente di servizio utilizza il formato [e-mail].

Aggiungi l'agente di servizio a un criterio a livello di bucket

Console

1. Nella console Google Cloud, vai alla pagina Bucket in Cloud Storage.
   

   Vai a Bucket

2. Fai clic sul menu Extra del bucket () associato al bucket a cui vuoi concedere un ruolo a un'entità.

3. Scegli Modifica accesso.

4. Fai clic sul pulsante + Aggiungi entità.

5. Nel campo Nuove entità, inserisci l'indirizzo email dell'account dell'agente di servizio.

6. Seleziona Storage Object Viewer o Storage Object Creator dal menu a discesa Seleziona un ruolo.

7. Fai clic su Aggiungi un altro ruolo.

8. Seleziona Storage Legacy Bucket Writer o Storage Legacy Bucket Reader.

9. Fai clic su Salva.

gcloud

Usa il comando 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

Dove:

• BUCKET_NAME è il nome del bucket a cui stai grantando l'accesso principale. Ad esempio, my-bucket.
• YOUR_AGENT_EMAIL è l'indirizzo email dell'account dell'agente che hai copiato in Trovare l'indirizzo email dell'agente di servizio.

Esempi di codice

C++

Per scoprire come installare e utilizzare la libreria client per Cloud Storage, consulta Librerie client di Cloud Storage. Per ulteriori informazioni, consulta API Cloud Storage C++ documentazione di riferimento.

Per autenticarti a Cloud Storage, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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#

Per scoprire come installare e utilizzare la libreria client per Cloud Storage, consulta Librerie client di Cloud Storage. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage C#.

Per eseguire l'autenticazione su Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Cloud Storage, consulta Librerie client di Cloud Storage. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Go.

Per eseguire l'autenticazione su Cloud Storage, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Cloud Storage, vedi Librerie client di Cloud Storage. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Java.

Per autenticarti a Cloud Storage, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Cloud Storage, vedi Librerie client di Cloud Storage. Per ulteriori informazioni, consulta API Cloud Storage Node.js documentazione di riferimento.

Per autenticarti a Cloud Storage, configura le credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Cloud Storage, vedi Librerie client di Cloud Storage. Per ulteriori informazioni, consulta API Cloud Storage PHP documentazione di riferimento.

Per autenticarti a Cloud Storage, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Cloud Storage, consulta Librerie client di Cloud Storage. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Python.

Per autenticarti a Cloud Storage, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Cloud Storage, vedi Librerie client di Cloud Storage. Per ulteriori informazioni, consulta API Cloud Storage Ruby documentazione di riferimento.

Per autenticarti a Cloud Storage, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.

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

Nota: questo metodo sostituisce eventuali Criterio IAM impostato su un bucket. Se vuoi modificare il criterio esistente, recuperalo con il metodo getIamPolicy, modificalo in base alle tue esigenze e utilizza la versione modificata nella richiesta setIamPolicy.

1. Avere gcloud CLI installato e inizializzato, che consente generi un token di accesso per l'intestazione Authorization.

2. Crea un file JSON contenente le seguenti informazioni:

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

   Dove:

   • YOUR_AGENT_EMAIL è l'indirizzo email dell'account agente che hai copiato in Trovare l'indirizzo email dell'agente di servizio.

3. Utilizza cURL per chiamare l'API JSON con una richiesta 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"

   Dove:

   • JSON_FILE_NAME è il percorso del file che hai creato nel passaggio 2.
   • OAUTH2_TOKEN è il token di accesso che generate nel passaggio 1.
   • BUCKET_NAME è il nome del bucket a cui vuoi concedere l'accesso principale. Ad esempio, my-bucket.