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, você precisa conhecer bem:

• 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

Confira a seguir uma lista de diretrizes relacionadas a papéis e permissões:

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

• Você também vai precisar de permissões no nível do recurso se suas assinaturas e 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 receber as permissões necessárias para criar assinaturas do Cloud Storage, peça ao administrador para conceder 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.

Esse 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:

Também é possível 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 estejam associadas a um tópico em outro projeto, peça ao administrador do tópico para conceder a você o papel do IAM (roles/pubsub.editor) de editor do Pub/Sub no tópico.

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 são conhecidas como agentes de serviço. O Pub/Sub cria e mantém uma conta de serviço para cada projeto no formato service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.

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 do bucket. Escolha um dos seguintes procedimentos:

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

• Se for necessário conceder papéis no nível do projeto, é possível conceder o papel 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.

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, é necessário especificar as propriedades comuns a todos os tipos de assinatura e algumas outras propriedades específicas da assinatura.

Propriedades comuns de assinaturas

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

Nome do bucket

Um bucket do Cloud Storage precisa existir antes da criação de uma assinatura do Cloud Storage.

As mensagens são enviadas como 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 de criação do objeto.

• <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 de arquivo:

  • Por exemplo, se o valor do prefixo do nome de arquivo for prod_ e o sufixo do nome do arquivo for _archive, um nome de objeto de amostra 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), segundo (ss). Por exemplo, YY-YYYY ou MMM é inválido.

  • 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 podem ser usados várias vezes: hífen (-), sublinhado (_), dois-pontos (:) e barra (/).

  • Por exemplo, se o valor do formato de data e hora do nome do arquivo for YYYY-MM-DD/hh_mm_ssZ, um nome de objeto de amostra 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 é um correspondente, esse caractere substituirá o separador entre <UTC-date-time> e <uuid>. Por exemplo, se o valor do formato de data e hora do nome do arquivo for YYYY-MM-DDThh_mm_ss-, um nome de objeto de amostra será prod_2023-09-25T04_10_00-uNiQuE_archive.

Lote de arquivos

As assinaturas do Cloud Storage permitem decidir quando 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. Estas são 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 da duração máxima for excedido. Se você não especificar o valor, o valor padrão de 5 minutos será aplicado. Veja a seguir os valores aplicáveis para a 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 do máximo de bytes for excedido. Veja a seguir os valores aplicáveis para o 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 4o 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 em vários arquivos em um bucket do Cloud Storage simultaneamente. Se você configurou sua assinatura para criar um novo arquivo a cada 6 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 loteamento de arquivos. Um arquivo também poderá 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, especifique 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. Ao selecionar Avro, você pode ativar as seguintes propriedades adicionais:

  • Gravar metadados: permite armazenar os metadados da mensagem com a mensagem. Metadados, como os campos subscription_name, message_id, publish_time e attributes, 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 attributes.

    Se a opção write metadata estiver desativada, apenas o payload da mensagem será gravado no objeto Avro de saída. Este é o esquema Avro para as mensagens de saída com metadados de gravação desativados:

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

    Este é o esquema Avro para as 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" }
      ]
    }
    

  • Usar esquema de tópicos: essa opção permite que o Pub/Sub use o esquema do tópico do Pub/Sub a que a assinatura está anexada ao gravar arquivos Avro.

    Ao usar essa opção, lembre-se de verificar os seguintes requisitos adicionais:

    • O esquema do tópico precisa estar no formato Apache Avro (link em inglês).

    • Se usar esquema de tópicos e gravar metadados estiverem ativados, o esquema de tópicos precisará ter um objeto Record na raiz. O Pub/Sub vai expandir a lista de campos do registro para incluir os campos de metadados. Como resultado, o registro não pode conter nenhum campo com o mesmo nome que os campos de metadados (subscription_name, message_id, publish_time ou attributes).

Criar uma assinatura do Cloud Storage

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";
}

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
}

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 fornece várias métricas para monitorar assinaturas.

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

A seguir

• Resolver problemas de uma assinatura do Cloud Storage.

• Leia sobre o Cloud Storage.

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