Configure o acesso a uma origem: Cloud Storage

O Storage Transfer Service usa uma conta de serviço gerida pela Google, conhecida como agente de serviço, para mover dados de um contentor de origem do Cloud Storage. Este agente de serviço é criado na primeira vez que chama o número googleServiceAccounts.get.

O contentor de origem não tem de pertencer ao mesmo projeto que o agente do serviço. Os passos são os mesmos, independentemente do projeto em que o contentor se encontra.

Autorizações do utilizador

Para conceder as autorizações necessárias ao agente de serviço, tem de ter as autorizações relevantes no contentor de origem:

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

A função Proprietário de contentores antigos do Storage (roles/storage.legacyBucketOwner) ou a função Administrador do Storage (roles/storage.admin) concedem as autorizações necessárias.

Concessão automática de autorizações na Google Cloud consola

Se estiver a usar a consola para criar a transferência e tiver as autorizações indicadas em Autorizações do utilizador, o agente de serviço recebe automaticamente as autorizações necessárias no seu contentor de origem. Google Cloud

Pode ignorar os passos desta página e aceder diretamente à criação de uma transferência.

Autorizações necessárias

O agente de serviço tem de ter as seguintes autorizações para o contentor de origem:

Autorização	Descrição
storage.buckets.get	Permite que o agente de serviço obtenha a localização do contentor.
storage.objects.list	Permite que o agente de serviço liste objetos no contentor.
storage.objects.get	Permite que o agente de serviço leia objetos no contentor.
storage.objects.create	Permite que o agente de serviço crie objetos no contentor. Obrigatório se a transferência for para um sistema de ficheiros. O serviço de transferência de armazenamento cria e preenche duas pastas no contentor de origem: cloud-ingest/ contém informações do sistema de ficheiros e storage-transfer/ contém registos de transferência.
storage.objects.delete	Permite que o agente de serviço elimine objetos no contentor. Obrigatório se definir deleteObjectsFromSourceAfterTransfer como true.

As seguintes funções predefinidas concedem em conjunto as autorizações necessárias:

• Uma das seguintes opções:
  • Storage Object Viewer (roles/storage.objectViewer) se a transferência for para outro contentor do Cloud Storage.
  • Storage Object Creator (roles/storage.objectCreator) se a transferência for para um sistema de ficheiros.
• Além de uma das seguintes opções:
  • Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter) se for necessária a autorização para eliminar objetos.
  • Leitor de buckets antigos do Storage (roles/storage.legacyBucketReader) se não for necessária a autorização de eliminação de objetos.

Qualquer função do Cloud Storage marcada como função legacy só pode ser concedida ao nível do contentor.

Para ver uma lista completa das funções do Cloud Storage e das autorizações que contêm, consulte Funções de IAM.

Para LCAs de objetos quando ACL_PRESERVE está definido, a função Proprietário de objetos antigos do Storage (roles/storage.legacyObjectOwner) também é necessária para o objeto de origem. Para ACL_PRESERVE, adicione manualmente a conta de serviço para ter a função Proprietário de objetos antigos do Storage para conceder autorização storage.objects.getIamPolicy ao objeto de origem.

Conceda as autorizações necessárias

Para conceder as autorizações necessárias ao agente de serviço, siga os passos abaixo.

Encontre o email do agente de serviço

1. Aceda à página de referência googleServiceAccounts.get.

   É aberto um painel interativo com o título Experimente este método.

2. No painel, em Parâmetros do pedido, introduza o seu ID do projeto. O projeto que especificar aqui tem de ser o projeto que está a usar para gerir o serviço de transferência de armazenamento, que pode ser diferente do projeto do contentor de origem.

3. Clique em Executar.

   O email do agente de serviço é devolvido como o valor de accountEmail. Copiar este valor.

   O email do agente de serviço usa o formato [e-mail].

Adicione o agente do serviço a uma política ao nível do contentor

Consola

1. Na Google Cloud consola, aceda à página Recipientes do Cloud Storage.
   

   Aceda a Recipientes

2. Clique no menu Mais opções do contentor () associado ao contentor ao qual quer conceder uma função a um principal.

3. Escolha Editar acesso.

4. Clique no botão + Adicionar principal.

5. No campo Novos membros, introduza o email da conta do seu agente de serviço.

6. Selecione Storage Object Viewer ou Storage Object Creator no menu pendente Selecionar uma função.

7. Clique em Adicionar outra função.

8. Selecione Storage Legacy Bucket Writer ou Storage Legacy Bucket Reader.

9. Clique em Guardar.

gcloud

Use o 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

Onde:

• BUCKET_NAME é o nome do contentor ao qual está a conceder acesso ao principal. Por exemplo, my-bucket.
• YOUR_AGENT_EMAIL é o email da conta de agente que copiou em Encontre o email do agente de serviço.

Exemplos de código

C++

Para saber como instalar e usar a biblioteca cliente do Cloud Storage, consulte as bibliotecas cliente do Cloud Storage. Para mais informações, consulte a documentação de referência da API C++ do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 saber como instalar e usar a biblioteca cliente do Cloud Storage, consulte as bibliotecas cliente do Cloud Storage. Para mais informações, consulte a documentação de referência da API C# do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 saber como instalar e usar a biblioteca cliente do Cloud Storage, consulte as bibliotecas cliente do Cloud Storage. Para mais informações, consulte a documentação de referência da API Go do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 saber como instalar e usar a biblioteca cliente do Cloud Storage, consulte as bibliotecas cliente do Cloud Storage. Para mais informações, consulte a documentação de referência da API Java do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 saber como instalar e usar a biblioteca cliente do Cloud Storage, consulte as bibliotecas cliente do Cloud Storage. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 saber como instalar e usar a biblioteca cliente do Cloud Storage, consulte as bibliotecas cliente do Cloud Storage. Para mais informações, consulte a documentação de referência da API PHP do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 saber como instalar e usar a biblioteca cliente do Cloud Storage, consulte as bibliotecas cliente do Cloud Storage. Para mais informações, consulte a documentação de referência da API Python do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 saber como instalar e usar a biblioteca cliente do Cloud Storage, consulte as bibliotecas cliente do Cloud Storage. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 substitui qualquer política de IAM existente definida num contentor. Se quiser modificar a política existente, obtenha-a com o método getIamPolicy, edite-a conforme necessário e use a versão editada no seu pedido setIamPolicy.

1. Ter a CLI gcloud instalada e inicializada, o que lhe permite gerar um token de acesso para o cabeçalho Authorization.

2. Crie um ficheiro JSON que contenha as seguintes informações:

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

   Onde:

   • YOUR_AGENT_EMAIL é o email da conta de agente que copiou em Encontre o email do agente de serviço.

3. Use cURL para chamar a API JSON com um pedido 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"

   Onde:

   • JSON_FILE_NAME é o caminho do ficheiro que criou no passo 2.
   • OAUTH2_TOKEN é o token de acesso que gerou no Passo 1.
   • BUCKET_NAME é o nome do contentor ao qual quer conceder acesso ao principal. Por exemplo, my-bucket.