O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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 para poder publicar ou assinar. 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 tópicos de importação.

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

Antes de começar

Saiba mais sobre o serviço do Pub/Sub e a terminologia dele.
Saiba mais sobre o processo de publicação.

Papéis e permissões necessárias

Para receber as permissões necessárias para criar um tópico, peça ao administrador para conceder a você o papel do IAM de editor do Pub/Sub(roles/pubsub.editor) no seu 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 um tópico. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar um tópico:

Conceda essa permissão para criar um tópico no projeto: pubsub.topics.create

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

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

Propriedades de um tópico

Ao criar ou atualizar um tópico, é necessário especificar as propriedades dele.

Adicione uma assinatura padrão

Adiciona uma assinatura padrão ao tópico do Pub/Sub. É possível 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 da retenção de mensagens de sete dias
Expiração após 31 dias de inatividade
Prazo de confirmação de recebimento 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 o Pub/Sub aplica. Os esquemas de tópicos ajudam a padronizar tipos e permissões de mensagens para que possam ser consumidos por diferentes equipes da organização. O Pub/Sub cria uma autoridade central para tipos e permissões de mensagens. Para criar um tópico com esquema, consulte Visão geral do esquema.

Ativar ingestão

A ativação dessa propriedade permite ingerir dados de streaming de fontes externas em um tópico para que você possa usar os recursos de Google Cloud. Para criar um tópico de importação para ingestão, consulte o seguinte:

Ativar a retenção de mensagens de tópico

Por padrão, um tópico do Pub/Sub descarta mensagens assim que são confirmadas por todas as assinaturas anexadas a ele. Opcionalmente, é possível configurar um tópico para reter mensagens por um período de até 31 dias, com um período mínimo de retenção de 10 minutos.

A retenção de mensagens permite que as assinaturas reproduzam mensagens confirmadas anteriormente ou mensagens publicadas antes da criação da assinatura. Para mais informações, consulte Reproduzir e remover mensagens com a função de busca.

Os custos de armazenamento das mensagens retidas pelo tópico são faturados no projeto do tópico. Após o período de armazenamento de mensagens, o Pub/Sub pode descartar a mensagem, independentemente do estado de confirmação.

Para conferir as métricas sobre mensagens retidas, use as seguintes métricas do Cloud Monitoring:

topic/num_retained_messages: o número de mensagens retidas
topic/oldest_retained_message_age: a idade da mensagem retida mais antiga
topic/retained_bytes: o tamanho total das mensagens retidas, em bytes

Exportar dados de mensagem para o BigQuery

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

Fazer backup de dados de mensagens no Cloud Storage

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

Transformações

As SMTs de tópicos permitem modificações leves nos dados e atributos das mensagens diretamente no Pub/Sub. Esse recurso permite a limpeza de dados, filtragem ou conversão de formato antes que as mensagens sejam publicadas no tópico.

Para mais informações sobre SMTs, consulte a Visão geral das SMTs.

Google-owned and Google-managed encryption key

Especifica que o tópico está criptografado usando Google-owned and Google-managed encryption keys. O Pub/Sub criptografa mensagens com Google-owned and Google-managed encryption keys 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 mais configuração. Para mais informações sobre Google-owned and Google-managed encryption keys, consulte Criptografia padrão com Google-owned and Google-managed encryption keys.

Chave do Cloud KMS

Especifica se o tópico está criptografado com uma chave de criptografia gerenciada pelo cliente (CMEK). O Pub/Sub criptografa mensagens com Google-owned and Google-managed encryption keys por padrão. Se você especificar essa opção, o Pub/Sub usará o padrão de criptografia de envelope com 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 usando a DEK mais recente que foi gerada para o tópico. O Pub/Sub descriptografa as mensagens pouco antes de elas 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 poder publicar ou assinar.

Console

Para criar um tópico, siga estas etapas:

No Google Cloud console, acesse a página Criar tópico do Pub/Sub.

Acessar "Criar tópico"
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.
Para criar uma assinatura padrão para o tópico, selecione Adicionar uma assinatura padrão. Essa opção é ativada por padrão.
Opcional. Para usar um esquema com o tópico, clique em Usar um esquema e forneça o esquema. Para mais informações, consulte Criar e associar um esquema ao criar um tópico.
Para um tópico padrão, deixe a opção Ativar ingestão desmarcada.
Opcional. Para reter mensagens após a publicação, selecione Ativar retenção de mensagens. Selecione o período de armazenamento em dias, horas e minutos. Para mais informações, consulte Ativar retenção de mensagens.
Opcional. Para exportar mensagens publicadas para uma tabela do BigQuery, selecione Exportar dados para o BigQuery e insira os detalhes da tabela. Para mais informações, consulte Criar assinaturas do BigQuery.
Opcional. Para fazer backup de mensagens publicadas em um bucket do Cloud Storage, selecione Fazer backup de dados de mensagens no Cloud Storage e insira os detalhes do bucket do Cloud Storage. Para mais informações, consulte Criar assinaturas do Cloud Storage.
Opcional. Em Transformações, adicione uma ou mais transformações de mensagens únicas (SMTs) para manipular e filtrar dados de mensagens. Para mais informações, consulte Criar um tópico com SMTs.
Opcional. Para usar uma chave de criptografia gerenciada pelo cliente (CMEK) para criptografar mensagens, selecione Chave do Cloud KMS. Por padrão, o Pub/Sub usa a criptografia padrão do Google, que não exige uma CMEK. Para mais informações, consulte Configurar a criptografia de mensagens.
Opcional. Para gerenciar as chaves associadas ao tópico, clique em Gerenciar chaves. Para mais informações, consulte Visão geral das tags.
Selecione Criar tópico.

gcloud

No Google Cloud console, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do Google Cloud console, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Para criar um tópico, execute o gcloud pubsub topics create comando:
```
gcloud pubsub topics create TOPIC_ID
```

REST

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

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 tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.

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 tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C# .


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

O exemplo a seguir usa a versão principal da biblioteca de cliente do Go Pub/Sub (v2). Se você ainda estiver usando a biblioteca v1, consulte o guia de migração para a v2. Para conferir uma lista de exemplos de código da v1, consulte os exemplos de código obsoletos.

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

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()

	topic := &pubsubpb.Topic{
		Name: fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
	}
	t, err := client.TopicAdminClient.CreateTopic(ctx, topic)
	if err != nil {
		return fmt.Errorf("CreateTopic: %w", err)
	}
	fmt.Fprintf(w, "Topic created: %v\n", t)
	return nil
}

Java

Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub para Java (em inglês).


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

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

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

/**
 * 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 tentar esse exemplo, siga as instruções de configuração do PHP em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.

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 tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python do Pub/Sub.

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

O exemplo a seguir usa a biblioteca de cliente do Ruby Pub/Sub v3. Se você ainda estiver usando a biblioteca v2, consulte o guia de migração para a v3. Para conferir uma lista de exemplos de código do Ruby v2, consulte os exemplos de código obsoletos.

Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.

# topic_id = "your-topic-id"

pubsub = Google::Cloud::PubSub.new
topic_admin = pubsub.topic_admin

topic = topic_admin.create_topic name: pubsub.topic_path(topic_id)

puts "Topic #{topic.name} created."

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

As políticas da organização 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 da organização, conforme necessário, antes de criar um tópico.

Se o projeto foi criado recentemente, aguarde alguns minutos para que a política da organização seja 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

Escolha o tipo de assinatura para o tópico.
Saiba como publicar uma mensagem em um tópico.
Resolver um problema de tópico.
Crie ou modifique um tópico com a CLI gcloud, as APIs REST, ou as bibliotecas de cliente.

Apache Kafka® é uma marca registrada da The Apache Software Foundation ou afiliadas nos Estados Unidos e/ou em outros países.

Criar um tópico Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Papéis e permissões necessárias

Permissões necessárias

Propriedades de um tópico

Adicione uma assinatura padrão

Usar um esquema

Ativar ingestão

Ativar a retenção de mensagens de tópico

Exportar dados de mensagem para o BigQuery

Fazer backup de dados de mensagens no Cloud Storage

Transformações

Google-owned and Google-managed encryption key

Chave do Cloud KMS

Criar um tópico

Console

gcloud

REST

C++

C#

Go

Java

Node.js

Node.ts

PHP

Python

Ruby

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

A seguir

Criar um tópico