Criar um tópico

No Pub/Sub, um tópico é um recurso nomeado que representa um feed de mensagens. É necessário criar um tópico antes de publicar ou assinar a ele. O Pub/Sub oferece suporte a dois tipos de tópicos: um tópico padrão e um tópico de importação.

Este documento descreve como criar um tópico padrão do Pub/Sub. Se você quiser saber mais sobre um tópico de importação e como criar um, consulte Sobre os tópicos de importação.

Para criar um tópico, use o console do Google Cloud, a Google Cloud CLI, a biblioteca de cliente ou a API Pub/Sub.

Antes de começar

Permissões e papéis necessários para gerenciar tópicos

Para receber as permissões necessárias para criar e gerenciar tópicos, peça ao administrador para conceder a você o papel do IAM de editor do Pub/Sub (roles/pubsub.editor) no seu tópico ou 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 e gerenciar tópicos. 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 e gerenciar tópicos:

  • Crie um tópico: pubsub.topics.create
  • Exclua um tópico: pubsub.topics.delete
  • Remover uma assinatura de um tópico: pubsub.topics.detachSubscription
  • Escolha um tema: pubsub.topics.get
  • Listar um tema: pubsub.topics.list
  • Publicar em um tópico: pubsub.topics.publish
  • Atualizar um tópico: pubsub.topics.update
  • Acesse a política do IAM para um tópico: pubsub.topics.getIamPolicy
  • Configure a política do IAM para um tópico: pubsub.topics.setIamPolicy

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

É possível configurar o controle de acesso no nível do projeto e do recurso individual. É possível criar uma assinatura em um projeto e anexá-la a um tópico localizado em outro projeto. Verifique se você tem as permissões necessárias para para cada projeto.

Propriedades de um tema

Ao criar ou atualizar um tópico, você precisa especificar as propriedades dele.

Adicione uma assinatura padrão

Adiciona uma assinatura padrão ao tópico do Pub/Sub. Você pode criar outra assinatura para o tópico depois que ele for criado. A assinatura padrão tem as seguintes propriedades:

  • ID da assinatura de -sub
  • Tipo de entrega pull
  • Duração de sete dias de retenção da mensagem
  • Expira após 31 dias de inatividade
  • Prazo de confirmação de 10 segundos
  • Política de repetição imediata

Usar um esquema

Um esquema é um formato que o campo de dados da mensagem precisa seguir. Um esquema é um contrato entre o editor e o assinante que Aplicações do Pub/Sub. Os esquemas de tópicos ajudam a padronizar mensagens e permissões para que sejam consumidos por equipes diferentes. na sua organização. O Pub/Sub cria uma autoridade central para tipos de mensagens e permissões. Para criar um tópico com esquema, consulte Visão geral do esquema.

Ativar ingestão

Ativar essa propriedade permite ingerir dados de streaming de fontes externas em um tópico para que você possa usar do Google Cloud. Para criar um tópico de importação para a transferência, consulte Criar um tópico de importação.

Ativar retenção de mensagens

Especifica por quanto tempo o tópico do Pub/Sub retém mensagens após a publicação. Após a duração da retenção da mensagem, o Pub/Sub pode descartar a mensagem, independentemente do estado de confirmação. As tarifas de armazenamento de mensagens são cobradas pelo armazenamento de todas as mensagens publicadas no tópico.

  • Padrão = não ativada
  • Valor mínimo = 10 minutos
  • Valor máximo = 31 dias

Exportar dados de mensagem para o BigQuery

Ao ativar essa propriedade, você pode criar uma assinatura do BigQuery que grava mensagens em uma tabela do BigQuery em que eles são recebidos. Não é preciso configurar um assinante separado para o cliente. Para mais informações sobre as assinaturas do BigQuery, consulte Assinaturas do BigQuery.

Exportar dados de mensagens para o Cloud Storage

A ativação dessa propriedade permite criar uma assinatura do Cloud Storage que grava mensagens em uma tabela do Cloud Storage à medida que elas são recebidas. Não é necessário configurar um cliente de assinante separado. Para mais informações sobre assinaturas do Cloud Storage, consulte Assinaturas do Cloud Storage.

Chave de criptografia gerenciada pelo Google

Especifica que o tópico é criptografado usando chaves de criptografia gerenciadas pelo Google. O Pub/Sub criptografa mensagens com chaves gerenciadas pelo Google por padrão. Portanto, escolher essa opção mantém o comportamento padrão. O Google processa o gerenciamento e a rotação de chaves automaticamente, garantindo que suas mensagens estejam sempre protegidas com a criptografia mais forte disponível. Essa opção não exige configuração adicional. Para mais informações sobre as chaves de criptografia gerenciadas pelo Google, consulte Criptografia padrão com chaves de propriedade e gerenciadas pelo Google.

Chave do Cloud KMS

Especifica se o tópico é criptografado com uma chave de criptografia gerenciada pelo cliente (CMEK). Pub/Sub criptografa mensagens com chaves de propriedade e gerenciadas pelo Google por padrão. Se você especificar essa opção, o Pub/Sub usa o padrão de criptografia de envelope com a CMEK. Nessa abordagem, o Cloud KMS não criptografa as mensagens. Em vez disso, O Cloud KMS criptografa as chaves de criptografia de dados (DEKs) que o Pub/Sub cria para cada tópico. O Pub/Sub criptografa as mensagens a DEK mais recente gerada para o tópico. Pub/Sub descriptografa as mensagens pouco antes de serem entregues aos assinantes. Para mais informações sobre como criar uma chave, consulte Configurar a criptografia de mensagens.

Criar um tópico

Crie um tópico antes de publicar ou se inscrever nele.

Console

Para criar um tópico, siga estas etapas:

  1. No Console do Google Cloud, acesse a página Tópicos do Pub/Sub.

    Acesse Tópicos

  2. Selecione Criar tópico.

  3. No campo ID do tópico, insira um ID para o tópico. Para mais informações sobre como nomear tópicos, consulte as diretrizes de nomenclatura.

  4. Mantenha a opção Adicionar uma assinatura padrão.

  5. Opcional. Não selecione as outras opções.

  6. Selecione Criar tópico.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Para criar um tópico, execute o Comando gcloud pubsub topics create:

    gcloud pubsub topics create TOPIC_ID

REST

Para criar um tópico, use o método projects.topics.create:

A solicitação precisa ser autenticada com um token de acesso no cabeçalho Authorization. Para conseguir um token de acesso para o Application Default Credentials: gcloud auth application-default print-access-token.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN
    

Em que:

  • PROJECT_ID é o ID do projeto;
  • TOPIC_ID é o ID do tópico.
  • Resposta:

    {
     "name": "projects/PROJECT_ID/topics/TOPIC_ID"
    }

    C++

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

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

    namespace pubsub = ::google::cloud::pubsub;
    namespace pubsub_admin = ::google::cloud::pubsub_admin;
    [](pubsub_admin::TopicAdminClient client, std::string project_id,
       std::string topic_id) {
      auto topic = client.CreateTopic(
          pubsub::Topic(std::move(project_id), std::move(topic_id)).FullName());
      // Note that kAlreadyExists is a possible error when the library retries.
      if (topic.status().code() == google::cloud::StatusCode::kAlreadyExists) {
        std::cout << "The topic already exists\n";
        return;
      }
      if (!topic) throw std::move(topic).status();
    
      std::cout << "The topic was successfully created: " << topic->DebugString()
                << "\n";
    }

    C#

    Antes de testar esta amostra, siga as instruções de configuração do 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 C#.

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

    
    using Google.Cloud.PubSub.V1;
    using Grpc.Core;
    using System;
    
    public class CreateTopicSample
    {
        public Topic CreateTopic(string projectId, string topicId)
        {
            PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
            var topicName = TopicName.FromProjectTopic(projectId, topicId);
            Topic topic = null;
    
            try
            {
                topic = publisher.CreateTopic(topicName);
                Console.WriteLine($"Topic {topic.Name} created.");
            }
            catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
            {
                Console.WriteLine($"Topic {topicName} already exists.");
            }
            return topic;
        }
    }

    Go

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

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

    import (
    	"context"
    	"fmt"
    	"io"
    
    	"cloud.google.com/go/pubsub"
    )
    
    func create(w io.Writer, projectID, topicID string) error {
    	// projectID := "my-project-id"
    	// topicID := "my-topic"
    	ctx := context.Background()
    	client, err := pubsub.NewClient(ctx, projectID)
    	if err != nil {
    		return fmt.Errorf("pubsub.NewClient: %w", err)
    	}
    	defer client.Close()
    
    	t, err := client.CreateTopic(ctx, topicID)
    	if err != nil {
    		return fmt.Errorf("CreateTopic: %w", err)
    	}
    	fmt.Fprintf(w, "Topic created: %v\n", t)
    	return nil
    }
    

    Java

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

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

    
    import com.google.cloud.pubsub.v1.TopicAdminClient;
    import com.google.pubsub.v1.Topic;
    import com.google.pubsub.v1.TopicName;
    import java.io.IOException;
    
    public class CreateTopicExample {
      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";
    
        createTopicExample(projectId, topicId);
      }
    
      public static void createTopicExample(String projectId, String topicId) throws IOException {
        try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
          TopicName topicName = TopicName.of(projectId, topicId);
          Topic topic = topicAdminClient.createTopic(topicName);
          System.out.println("Created topic: " + topic.getName());
        }
      }
    }

    Node.js

    /**
     * TODO(developer): Uncomment this variable before running the sample.
     */
    // const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
    
    // 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 createTopic(topicNameOrId) {
      // Creates a new topic
      await pubSubClient.createTopic(topicNameOrId);
      console.log(`Topic ${topicNameOrId} created.`);
    }

    Node.js

    /**
     * TODO(developer): Uncomment this variable before running the sample.
     */
    // const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
    
    // Imports the Google Cloud client library
    import {PubSub} from '@google-cloud/pubsub';
    
    // Creates a client; cache this for further use
    const pubSubClient = new PubSub();
    
    async function createTopic(topicNameOrId: string) {
      // Creates a new topic
      await pubSubClient.createTopic(topicNameOrId);
      console.log(`Topic ${topicNameOrId} created.`);
    }

    PHP

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

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

    use Google\Cloud\PubSub\PubSubClient;
    
    /**
     * Creates a Pub/Sub topic.
     *
     * @param string $projectId  The Google project ID.
     * @param string $topicName  The Pub/Sub topic name.
     */
    function create_topic($projectId, $topicName)
    {
        $pubsub = new PubSubClient([
            'projectId' => $projectId,
        ]);
        $topic = $pubsub->createTopic($topicName);
    
        printf('Topic created: %s' . PHP_EOL, $topic->name());
    }

    Python

    Antes de testar este exemplo, siga as instruções de configuração do Python na 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 Python.

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

    from google.cloud import pubsub_v1
    
    # TODO(developer)
    # project_id = "your-project-id"
    # topic_id = "your-topic-id"
    
    publisher = pubsub_v1.PublisherClient()
    topic_path = publisher.topic_path(project_id, topic_id)
    
    topic = publisher.create_topic(request={"name": topic_path})
    
    print(f"Created topic: {topic.name}")

    Ruby

    Antes de testar esta amostra, siga as instruções de configuração do Ruby 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 Ruby.

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

    # topic_id = "your-topic-id"
    
    pubsub = Google::Cloud::Pubsub.new
    
    topic = pubsub.create_topic topic_id
    
    puts "Topic #{topic.name} created."

    Restrições da política da organização

    As políticas organizacionais podem restringir a criação de tópicos. Por exemplo, uma política pode restringir o armazenamento de mensagens em uma região do Compute Engine. Para evitar erros de criação de tópicos, examine e atualize as políticas organizacionais, conforme necessário, antes de criar um tópico.

    Se o projeto tiver sido criado recentemente, aguarde alguns minutos a política da organização a ser inicializada antes de criar um tópico.

    Acesse as políticas da organização

    Para mais informações, consulte Configurar políticas de armazenamento de mensagens.

    A seguir