Configurar o acesso a uma origem: Cloud Storage

O Serviço de transferência do Cloud Storage usa uma conta de serviço gerenciada pelo Google, conhecida como agente de serviço, para mover dados de um bucket de origem do Cloud Storage. Essa conta de serviço é criada na primeira vez que você chama googleServiceAccounts.get.

O bucket de origem não precisa pertencer ao mesmo projeto que o agente de serviço. As etapas são as mesmas, independentemente do projeto em que o bucket está.

Permissões do usuário

Para conceder as permissões necessárias ao agente de serviço, você precisa ter as permissões relevantes no bucket de origem:

storage.buckets.getIamPolicy
storage.buckets.setIamPolicy

Os papéis Proprietário do bucket legado do Storage (roles/storage.legacyBucketOwner) ou Administrador do Storage (roles/storage.admin) fornecem as permissões necessárias.

Como conceder permissões automaticamente no Console do Google Cloud

Se você estiver usando o Console do Google Cloud para criar sua transferência e tiver as permissões listadas em Permissões do usuário, o agente de serviço receberá automaticamente as permissões necessárias na sua bucket de origem.

É possível pular as etapas desta página e ir diretamente para Como criar uma transferência.

Permissões necessárias

A conta de serviço precisa ter as seguintes permissões para o bucket de origem:

Permissão	Descrição
`storage.buckets.get`	Permite a localização do bucket pelo agente de serviço.
`storage.objects.list`	Permite a listagem dos objetos no bucket pelo agente de serviço.
`storage.objects.get`	Permite a leitura dos objetos no bucket pelo agente de serviço.
`storage.objects.create`	Permite que o agente de serviço crie objetos no bucket. Obrigatório se a transferência for para um sistema de arquivos. O Serviço de transferência do Cloud Storage cria e preenche duas pastas no bucket de origem: `cloud-ingest/` contém informações do sistema de arquivos e `storage-transfer/` contém registros de transferência.
`storage.objects.delete`	Permite a exclusão de objetos no bucket pelo agente de serviço. Obrigatório se você definir `deleteObjectsFromSourceAfterTransfer` como `true`.

Os papéis predefinidos a seguir concedem as permissões necessárias:

Uma destas:
- Leitor de objetos do Storage (roles/storage.objectViewer) se a transferência for para outro bucket do Cloud Storage.
- Criador de objeto do Storage (roles/storage.objectCreator) se a transferência for para um sistema de arquivos.
Mais um dentre:
- Gravador de bucket legado do Storage (roles/storage.legacyBucketWriter) se a permissão de exclusão de objetos for necessária.
- Leitor de bucket legado do Storage (roles/storage.legacyBucketReader) se a permissão de exclusão de objetos não for necessária.

Qualquer papel do Cloud Storage marcado como um papel legacy só pode ser concedido no nível do bucket.

Para uma lista completa dos papéis do Cloud Storage e das respectivas permissões, consulte papéis do IAM.

Para ACLs de objeto quando ACL_PRESERVE é definido, o papel Proprietário de objeto legado do Storage (roles/storage.legacyObjectOwner) também é obrigatório para o objeto de origem. Para ACL_PRESERVE, adicione manualmente a conta de serviço para ter o papel Proprietário do objeto legado do Storage para dar permissão ao objeto de origem storage.objects.getIamPolicy.

Conceder as permissões necessárias

Para conceder as permissões necessárias ao agente de serviço, siga as etapas abaixo.

Encontre o e-mail do agente de serviço

Acesse a página de referência de googleServiceAccounts.get.

Você verá um painel interativo com o título Testar este método.
No painel, em Parâmetros de solicitação, insira o ID do projeto. O projeto especificado aqui precisa ser o projeto que você está usando para gerenciar o Serviço de transferência do Cloud Storage, que pode ser diferente do projeto do bucket de origem.
Clique em Executar.

O e-mail do agente de serviço é retornado como o valor de accountEmail. Copie esse valor.

O e-mail do agente de serviço tem o formato project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com.

Adicionar o agente de serviço a uma política no nível do bucket

Console

No console do Google Cloud, acesse a página Buckets do Cloud Storage.

Acessar buckets
Clique no menu flutuante bucket () associado ao bucket onde você quer conceder a um membro um papel.
Escolha Editar acesso.
Clique no botão + Adicionar principal.
No campo Novos participantes, insira o e-mail da conta do agente de serviço.
Selecione Storage Object Viewer ou Storage Object Creator no menu suspenso Selecionar um papel.
Clique em Adicionar outro papel.
Selecione Storage Legacy Bucket Writer ou Storage Legacy Bucket Reader.
Clique em Salvar.

gsutil

Use o comando gsutil iam ch:

gsutil iam ch \
serviceAccount:YOUR_AGENT_EMAIL:objectViewer,legacyBucketReader \
gs://BUCKET_NAME

Em que:

YOUR_AGENT_EMAIL é o e-mail da conta de agente que você copiou em Encontrar o e-mail do agente de serviço.
BUCKET_NAME é o nome do bucket ao qual você concede acesso principal. Por exemplo, my-bucket.

Amostras de código

C++

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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 autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.


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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.


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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Ter a CLI gcloud instalada e inicializada para gerar um token de acesso para o cabeçalho Authorization.

Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

Crie um arquivo JSON com as informações a seguir:

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

Em que:

YOUR_AGENT_EMAIL é o e-mail da conta de agente que você copiou em Encontrar o e-mail do agente de serviço.

Use cURL para chamar a API JSON com uma solicitação 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"
```
Em que:
- JSON_FILE_NAME é o caminho para o arquivo criado na Etapa 2.
- OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
- BUCKET_NAME é o nome do bucket ao qual você quer conceder o acesso principal. Por exemplo, my-bucket.