Configurare l'accesso a un sink: Cloud Storage

Cloud Storage utilizza un service agent per spostare i dati in un bucket Cloud Storage. Questo service agent viene creato la prima volta che chiami googleServiceAccounts.get.

Il bucket di destinazione non deve necessariamente appartenere allo stesso progetto del service agent. I passaggi sono gli stessi indipendentemente dal progetto in cui si trova il bucket.

Autorizzazioni utente

Per concedere le autorizzazioni richieste al service agent, devi disporre delle autorizzazioni pertinenti per il bucket di destinazione:

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

Il ruolo Storage Legacy Bucket Owner (roles/storage.legacyBucketOwner) o il ruolo Amministratore spazio di archiviazione (roles/storage.admin) forniscono le autorizzazioni richieste.

Concessione automatica delle autorizzazioni nella Google Cloud console

Se utilizzi la Google Cloud console per creare il trasferimento e disponi delle autorizzazioni elencate in Autorizzazioni utente, al service agent verranno concesse automaticamente le autorizzazioni richieste per il bucket di destinazione.

Puoi saltare i passaggi descritti in questa pagina. Se necessario, configura l'accesso all'origine, quindi crea un trasferimento.

Autorizzazioni obbligatorie

Il service agent deve disporre delle seguenti autorizzazioni per il bucket di destinazione:

Autorizzazione	Descrizione
storage.buckets.get	Consente al account di servizio di ottenere la località del bucket.
storage.objects.get	Consente al account di servizio di visualizzare gli oggetti e i relativi metadati, esclusi gli ACL. Obbligatorio se il trasferimento è configurato per [sovrascrivere gli oggetti](/storage-transfer/docs/reference/rest/v1/TransferOptions#OverwriteWhen) nel sink quando sono diversi o mai. Non è obbligatorio se l'impostazione di trasferimento è di sovrascrivere sempre.
storage.objects.create	Consente al account di servizio di aggiungere oggetti al bucket.
storage.objects.delete	Consente al account di servizio di eliminare gli oggetti nel bucket. Obbligatorio se imposti overwriteObjectsAlreadyExistingInSink o deleteObjectsUniqueInSink su true. Tieni presente che se il bucket di destinazione ha il controllo delle versioni degli oggetti abilitato, né overwriteObjectsAlreadyExistingInSink né deleteObjectsUniqueInSink eliminano definitivamente gli oggetti. Le versioni degli oggetti attivi pertinenti diventano non correnti.
storage.objects.list	Consente al account di servizio di elencare gli oggetti nel bucket. Obbligatorio se imposti overwriteObjectsAlreadyExistingInSink su false o deleteObjectsUniqueInSink su true.

Il seguente ruolo predefinito concede le autorizzazioni richieste:

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

Inoltre, per i trasferimenti configurati per sovrascrivere gli oggetti nel sink quando sono diversi o mai, assegna il seguente ruolo predefinito al service agent:

• Storage Object Viewer (roles/storage.objectViewer)

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

Concedi le autorizzazioni richieste

Per concedere i ruoli Storage Legacy Bucket Writer e Storage Object Viewer al service agent, segui questi passaggi.

Trova l'indirizzo email del service agent

1. Vai alla pagina di riferimento googleServiceAccounts.get.

   Si apre un riquadro interattivo intitolato Prova questo metodo.

2. Nel riquadro, in Parametri della richiesta, inserisci il tuo ID progetto. Il progetto che specifichi qui deve essere il progetto che utilizzi per gestire Storage Transfer Service, che potrebbe essere diverso dal progetto del bucket di destinazione.

3. Fai clic su Esegui.

   L'indirizzo email del service agent viene restituito come valore di accountEmail. Copia questo valore.

   L'indirizzo email del service agent utilizza il formato project-PROJECT_NUMBER@storage-transfer-service..

Aggiungi il service agent a un criterio a livello di bucket

Console

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

   Vai a Bucket

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

3. Scegli accesso in modifica.

4. Fai clic sul pulsante + Aggiungi entità.

5. Nel campo Nuove entità, inserisci l'indirizzo email dell'account del service agent.

6. Seleziona Storage Legacy Bucket Writer dal menu a discesa Seleziona un ruolo.

7. Fai clic su Salva.

8. Ripeti l'operazione per aggiungere il ruolo Storage Object Viewer se il trasferimento è configurato per sovrascrivere gli oggetti nel sink quando sono diversi o mai.

gcloud

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

Sostituisci quanto segue:

• BUCKET_NAME è il nome del bucket a cui stai concedendo l'accesso all'entità. Ad esempio, my-bucket.
• YOUR_AGENT_EMAIL è l'indirizzo email dell'account dell'agente che hai copiato in Trova l'indirizzo email del service agent.

Per concedere il ruolo Storage Object Viewer per le configurazioni di trasferimento configurate per sovrascrivere gli oggetti nel sink quando sono diversi o mai:

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

Esempi di codice

C++

Per scoprire come installare e utilizzare la libreria client per Cloud Storage, consulta Librerie client di Cloud Storage. Per saperne di più, consulta la documentazione di riferimento dell'APIC++ di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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 saperne di più, consulta la documentazione di riferimento dell'C# API di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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 saperne di più, consulta la documentazione di riferimento dell' API Go di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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, consulta Librerie client di Cloud Storage. Per saperne di più, consulta la documentazione di riferimento dell'API Java Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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, consulta Librerie client di Cloud Storage. Per saperne di più, consulta la documentazione di riferimento dell'Node.js API di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

/**
 * 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, consulta Librerie client di Cloud Storage. Per saperne di più, consulta la documentazione di riferimento dell'API PHP Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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 saperne di più, consulta la documentazione di riferimento dell' API Python di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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, consulta Librerie client di Cloud Storage. Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Ruby.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Nota: questo metodo sostituisce qualsiasi policy IAM esistente impostata su un bucket. Se vuoi modificare la policy esistente, recuperala con il getIamPolicy , modificala in base alle esigenze e utilizza la versione modificata nella richiesta setIamPolicy.

1. Assicurati che gcloud CLI sia installato e inizializzato, in modo da poter generare un token di accesso per l'intestazione Authorization.

2. Crea un file JSON contenente le seguenti informazioni:

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

   Sostituisci quanto segue:

   • YOUR_AGENT_EMAIL è l'indirizzo email dell'account dell'agente che hai copiato in Trova l'indirizzo email del service agent.

3. Utilizza cURL per chiamare la API JSON con una PUT setIamPolicy richiesta:

   curl -X PUT --data-binary @JSON_FILE_NAME \
   -H "Authorization: Bearer OAUTH2_TOKEN" \
   -H "Content-Type: application/json" \
   "https://storage./storage/v1/b/BUCKET_NAME/iam"

   Sostituisci quanto segue:

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

Per saperne di più sull'assegnazione dei ruoli IAM alle risorse di Cloud Storage, consulta la documentazione IAM di Cloud Storage.