Criar assinaturas do Cloud Storage

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

Antes de começar

Antes de ler este documento, confira se você conhece os seguintes conceitos:

Papéis e permissões necessárias

Para receber as permissões necessárias para criar uma assinatura de armazenamento do Cloud Storage, peça ao administrador para conceder a você o papel do IAM de Editor do Pub/Sub (roles/pubsub.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar uma assinatura de armazenamento do Cloud Storage. Para acessar 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 uma assinatura de armazenamento do Cloud Storage:

  • pubsub.subscriptions.create no projeto
  • pubsub.topics.attachSubscription no tópico

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Assinaturas entre projetos

Se você criar uma assinatura em um projeto para um tópico em outro, será necessário ter a permissão pubsub.subscriptions.create no projeto em que você está criando a assinatura e a permissão pubsub.topics.attachSubscription no tópico.

Conceder papéis do IAM à conta de serviço

O Pub/Sub usa uma conta de serviço do Identity and Access Management (IAM) para acessar recursos do Google Cloud . Por padrão, ele usa o agente de serviço do Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com).

Para permitir que o Pub/Sub grave no Cloud Storage, a conta de serviço precisa das seguintes funções:

  • Criador de objetos do Storage (roles/storage.objectCreator)
  • Leitor de bucket legado do Storage (roles/storage.legacyBucketReader)

É possível conceder permissões à conta de serviço para o projeto ou o bucket do Cloud Storage, da seguinte maneira:

Projeto

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

    Acessar buckets

  2. Selecione Incluir concessões de papel fornecidas pelo Google.

  3. Localize a linha da conta de serviço do Cloud Pub/Sub e clique em Editar principal.

  4. Clique em Adicionar outro papel e selecione o papel Criador de objetos do Storage. Repita essa etapa para o papel Leitor de bucket legado do Storage.

Para mais informações, consulte Conceder um papel do IAM usando o console.

Bucket do Cloud Storage

  1. No Google Cloud console, acesse Buckets.

    Acessar buckets

  2. Clique no nome do bucket do Cloud Storage a que você quer conceder permissão.

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

  4. No painel Permissões, clique na guia Visualizar por principais.

  5. Clique em Conceder acesso.

  6. No campo Novos principais, insira o identificador da conta de serviço no seguinte formato:

    service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.

  7. Na lista Atribuir papéis, selecione Criador de objetos do Storage.

  8. Clique em Adicionar outro papel e selecione Leitor de bucket legados do Storage.

  9. Clique em Salvar. O principal recebe os papéis no recurso.

Usar uma conta de serviço personalizada

Ao conceder os papéis Criador de objetos do Storage e Leitor de bucket legados do Storage à conta de serviço do Cloud Pub/Sub, qualquer usuário com permissão para criar uma assinatura no projeto pode gravar no bucket do Cloud Storage. Se você quiser fornecer permissões mais granulares, configure uma conta serviço gerenciado pelo usuário.

As seguintes permissões são necessárias para configurar uma conta de serviço gerenciado pelo usuário para gravar no Cloud Storage:

  • A conta de serviço gerenciado pelo usuário precisa ter os papéis Criador de objetos do Storage e Leitor de buckets legados do Storage.

  • A conta de serviço do Cloud Pub/Sub precisa ter a permissão iam.serviceAccounts.getAccessToken na conta de serviço gerenciado pelo usuário.

  • O usuário que cria a assinatura precisa ter a permissão iam.serviceAccounts.actAs na conta de serviço gerenciado pelo usuário.

Ao criar a assinatura, especifique a conta de serviço gerenciado pelo usuário como a conta de serviço da assinatura.

Propriedades da assinatura de Cloud Storage

As assinaturas do Cloud Storage são compatíveis com todas as propriedades comuns de assinatura. As seções a seguir descrevem propriedades específicas das assinaturas do Cloud Storage.

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 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 de arquivo e dos campos que você pode personalizar:

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

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

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

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

  • É possível mudar 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 for _archive, um nome de objeto de exemplo será prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

    • Se você não especificar o prefixo e o sufixo do nome do arquivo, o nome do objeto armazenado no bucket do Cloud Storage será do 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 objetos do Cloud Storage.

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

    • Correspondedores de data e hora obrigatórios que podem ser usados 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.

    • Correspondedores opcionais que podem ser usados apenas uma vez: separador de data e hora (T) e deslocamento 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 com um caractere que não seja um comparador, 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 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

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 agrupamento em lote especificadas é atendida. Estas são as condições de loteamento do Cloud Storage:

  • Duração máxima do lote de armazenamento. Essa é uma configuração obrigatória. O Pub/Sub grava um novo arquivo de saída se o valor especificado para max duration for excedido. A duração é medida desde o momento em que o Pub/Sub começa a gravar em um novo arquivo até a finalização dele. Por exemplo, se você definir a duração máxima como 5 minutos, o Pub/Sub vai finalizar o arquivo no máximo 5 minutos depois de começar a gravar nele. Um novo arquivo pode ser criado antes que a duração máxima tenha decorrido. Se você não especificar o valor, o padrão de 5 minutos será aplicado. Estes são 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

  • Máximo de bytes do lote de armazenamento. Essa configuração é opcional. A assinatura de armazenamento do Cloud Storage grava um novo arquivo de saída se o valor especificado de bytes máximos for excedido. Estes são os valores aplicáveis para bytes máximos:

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

  • Número máximo de mensagens do lote de armazenamento. Essa configuração é opcional. A assinatura do Cloud Storage grava um novo arquivo de saída se o número máximo de mensagens especificado for excedido. Confira abaixo os valores aplicáveis para o número máximo de mensagens:

    • Valor mínimo = 1000

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

Uma assinatura de armazenamento 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, é possível observar vários arquivos do Cloud Storage sendo criados a cada 6 minutos.

Em algumas situações, o Pub/Sub pode começar a gravar em um novo arquivo antes do horário configurado pelas condições de agrupamento em lote. Um arquivo também pode exceder o valor de "Max 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 Texto ou Avro.

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

  • Avro: as mensagens são armazenadas no formato binário do Apache Avro. Ao selecionar Avro, você pode ativar estas propriedades adicionais:

    • Gravar metadados: permite armazenar os metadados da mensagem junto com ela. 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 de mensagem que não sejam dados (por exemplo, uma ordering_key, se presente) são adicionadas como entradas no mapa attributes.

      Se a opção gravar metadados estiver desativada, apenas a carga útil da mensagem será gravada no objeto Avro de saída. Confira abaixo o esquema Avro para as mensagens de saída com os metadados de gravação desativados:

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

      Confira o esquema Avro para as mensagens de saída com os 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ópico: 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, verifique os seguintes requisitos adicionais:

      • O esquema do tópico precisa estar no formato Apache Avro.

      • Se as opções usar esquema de tópico e gravar metadados estiverem ativadas, o esquema de tópico 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 campos com o mesmo nome dos campos de metadados (subscription_name, message_id, publish_time ou attributes).

Conta de serviço

Você tem as seguintes opções para gravar mensagens em um bucket do Cloud Storage:

  • Configure uma conta de serviço personalizada para que apenas usuários com a permissão iam.serviceAccounts.actAs na conta de serviço possam criar uma assinatura que grava no bucket. Um exemplo de papel que inclui a permissão iam.serviceAccounts.actAs é o papel Usuário da conta de serviço (roles/iam.serviceAccountUser).

  • Use o agente de serviço padrão do Pub/Sub, que permite que qualquer usuário com a capacidade de criar assinaturas no projeto crie uma assinatura que grave no bucket. O agente de serviço do Pub/Sub é a configuração padrão quando você não especifica uma conta de serviço personalizada.

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, insira um nome.

    Para informações sobre 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 informações sobre como criar um tópico, consulte Criar e gerenciar tópicos.

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

  6. Para o bucket do Cloud Storage, clique em Procurar.

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

    • Você também pode clicar no ícone de criação e seguir as instruções na tela para criar um bucket.

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

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

    Ao especificar o bucket, o Pub/Sub verifica as permissões adequadas no bucket para o agente de serviço do Pub/Sub. Se houver problemas de permissão, você vai receber 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.

    Ou siga as instruções em Atribuir papéis do Cloud Storage ao agente 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 mensagem para o formato Avro, consulte Formato de arquivo.

  9. Opcional: é possível especificar o prefixo, o sufixo e a data/hora 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, o sufixo e a data/hora do arquivo, consulte Prefixo, sufixo e data/hora do nome do arquivo.

  10. Para Agrupamento de arquivos, especifique um tempo máximo para decorrer antes de criar um novo arquivo.

    Você também pode definir o tamanho máximo do arquivo ou o número máximo de mensagens para os arquivos.

    Para mais informações sobre as duas opções de agrupamento de arquivos, consulte Agrupamento de arquivos.

  11. Recomendamos ativar o envio para fila de 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 de baixo do console 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 de armazenamento 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-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \
    --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \
    --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \
    --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \
    --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \
    --cloud-storage-write-metadata
    --cloud-storage-use-topic-schema

    Se você quiser usar uma conta de serviço personalizada, forneça-a como um argumento adicional:

    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-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \
    --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \
    --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \
    --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \
    --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \
    --cloud-storage-write-metadata
    --cloud-storage-use-topic-schema
    --cloud-storage-service-account-email=SERVICE_ACCOUNT_NAME

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

    Substitua:

    • SUBSCRIPTION_ID: o nome ou ID da sua nova assinatura de armazenamento do Cloud Storage.
    • TOPIC_ID: o nome ou ID do tópico.
    • BUCKET_NAME: especifica o nome de um bucket existente. 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 do 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_FILE_DATETIME_FORMAT: Especifica o formato de data e hora para o nome do arquivo do Cloud Storage. Por exemplo, YYYY-MM-DD/hh_mm_ssZ.
    • CLOUD_STORAGE_MAX_DURATION: a duração máxima que pode decorrer antes da criação de um novo arquivo do Cloud Storage. O valor precisa estar entre 1m e 10m. Por exemplo, 5m.
    • CLOUD_STORAGE_MAX_BYTES: o número 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_MESSAGES: o número máximo de mensagens que podem ser gravadas em um arquivo do Cloud Storage antes da criação de um novo arquivo. O valor precisa ser maior ou igual a 1000. Por exemplo, 100000.
    • 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 gravadas como um binário Avro. --cloud-storage-write-metadata e --cloud-storage-use-topic-schema afetam apenas assinaturas com formato de saída avro.
    • SERVICE_ACCOUNT_NAME: especifica o nome da conta de serviço a ser usada para gravar no Cloud Storage.

C++

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

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

C#

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

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


using Google.Cloud.PubSub.V1;
using Google.Protobuf.WellKnownTypes;
using System;

public class CreateCloudStorageSubscriptionSample
{
    public Subscription CreateCloudStorageSubscription(string projectId, string topicId, string subscriptionId,
        string bucket, string filenamePrefix, string filenameSuffix, TimeSpan maxDuration)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            CloudStorageConfig = new CloudStorageConfig
            {
                Bucket = bucket,
                FilenamePrefix = filenamePrefix,
                FilenameSuffix = filenameSuffix,
                MaxDuration = Duration.FromTimeSpan(maxDuration)
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

Go

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

Para 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/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
	"google.golang.org/protobuf/types/known/durationpb"
)

// createCloudStorageSubscription creates a Pub/Sub subscription that exports messages to Cloud Storage.
func createCloudStorageSubscription(w io.Writer, projectID, topic, subscription, bucket string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// bucket := "my-bucket" // bucket must not have the gs:// prefix
	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.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
		CloudStorageConfig: &pubsubpb.CloudStorageConfig{
			Bucket:         bucket,
			FilenamePrefix: "log_events_",
			FilenameSuffix: ".avro",
			OutputFormat: &pubsubpb.CloudStorageConfig_AvroConfig_{
				AvroConfig: &pubsubpb.CloudStorageConfig_AvroConfig{
					WriteMetadata: true,
				},
			},
			MaxDuration: durationpb.New(1 * time.Minute),
			MaxBytes:    1e8,
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create cloud storage sub: %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 para Java no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub para Java.

Para 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());
    }
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createCloudStorageSubscription(
  topicName,
  subscriptionName,
  bucket,
  filenamePrefix,
  filenameSuffix,
  maxDuration,
) {
  const options = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

// Imports the Google Cloud client library
import {CreateSubscriptionOptions, PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createCloudStorageSubscription(
  topicName: string,
  subscriptionName: string,
  bucket: string,
  filenamePrefix: string,
  filenameSuffix: string,
  maxDuration: number,
) {
  const options: CreateSubscriptionOptions = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

PHP

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

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

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub GCS subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $bucket The Cloud Storage bucket name without any prefix like "gs://".
 */
function create_cloud_storage_subscription($projectId, $topicName, $subscriptionName, $bucket)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = ['bucket' => $bucket];
    $subscription->create([
        'cloudStorageConfig' => $config
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

Python

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

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

from google.cloud import pubsub_v1
from google.protobuf import duration_pb2

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bucket = "my-bucket"

filename_prefix = "log_events_"
filename_suffix = ".avro"
# Either CloudStorageConfig.AvroConfig or CloudStorageConfig.TextConfig
# defaults to TextConfig
avro_config = pubsub_v1.types.CloudStorageConfig.AvroConfig(write_metadata=True)

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)
max_duration = duration_pb2.Duration()
max_duration.FromSeconds(300)

cloudstorage_config = pubsub_v1.types.CloudStorageConfig(
    bucket=bucket,
    filename_prefix=filename_prefix,
    filename_suffix=filename_suffix,
    avro_config=avro_config,
    # Min 1 minutes, max 10 minutes
    max_duration=max_duration,
    # Min 1 KB, max 10 GiB
    max_bytes=10000000,
)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "cloud_storage_config": cloudstorage_config,
        }
    )

print(f"CloudStorage subscription created: {subscription}.")
print(f"Bucket for subscription is: {bucket}")
print(f"Prefix is: {filename_prefix}")
print(f"Suffix is: {filename_suffix}")

Monitorar uma assinatura de Cloud Storage

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

Para conferir uma lista de todas as métricas disponíveis relacionadas ao Pub/Sub e as descrições delas, consulte a documentação do Monitoring para o Pub/Sub.

Você também pode monitorar as assinaturas no Pub/Sub.

A seguir