Criar assinaturas do Cloud Storage

Neste documento, descrevemos como criar uma assinatura do Cloud Storage. É possível usar o console do Google Cloud, a Google Cloud CLI, a biblioteca de cliente ou a API Pub/Sub para criar uma assinatura do Cloud Storage.

Antes de começar

Antes de ler este documento, certifique-se de que você conheça o seguinte:

• Como funciona uma assinatura do Cloud Storage.
• Como o Cloud Storage funciona e como criar e gerenciar buckets do Cloud Storage.
• Como configurar um tópico de mensagens inativas para lidar com falhas de mensagens.

Papéis e permissões necessárias

Veja a seguir uma lista de diretrizes sobre papéis e permissões:

• Para criar uma assinatura, configure o controle de acesso no nível do projeto.

• Você também precisa de permissões no nível do recurso se as assinaturas e os tópicos estiverem em projetos diferentes, conforme discutido mais adiante nesta seção.

• Para criar uma assinatura do Cloud Storage, a conta de serviço do Pub/Sub precisa ter permissão para gravar no bucket específico do Cloud Storage e ler os metadados dele. Para mais informações sobre como conceder essas permissões, consulte a próxima seção deste documento.

Para ter as permissões necessárias para criar assinaturas do Cloud Storage, peça ao administrador que conceda a você o papel do IAM Editor do Pub/Sub (roles/pubsub.editor) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Este papel predefinido contém as permissões necessárias para criar assinaturas do Cloud Storage. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar assinaturas do Cloud Storage:

• Criar uma assinatura: pubsub.subscriptions.create
• Anexar uma assinatura a um tópico: pubsub.topics.attachSubscription
• Extrair de uma assinatura: pubsub.subscriptions.consume
• Fazer uma assinatura: pubsub.subscriptions.get
• Listar uma assinatura: pubsub.subscriptions.list
• Atualizar uma assinatura: pubsub.subscriptions.update
• Excluir uma assinatura: pubsub.subscriptions.delete
• Consiga a política do IAM para uma assinatura: pubsub.subscriptions.getIamPolicy
• Configure a política do IAM para uma assinatura: pubsub.subscriptions.setIamPolicy

Talvez você também consiga receber essas permissões com papéis personalizados ou outros papéis predefinidos.

Se você precisar criar assinaturas do Cloud Storage em um projeto que estão associadas a um tópico em outro projeto, peça ao administrador do tópico para conceder a você também o papel do IAM (roles/pubsub.editor) de Editor do Pub/Sub.

Atribuir papéis do Cloud Storage à conta de serviço do Pub/Sub

Alguns serviços do Google Cloud têm contas de serviço gerenciado pelo Google Cloud que permitem que os serviços acessem seus recursos. Essas contas de serviço são conhecidas como agentes de serviços. O Pub/Sub cria e mantém uma conta de serviço para cada projeto no formato [e-mail].

Para criar uma assinatura do Cloud Storage, a conta de serviço do Pub/Sub precisa ter permissão para gravar no bucket específico do Cloud Storage e ler os metadados dele. Escolha um dos seguintes procedimentos:

• Conceda permissões no nível do bucket. No bucket específico do Cloud Storage, conceda o papel Criador de objetos do Storage (roles/storage.objectCreator) e o papel Leitor de bucket legado do Storage (roles/storage.legacyBucketReader) à conta de serviço do Pub/Sub.

• Se você precisar conceder papéis no nível do projeto, atribua o papel de Administrador do Storage (roles/storage.admin) no projeto que contém o bucket do Cloud Storage. Conceda esse papel à conta de serviço do Pub/Sub.

Permissões de bucket

Siga as etapas a seguir para conceder os papéis Criador de objetos do Storage (roles/storage.objectCreator) e Leitor de bucket legado do Storage (roles/storage.legacyBucketReader) no nível do bucket:

1. No Console do Google Cloud, acesse a página Cloud Storage.

   Acesse o Cloud Storage

2. Clique no bucket do Cloud Storage em que você quer gravar mensagens.

   A página Detalhes do bucket é aberta.

3. Na página Detalhes do bucket, clique na guia Permissões.

4. Na guia Permissões > Visualizar por principais, clique em Conceder acesso.

   A página Conceder acesso é aberta.

5. Na seção Adicionar principais, insira o nome da sua conta de serviço do Pub/Sub.

   O formato da conta de serviço é [e-mail]. Por exemplo, em um projeto com PROJECT_NUMBER=112233445566, a conta de serviço tem o formato [e-mail].

6. No menu suspenso Atribuir papéis > Selecionar um papel, insira Creator e selecione o papel Criador de objetos do Storage.

7. Clique em Adicionar outro papel.

8. No menu suspenso Selecionar um papel, digite Bucket Reader e selecione o papel Leitor de bucket legado do Storage.

9. Clique em Salvar.

Permissões do projeto

Siga as etapas a seguir para conceder o papel de Administrador do Storage (roles/storage.admin) no nível do projeto:

1. No console do Google Cloud, abra a página IAM.

   Acessar IAM

2. Na guia Permissões > Visualizar por principais, clique em Conceder acesso.

   A página Conceder acesso é aberta.

3. Na seção Adicionar principais, insira o nome da sua conta de serviço do Pub/Sub.

   O formato da conta de serviço é [e-mail]. Por exemplo, em um projeto com PROJECT_NUMBER=112233445566, a conta de serviço tem o formato [e-mail].

4. No menu suspenso Atribuir papéis > Selecionar um papel, insira Storage Admin e selecione o papel Administrador do Storage.

5. Clique em Salvar.

Para mais informações sobre o IAM do Cloud Storage, consulte Identity and Access Management do Cloud Storage.

Propriedades da assinatura do Cloud Storage

Ao configurar uma assinatura do Cloud Storage, é preciso especificar as propriedades comuns a todos os tipos de assinatura e algumas outras propriedades específicas da assinatura do Cloud Storage.

Propriedades de assinatura comuns

Saiba mais sobre as propriedades de assinatura comuns que podem ser definidas em todas as assinaturas.

Nome do bucket

É preciso que um bucket do Cloud Storage já exista antes de você criar uma assinatura do Cloud Storage.

As mensagens são enviadas em lotes e armazenadas no bucket do Cloud Storage. Um único lote ou arquivo é armazenado como um objeto no bucket.

O bucket do Cloud Storage precisa ter a opção Pagamentos do solicitante desativada.

Para criar um bucket do Cloud Storage, consulte Criar buckets.

Prefixo, sufixo e data/hora do nome de arquivo

Os arquivos de saída do Cloud Storage gerados pela assinatura do Cloud Storage são armazenados como objetos no bucket do Cloud Storage. O nome do objeto armazenado no bucket do Cloud Storage tem o seguinte formato: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

A lista a seguir inclui detalhes do formato do arquivo e os campos que podem ser personalizados:

• <file-prefix> é o prefixo de nome de arquivo personalizado; Esse campo é opcional.

• <UTC-date-time> é uma string personalizável gerada automaticamente com base no horário em que o objeto é criado.

• <uuid> é uma string aleatória gerada automaticamente para o objeto.

• <file-suffix> é o sufixo do nome de arquivo personalizado. Esse campo é opcional. O sufixo do nome do arquivo não pode terminar em "/".

• É possível alterar o prefixo e o sufixo do nome do arquivo:

  • Por exemplo, se o valor do prefixo do nome de arquivo for prod_ e o valor do sufixo do nome de arquivo for _archive, um exemplo de nome de objeto será prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

  • Se você não especificar o prefixo e o sufixo do nome de arquivo, o nome do objeto armazenado no bucket do Cloud Storage terá o formato: <UTC-date-time>_<uuid>.

  • Os requisitos de nomenclatura de objetos do Cloud Storage também se aplicam ao prefixo e ao sufixo do nome do arquivo. Para mais informações, consulte Sobre os objetos do Cloud Storage.

• Você pode alterar como a data e a hora são exibidas no nome do arquivo:

  • Correspondências de data e hora obrigatórias que podem ser usadas apenas uma vez: ano (YYYY ou YY), mês (MM), dia (DD), hora (hh), minuto (mm) e segundo (ss). Por exemplo, YY-YYYY ou MMM são inválidos.

  • Correspondências opcionais que podem ser usadas apenas uma vez: separador de data e hora (T) e compensação de fuso horário (Z ou +00:00).

  • Elementos opcionais que você pode usar várias vezes: hífen (-), sublinhado (_), dois-pontos (:) e barra (/).

  • Por exemplo, se o valor do formato de data e hora do nome de arquivo for YYYY-MM-DD/hh_mm_ssZ, um exemplo de nome de objeto será prod_2023-09-25/04_10_00Z_uNiQuE_archive.

  • Se o formato de data e hora do nome do arquivo terminar em um caractere que não seja um correspondente, esse caractere vai substituir o separador entre <UTC-date-time> e <uuid>. Por exemplo, se o valor do formato de data e hora do nome de arquivo for YYYY-MM-DDThh_mm_ss-, um exemplo de nome de objeto será prod_2023-09-25T04_10_00-uNiQuE_archive.

Enviar arquivos em lote

Com as assinaturas do Cloud Storage, você decide quando quer criar um novo arquivo de saída armazenado como um objeto no bucket do Cloud Storage. O Pub/Sub grava um arquivo de saída quando uma das condições de lote especificadas é atendida. Veja a seguir as condições de lote do Cloud Storage:

• Duração máxima do lote de armazenamento. Essa configuração é obrigatória. A assinatura do Cloud Storage gravará um novo arquivo de saída se o valor especificado de duração máxima for excedido. Se você não especificar o valor, será aplicado um valor padrão de 5 minutos. Veja a seguir os valores aplicáveis para duração máxima:

  • Valor mínimo = 1 minuto
  • Valor padrão = 5 minutos
  • Valor máximo = 10 minutos

• Bytes máximos de lote de armazenamento. Essa configuração é opcional. A assinatura do Cloud Storage gravará um novo arquivo de saída se o valor especificado de máximo de bytes for excedido. Veja a seguir os valores aplicáveis ao máximo de bytes:

  • Valor mínimo = 1 KB
  • Valor máximo = 10 GiB

Por exemplo, é possível configurar a duração máxima como 6 minutos e o máximo de bytes como 2 GB. Se, no quarto minuto, o arquivo de saída atingir 2 GB, o Pub/Sub finalizará o arquivo anterior e começará a gravar em um novo.

Uma assinatura do Cloud Storage pode gravar simultaneamente vários arquivos em um bucket do Cloud Storage. Se você configurou sua assinatura para criar um novo arquivo a cada seis minutos, poderá observar vários arquivos do Cloud Storage sendo criados a cada seis minutos.

Em algumas situações, o Pub/Sub pode começar a gravar em um novo arquivo antes do tempo configurado pelas condições de lote do arquivo. Um arquivo também pode exceder o valor máximo de bytes se a assinatura receber mensagens maiores que esse valor.

Formato do arquivo

Ao criar uma assinatura do Cloud Storage, é possível especificar o formato dos arquivos de saída que serão armazenados em um bucket do Cloud Storage como Text ou Avro.

• Texto: as mensagens são armazenadas como texto simples. Um caractere de nova linha separa uma mensagem da mensagem anterior no arquivo. Somente payloads de mensagens são armazenados, não atributos ou outros metadados.

• Avro: as mensagens são armazenadas no formato binário Apache Avro.

  Quando você seleciona Avro, também é possível ativar a opção write metadata. Esta opção permite armazenar os metadados da mensagem com a mensagem.

  Metadados como subscription_name, message_id, publish_time e campos de atributos são gravados em campos de nível superior no objeto Avro de saída, enquanto todas as outras propriedades da mensagem, exceto dados (por exemplo, uma chave_de_ordenação, se presente) são adicionadas como entradas no mapa de atributos.

  Se a opção de gravação de metadados estiver desativada, somente o payload da mensagem será gravado no objeto Avro de saída.

  Este é o esquema Avro das mensagens de saída sem metadados de gravação ativados:

  {
    "type": "record",
    "namespace": "com.google.pubsub",
    "name": "PubsubMessage",
    "fields": [
      { "name": "data", "type": "bytes" }
    ]
  }
  

  Este é o esquema Avro das mensagens de saída com metadados de gravação ativados:

  {
    "type": "record",
    "namespace": "com.google.pubsub",
    "name": "PubsubMessageWithMetadata",
    "fields": [
      { "name": "subscription_name", "type": "string" },
      { "name": "message_id", "type": "string"  },
      { "name": "publish_time", "type": {
          "type": "long",
          "logicalType": "timestamp-micros"
        }
      },
      { "name": "attributes", "type": { "type": "map", "values": "string" } },
      { "name": "data", "type": "bytes" }
    ]
  }
  

Criar uma assinatura do Cloud Storage

Console

1. No console do Google Cloud, acesse a página Assinaturas.

   Acessar "Assinaturas"

2. Clique em Criar assinatura.

3. No campo ID da assinatura, digite um nome.

   Para saber como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.

4. Escolha ou crie um tópico no menu suspenso.

   A assinatura recebe mensagens do tópico.

   Para mais informações sobre como criar um tópico, consulte Criar e gerenciar tópicos.

5. Selecione Tipo de entrega como Gravar no Cloud Storage.

6. No bucket do Cloud Storage, clique em Procurar.

   • É possível selecionar um bucket atual de qualquer projeto apropriado.

   • Também é possível clicar no ícone de criação e seguir as instruções na tela para criar um novo bucket.

     Depois de criar o bucket, selecione-o para a assinatura do Cloud Storage.

     Para mais informações sobre como criar um bucket, consulte Criar buckets.

   Quando você especifica o bucket, o Pub/Sub verifica as permissões apropriadas no bucket para a conta de serviço do Pub/Sub. Se houver problemas de permissão, você verá uma mensagem semelhante a esta: Unable to verify if the Pub/Sub service agent has write permissions on this bucket. You may be lacking permissions to view or set permissions.

7. Se você tiver problemas de permissão, clique em Definir permissão e siga as instruções na tela.

   Como alternativa, siga as instruções em Atribuir papéis do Cloud Storage à conta de serviço do Pub/Sub.

8. Em Formato de arquivo, selecione Texto ou Avro.

   Se você selecionar Avro, também poderá especificar se quer armazenar os metadados da mensagem na saída.

   Para mais informações sobre as duas opções, incluindo a opção de metadados de mensagens para o formato Avro, consulte Formato de arquivo.

9. Opcional: é possível especificar o prefixo e o sufixo do nome do arquivo para todos os arquivos que serão gravados no bucket do Cloud Storage. Um arquivo é armazenado como um objeto no bucket.

   Para mais informações sobre como definir o prefixo e o sufixo do arquivo, consulte Prefixo e sufixo do arquivo.

10. Em Enviar em lote de arquivos, especifique um tempo máximo decorrido antes de criar um novo arquivo.

    Também é possível definir o tamanho máximo dos arquivos.

    Para mais informações sobre as duas opções de lotes de arquivos, consulte Lotes de arquivos.

11. É altamente recomendável ativar Mensagens inativas para lidar com falhas de mensagens.

    Para mais informações, consulte Tópico de mensagens inativas.

12. Mantenha as outras configurações como padrão e clique em Criar.

gcloud

1. No Console do Google Cloud, ative o Cloud Shell.

   Ativar o Cloud Shell

   Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

2. Para criar uma assinatura do Cloud Storage, execute o comando gcloud pubsub subscriptions create.

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --cloud-storage-bucket=BUCKET_NAME \
       --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \
       --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \
       --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \
       --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \
       --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \
       --cloud-storage-write-metadata

   No comando, apenas SUBSCRIPTION_ID e as sinalizações --topic e --cloud-storage-bucket são obrigatórias. As outras sinalizações são opcionais e podem ser omitidas.

   Substitua:

   • SUBSCRIPTION_ID: o nome ou ID da nova assinatura do Cloud Storage.
   • TOPIC_ID: o nome ou ID do tópico.
   • BUCKET_NAME: especifica o nome de um bucket atual. Por exemplo, prod_bucket. O nome do bucket não pode incluir o ID do projeto. Para criar um bucket, consulte Criar buckets.
   • CLOUD_STORAGE_FILE_PREFIX: especifica o prefixo do nome de arquivo do Cloud Storage. Por exemplo, log_events_.
   • CLOUD_STORAGE_FILE_SUFFIX: especifica o sufixo do nome do arquivo do Cloud Storage. Por exemplo, .txt.
   • CLOUD_STORAGE_MAX_BYTES: o máximo de bytes que podem ser gravados em um arquivo do Cloud Storage antes da criação de um novo arquivo. O valor precisa estar entre 1 KB e 10 GB. Por exemplo, 20MB.
   • CLOUD_STORAGE_MAX_DURATION: a duração máxima que pode decorrer antes que um novo arquivo do Cloud Storage seja criado. O valor precisa estar entre 1 m e 10 m. Por exemplo, 5m.
   • CLOUD_STORAGE_OUTPUT_FORMAT: o formato de saída dos dados gravados no Cloud Storage. Os valores são os seguintes:
     • text: as mensagens são escritas como texto bruto, separadas por uma nova linha.
     • avro: as mensagens são escritas como um binário Avro. --cloud-storage-write-metadata tem efeito apenas para assinaturas com formato de saída avro.

C++

Antes de testar esta amostra, siga as instruções de configuração de C++ no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.

Para se autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& bucket) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_cloud_storage_config()->set_bucket(bucket);
  auto sub = client.CreateSubscription(request);
  if (!sub) {
    if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The subscription already exists\n";
      return;
    }
    throw std::move(sub).status();
  }

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

Go

Antes de testar esta amostra, siga as instruções de configuração de Go no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.

Para se autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub"
)

// createCloudStorageSubscription creates a Pub/Sub subscription that exports messages to Cloud Storage.
func createCloudStorageSubscription(w io.Writer, projectID, subID string, topic *pubsub.Topic, bucket string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// note bucket should not have the gs:// prefix
	// bucket := "my-bucket"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic: topic,
		CloudStorageConfig: pubsub.CloudStorageConfig{
			Bucket:         bucket,
			FilenamePrefix: "log_events_",
			FilenameSuffix: ".avro",
			OutputFormat:   &pubsub.CloudStorageOutputFormatAvroConfig{WriteMetadata: true},
			MaxDuration:    1 * time.Minute,
			MaxBytes:       1e8,
		},
	})
	if err != nil {
		return fmt.Errorf("client.CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created Cloud Storage subscription: %v\n", sub)

	return nil
}

Java

Antes de testar esta amostra, siga as instruções de configuração de Java no Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.

Para se autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.protobuf.Duration;
import com.google.pubsub.v1.CloudStorageConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateCloudStorageSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String bucket = "your-bucket";
    String filenamePrefix = "log_events_";
    String filenameSuffix = ".text";
    Duration maxDuration = Duration.newBuilder().setSeconds(300).build();

    createCloudStorageSubscription(
        projectId, topicId, subscriptionId, bucket, filenamePrefix, filenameSuffix, maxDuration);
  }

  public static void createCloudStorageSubscription(
      String projectId,
      String topicId,
      String subscriptionId,
      String bucket,
      String filenamePrefix,
      String filenameSuffix,
      Duration maxDuration)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      CloudStorageConfig cloudStorageConfig =
          CloudStorageConfig.newBuilder()
              .setBucket(bucket)
              .setFilenamePrefix(filenamePrefix)
              .setFilenameSuffix(filenameSuffix)
              .setMaxDuration(maxDuration)
              .build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setCloudStorageConfig(cloudStorageConfig)
                  .build());

      System.out.println("Created a CloudStorage subscription: " + subscription.getAllFields());
    }
  }
}

Monitorar assinaturas

O Cloud Monitoring oferece várias métricas para monitorar assinaturas.

Também é possível monitorar as assinaturas no Pub/Sub.

A seguir

• Resolva problemas com uma assinatura do Cloud Storage.

• Leia sobre o Cloud Storage.

• Revise os preços do Pub/Sub, incluindo a assinatura do Cloud Storage.