Configura el acceso a una fuente: Cloud Storage

El Servicio de transferencia de almacenamiento usa una cuenta de servicio administrada por Google, conocida como un agente de servicio, para mover datos desde un bucket de Cloud Storage de origen. Este agente de servicio se crea la primera vez que llamas a googleServiceAccounts.get.

No es necesario que el bucket de origen pertenezca al mismo proyecto que el agente de servicio. Los pasos son los mismos sin importar el proyecto en el que se encuentre el bucket.

Permisos de usuario

Para otorgar los permisos necesarios al agente de servicio, debes tener los permisos relevantes en el bucket de origen:

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

Los roles Storage Legacy Bucket Owner (roles/storage.legacyBucketOwner) o Storage Admin (roles/storage.admin) otorgan los permisos necesarios.

Otorga permisos automáticamente en la consola de Google Cloud

Si usas la consola de Google Cloud para crear tu transferencia y tienes los permisos enumerados en Permisos de usuario, el agente de servicio recibirá automáticamente los permisos necesarios en tu bucket de origen.

Puedes omitir los pasos en esta página y dirigirte directamente a Crea una transferencia.

Permisos necesarios

El agente de servicio debe tener los siguientes permisos para acceder al bucket de origen:

Permiso	Descripción
storage.buckets.get	Permite que el agente de servicio obtenga la ubicación del bucket.
storage.objects.list	Permite que el agente de servicio enumere los objetos en el bucket.
storage.objects.get	Permite que la cuenta de servicio lea los objetos en el bucket.
storage.objects.create	Permite que el agente de servicio cree objetos en el bucket. Obligatorio si la transferencia es a un sistema de archivos. El Servicio de transferencia de almacenamiento crea y propaga dos carpetas en el bucket de origen: cloud-ingest/ contiene información del sistema de archivos y storage-transfer/ contiene registros de transferencia.
storage.objects.delete	Permite que el agente de servicio borre objetos en el bucket. Se requiere si establece deleteObjectsFromSourceAfterTransfer en true.

Los siguientes roles predefinidos otorgan los permisos necesarios:

• Uno de los siguientes:
  • Storage Object Viewer (roles/storage.objectViewer) si la transferencia se realiza en otro bucket de Cloud Storage.
  • Storage Object Creator (roles/storage.objectCreator) si la transferencia es a un sistema de archivos.
• Más uno de los siguientes:
  • Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter) si se requiere permiso para eliminar objetos.
  • Storage Legacy Bucket Reader (roles/storage.legacyBucketReader) si no se requiere permiso para borrar objetos.

Cualquier rol de Cloud Storage marcada como rol legacy solo se puede otorgar a nivel de bucket.

Para obtener una lista completa de las funciones de Cloud Storage y los permisos que contienen, consulta las funciones de IAM.

Para las LCA de objetos cuando se establece ACL_PRESERVE, el rol de propietario de objetos heredados de almacenamiento (roles/storage.legacyObjectOwner) también es obligatorio para el objeto de origen. Para ACL_PRESERVE, agrega manualmente la cuenta de servicio para que tenga el rol de Propietario de objetos heredados de Storage para otorgarle al objeto de origen el permiso storage.objects.getIamPolicy.

Otorga los permisos necesarios.

Para otorgar los permisos necesarios al agente de servicio, sigue los pasos que se indican a continuación.

Busca el correo electrónico del agente de servicio

1. Ve a la página de referencia de googleServiceAccounts.get.

   Se abrirá un panel interactivo con el título Prueba este método.

2. En el panel, en Parámetros de solicitud, ingresa el ID del proyecto. El proyecto que especifiques aquí debe ser el proyecto que usas para administrar el Servicio de transferencia de almacenamiento, que puede ser diferente del proyecto del bucket de origen.

3. Haz clic en Ejecutar.

   El correo electrónico del agente de servicio se muestra como el valor de accountEmail. Copia este valor.

   El correo electrónico del agente de servicio usa el formato [e-mail].

Agrega el agente de servicio a una política a nivel de bucket

Console

1. En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.
   

   Ir a Buckets

2. Haz clic en el menú Ampliado del bucket () asociado al bucket en el que deseas asignarle un rol a una principal.

3. Elige Editar acceso.

4. Haz clic en el botón + Agregar principal.

5. En el campo Principales nuevas, ingresa el correo electrónico de la cuenta de tu agente de servicio.

6. Selecciona Storage Object Viewer o Storage Object Creator en el menú desplegable Selecciona un rol.

7. Haz clic en Agregar otra función.

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

9. Haz clic en Guardar.

gcloud

Usa el 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

Aquí:

• BUCKET_NAME es el nombre del bucket al cual le otorgas acceso principal. Por ejemplo, my-bucket
• YOUR_AGENT_EMAIL es el correo electrónico de la cuenta del agente que copiaste en Encuentra el correo electrónico del agente de servicio.

Muestras de código

C++

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Storage, consulta Bibliotecas cliente de Cloud Storage. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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#

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Storage, consulta Bibliotecas cliente de Cloud Storage. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Storage, consulta Bibliotecas cliente de Cloud Storage. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Go.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Storage, consulta Bibliotecas cliente de Cloud Storage. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Storage, consulta Bibliotecas cliente de Cloud Storage. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Storage, consulta Bibliotecas cliente de Cloud Storage. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Storage, consulta Bibliotecas cliente de Cloud Storage. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Storage, consulta Bibliotecas cliente de Cloud Storage. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Ruby.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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: Este método reemplaza cualquier política de IAM existente configurada en un bucket. Si deseas modificar la política existente, recupérala con el método getIamPolicy, edítala según sea necesario y usa la versión editada de tu solicitud setIamPolicy.

1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization.

2. Crea un archivo JSON que contenga la siguiente información:

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

   Aquí:

   • YOUR_AGENT_EMAIL es el correo electrónico de la cuenta del agente que copiaste en Encuentra el correo electrónico del agente de servicio.

3. Usa cURL para llamar a la API de JSON con una solicitud 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"

   Aquí:

   • JSON_FILE_NAME es la ruta de acceso del archivo que creaste en el paso 2.
   • OAUTH2_TOKEN es el token de acceso que generaste en el paso 1.
   • BUCKET_NAME es el nombre del bucket al que le quieres otorgar acceso al principal. Por ejemplo, my-bucket