Criar e usar tópicos

Neste documento, explicamos como criar, atualizar, visualizar e excluir um tópico do Pub/Sub. Este documento também explica como nomear tópicos e assinaturas.

Replicação de dados em um tópico

Um tópico do Pub/Sub usa três zonas para armazenar dados. O serviço garante a replicação síncrona para pelo menos duas zonas e a replicação de melhor esforço para uma terceira zona adicional. A replicação do Pub/Sub está em apenas uma região.

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: -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 10 segundos
    • Política de repetição imediata
  • Esquema. O esquema é um formato que o campo de dados de mensagens precisa seguir. Um esquema é um contrato entre o editor e o assinante aplicado pelo Pub/Sub. Os esquemas de tópicos ajudam a padronizar os tipos de mensagens e permissões para que sejam consumidos por diferentes equipes 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 Criar e gerenciar esquemas.

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

    • Padrão = não ativado
    • Valor mínimo = 10 minutos
    • Valor máximo = 31 dias
  • Use uma chave de criptografia gerenciada pelo cliente (CMEK). Especifica se o tópico é criptografado com uma CMEK. Por padrão, o Pub/Sub criptografa mensagens com chaves gerenciadas pelo Google. 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) criadas pelo Pub/Sub para cada tópico. O Pub/Sub criptografa as mensagens usando a DEK mais recente gerada para o tópico. O 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.

Diretrizes para nomear um tópico, uma assinatura ou um snapshot

Um nome de recurso do Pub/Sub identifica exclusivamente um recurso do Pub/Sub, como um tópico, uma assinatura ou um snapshot. O nome do recurso precisa ter o seguinte formato:

projects/project-identifier/collection/ID

  • project-identifier: precisa ser o ID do projeto, disponível no console do Google Cloud. Por exemplo, my-cool-project.

  • collection: precisa ser topics, subscriptions ou snapshots.

  • ID: precisa estar em conformidade com as seguintes diretrizes:

    • Não começar com a string goog
    • Começar com uma letra
    • conter entre 3 e 255 caracteres;
    • Contém apenas os seguintes caracteres: letras [A-Za-z], números [0-9], traços -, sublinhados _, pontos ., tils ~, mais sinais + e sinais de porcentagem %

    Você pode usar os caracteres especiais na lista anterior em nomes de recursos sem codificação para URLs. No entanto, é necessário garantir que qualquer outro caractere especial seja devidamente codificado ou decodificado quando usado em URLs. Por exemplo, mi-tópico é um ID inválido. No entanto, mi-t%C3%B3pico é válido. Esse formato é importante quando você faz chamadas REST.

Crie um tópico

Crie um tópico para 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. Clique em Criar tópico.

  3. No campo Código do tópico, insira um código para o tópico.

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

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

  6. Selecione Criar tópico.

gcloud CLI

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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ do Pub/Sub.

    namespace pubsub = ::google::cloud::pubsub;
    [](pubsub::TopicAdminClient client, std::string project_id,
       std::string topic_id) {
      auto topic = client.CreateTopic(pubsub::TopicBuilder(
          pubsub::Topic(std::move(project_id), std::move(topic_id))));
      // 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::runtime_error(topic.status().message());
    
      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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# do Pub/Sub.

    
    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.

    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: %v", err)
    	}
    	defer client.Close()
    
    	t, err := client.CreateTopic(ctx, topicID)
    	if err != nil {
    		return fmt.Errorf("CreateTopic: %v", 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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.

    
    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 testar esta amostra, siga as instruções de configuração do Node.js 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 Node.js do Pub/Sub.

    /**
     * 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() {
      // Creates a new topic
      await pubSubClient.createTopic(topicNameOrId);
      console.log(`Topic ${topicNameOrId} created.`);
    }
    
    createTopic();

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API PHP do Pub/Sub.

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

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

    # topic_id = "your-topic-id"
    require "google/cloud/pubsub"
    
    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 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 na criação de tópicos, examine e atualize as políticas organizacionais conforme necessário antes de criar um tópico.

    Se o projeto for recém-criado, aguarde alguns minutos até a política da organização ser inicializada antes de criar um tópico.

    Acesse as políticas da organização

    Criar um tópico com um esquema

    Ao criar um tópico, talvez você queira atribuir um esquema a ele.

    Veja a seguir algumas diretrizes sobre como usar esquemas:

    • Não é possível adicionar esquemas a tópicos existentes.
    • É possível especificar um esquema somente ao criar um tópico.
    • Depois que um esquema for associado a um tópico, não será possível atualizá-lo ou remover a associação.
    • Você pode aplicar o mesmo esquema a outros tópicos.
    • Se você excluir um esquema, a publicação de todos os tópicos associados falhará.

    Para saber mais sobre esquemas, consulte Criar e gerenciar esquemas.

    Console

    Para criar um tópico e atribuir a ele um esquema, siga estas etapas:

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

      Acesse Tópicos

    2. Clique em Criar tópico.

    3. No campo Código do tópico, insira um código para o tópico.

    4. Marque a caixa Usar um esquema. Não altere as outras opções.

    5. Clique em Selecionar um esquema do Pub/Sub e escolha Criar um novo esquema. Se você quiser usar um esquema atual, pule para a etapa 7.

    6. No campo Schema ID, insira um ID para seu esquema.

    7. Em Tipo de esquema, selecione Avro ou o buffer de protocolo.

    8. No campo Definição de esquema, insira a definição de Buffer de protocolo Avro para seu esquema.

    9. Clique em Criar para salvar o esquema.

    10. Na caixa de diálogo Criar um tópico, procure seu esquema no campo Selecionar um esquema do Pub/Sub.

    11. Clique em Criar para salvar o tópico e atribuí-lo com o esquema selecionado.

    gcloud

    Para criar um tópico atribuído com um esquema criado anteriormente, execute o comando gcloud pubsub topics create:

    gcloud pubsub topics create TOPIC_ID \
            --message-encoding=ENCODING_TYPE \
            --schema=SCHEMA_ID

    Em que:

    • TOPIC_ID é o ID do tópico que você está criando.
    • ENCODING_TYPE é a codificação de mensagens validadas no esquema. Esse valor precisa ser definido como JSON ou BINARY.
    • SCHEMA_ID é o ID de um esquema atual.

    Também é possível atribuir um esquema de um projeto diferente do Google Cloud:

    gcloud pubsub topics create TOPIC_ID \
            --message-encoding=ENCODING_TYPE \
            --schema=SCHEMA_ID \
            --schema-project=SCHEMA_PROJECT \
            --project=TOPIC_PROJECT

    Em que:

    • SCHEMA_PROJECT é o ID do projeto do Google Cloud para o esquema.
    • TOPIC_PROJECT é o ID do projeto do Google Cloud para o tópico.

    REST

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

    Solicitação:

    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
    

    Corpo da solicitação:

    {
      "schemaSettings": {
        "schema": "SCHEMA_NAME",
        "encoding": "ENCODING_TYPE"
      }
    }

    Em que:

    • PROJECT_ID é o ID do projeto;
    • TOPIC_ID é o ID do tópico.
    • SCHEMA_NAME é o nome do esquema em que as mensagens publicadas precisam ser validadas. O formato é: projects/PROJECT_ID/schemas/SCHEMA_ID.
    • ENCODING_TYPE é a codificação de mensagens validadas no esquema. Precisa ser definido como JSON ou BINARY.

    Resposta:

    {
      "name": "projects/PROJECT_ID/topics/TOPIC_ID",
      "schemaSettings": {
        "schema": "SCHEMA_NAME",
        "encoding": "ENCODING_TYPE"
      }
    }

    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;
    [](pubsub::TopicAdminClient client, std::string project_id,
       std::string topic_id, std::string schema_id, std::string const& encoding) {
      auto const& schema = pubsub::Schema(project_id, std::move(schema_id));
      auto topic = client.CreateTopic(
          pubsub::TopicBuilder(
              pubsub::Topic(std::move(project_id), std::move(topic_id)))
              .set_schema(schema)
              .set_encoding(encoding == "JSON" ? google::pubsub::v1::JSON
                                               : google::pubsub::v1::BINARY));
      // 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::runtime_error(topic.status().message());
    
      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 CreateTopicWithSchemaSample
    {
        public Topic CreateTopicWithSchema(string projectId, string topicId, string schemaName, Encoding encoding)
        {
            PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
            var topicName = TopicName.FromProjectTopic(projectId, topicId);
            Topic topic = new Topic
            {
                Name = topicName.ToString(),
                SchemaSettings = new SchemaSettings
                {
                    Schema = schemaName,
                    Encoding = encoding
                }
            };
    
            Topic receivedTopic = null;
            try
            {
                receivedTopic = publisher.CreateTopic(topic);
                Console.WriteLine($"Topic {topic.Name} created.");
            }
            catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
            {
                Console.WriteLine($"Topic {topicName} already exists.");
            }
            return receivedTopic;
        }
    }

    Go

    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"
    )
    
    func createTopicWithSchema(w io.Writer, projectID, topicID, schemaID string, encoding pubsub.SchemaEncoding) error {
    	// projectID := "my-project-id"
    	// topicID := "my-topic"
    	// schemaID := "my-schema-id"
    	// encoding := pubsub.EncodingJSON
    	ctx := context.Background()
    	client, err := pubsub.NewClient(ctx, projectID)
    	if err != nil {
    		return fmt.Errorf("pubsub.NewClient: %v", err)
    	}
    
    	tc := &pubsub.TopicConfig{
    		SchemaSettings: &pubsub.SchemaSettings{
    			Schema:   fmt.Sprintf("projects/%s/schemas/%s", projectID, schemaID),
    			Encoding: encoding,
    		},
    	}
    	t, err := client.CreateTopicWithConfig(ctx, topicID, tc)
    	if err != nil {
    		return fmt.Errorf("CreateTopicWithConfig: %v", err)
    	}
    	fmt.Fprintf(w, "Topic with schema 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 Java.

    
    import com.google.api.gax.rpc.AlreadyExistsException;
    import com.google.cloud.pubsub.v1.TopicAdminClient;
    import com.google.pubsub.v1.Encoding;
    import com.google.pubsub.v1.SchemaName;
    import com.google.pubsub.v1.SchemaSettings;
    import com.google.pubsub.v1.Topic;
    import com.google.pubsub.v1.TopicName;
    import java.io.IOException;
    
    public class CreateTopicWithSchemaExample {
    
      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";
        // Use an existing schema.
        String schemaId = "your-schema-id";
        // Choose either BINARY or JSON message serialization in this topic.
        Encoding encoding = Encoding.BINARY;
    
        createTopicWithSchemaExample(projectId, topicId, schemaId, encoding);
      }
    
      public static void createTopicWithSchemaExample(
          String projectId, String topicId, String schemaId, Encoding encoding) throws IOException {
        TopicName topicName = TopicName.of(projectId, topicId);
        SchemaName schemaName = SchemaName.of(projectId, schemaId);
    
        SchemaSettings schemaSettings =
            SchemaSettings.newBuilder().setSchema(schemaName.toString()).setEncoding(encoding).build();
    
        try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
    
          Topic topic =
              topicAdminClient.createTopic(
                  Topic.newBuilder()
                      .setName(topicName.toString())
                      .setSchemaSettings(schemaSettings)
                      .build());
    
          System.out.println("Created topic with schema: " + topic.getName());
        } catch (AlreadyExistsException e) {
          System.out.println(schemaName + "already exists.");
        }
      }
    }

    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 Node.js.

    /**
     * TODO(developer): Uncomment these variables before running the sample.
     */
    // const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
    // const schemaName = 'YOUR_SCHEMA_NAME_OR_ID';
    // const encodingType = 'BINARY';
    
    // 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 createTopicWithSchema(
      topicNameOrId,
      schemaNameOrId,
      encodingType
    ) {
      // Get the fully qualified schema name.
      const schema = pubSubClient.schema(schemaNameOrId);
      const fullName = await schema.getName();
    
      // Creates a new topic with a schema. Note that you might also
      // pass Encodings.Json or Encodings.Binary here.
      await pubSubClient.createTopic({
        name: topicNameOrId,
        schemaSettings: {
          schema: fullName,
          encoding: encodingType,
        },
      });
      console.log(`Topic ${topicNameOrId} created with schema ${fullName}.`);
    }

    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;
    use Google\Cloud\PubSub\Schema;
    
    /**
     * Create a topic with a schema.
     *
     * @param string $projectId
     * @param string $topicId
     * @param string $schemaId
     * @param string $encoding
     */
    function create_topic_with_schema($projectId, $topicId, $schemaId, $encoding)
    {
        $pubsub = new PubSubClient([
            'projectId' => $projectId,
        ]);
    
        $schema = $pubsub->schema($schemaId);
    
        $topic = $pubsub->createTopic($topicId, [
            'schemaSettings' => [
                // The schema may be provided as an instance of the schema type,
                // or by using the schema ID directly.
                'schema' => $schema,
                // Encoding may be either `BINARY` or `JSON`.
                // Provide a string or a constant from Google\Cloud\PubSub\V1\Encoding.
                'encoding' => $encoding,
            ]
        ]);
    
        printf('Topic %s created', $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 Pub/Sub Python.

    from google.api_core.exceptions import AlreadyExists, InvalidArgument
    from google.cloud.pubsub import PublisherClient, SchemaServiceClient
    from google.pubsub_v1.types import Encoding
    
    # TODO(developer): Replace these variables before running the sample.
    # project_id = "your-project-id"
    # topic_id = "your-topic-id"
    # schema_id = "your-schema-id"
    # Choose either BINARY or JSON as valid message encoding in this topic.
    # message_encoding = "BINARY"
    
    publisher_client = PublisherClient()
    topic_path = publisher_client.topic_path(project_id, topic_id)
    
    schema_client = SchemaServiceClient()
    schema_path = schema_client.schema_path(project_id, schema_id)
    
    if message_encoding == "BINARY":
        encoding = Encoding.BINARY
    elif message_encoding == "JSON":
        encoding = Encoding.JSON
    else:
        encoding = Encoding.ENCODING_UNSPECIFIED
    
    try:
        response = publisher_client.create_topic(
            request={
                "name": topic_path,
                "schema_settings": {"schema": schema_path, "encoding": encoding},
            }
        )
        print(f"Created a topic:\n{response}")
    
    except AlreadyExists:
        print(f"{topic_id} already exists.")
    except InvalidArgument:
        print("Please choose either BINARY or JSON as a valid message encoding type.")

    Ruby

    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"
    # schema_id = "your-schema-id"
    # Choose either BINARY or JSON as valid message encoding in this topic.
    # message_encoding = :binary
    require "google/cloud/pubsub"
    
    pubsub = Google::Cloud::Pubsub.new
    
    topic = pubsub.create_topic topic_id, schema_name: schema_id, message_encoding: message_encoding
    
    puts "Topic #{topic.name} created."

    Excluir um tópico

    Quando você exclui um tópico, as assinaturas dele não são excluídas. O backlog de mensagens da assinatura está disponível para assinantes. Depois que um tópico é excluído, as assinaturas dele ficam com o nome de tópico _deleted-topic_. Se você tentar criar um tópico com o mesmo nome de um que você acabou de excluir, aguarde um erro por um breve período.

    Console

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

      Acesse Tópicos

    2. Selecione um tópico e clique em Mais ações.

    3. Clique em Excluir.

      A janela Excluir tópico será exibida.

    4. Digite delete e clique em Delete.

    gcloud CLI

    Para excluir um tópico, use o comando gcloud pubsub topics delete:

    gcloud pubsub topics delete TOPIC_ID

    REST

    Para excluir um tópico, use o método projects.topics.delete:

    Solicitação:

    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.

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

    Se a solicitação for bem-sucedida, a resposta será um objeto JSON vazio.

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ do Pub/Sub.

    namespace pubsub = ::google::cloud::pubsub;
    [](pubsub::TopicAdminClient client, std::string const& project_id,
       std::string const& topic_id) {
      auto status = client.DeleteTopic(
          pubsub::Topic(std::move(project_id), std::move(topic_id)));
      // Note that kNotFound is a possible result when the library retries.
      if (status.code() == google::cloud::StatusCode::kNotFound) {
        std::cout << "The topic was not found\n";
        return;
      }
      if (!status.ok()) throw std::runtime_error(status.message());
    
      std::cout << "The topic was successfully deleted\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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# do Pub/Sub.

    
    using Google.Cloud.PubSub.V1;
    
    public class DeleteTopicSample
    {
        public void DeleteTopic(string projectId, string topicId)
        {
            PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
            TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
            publisher.DeleteTopic(topicName);
        }
    }

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.

    import (
    	"context"
    	"fmt"
    	"io"
    
    	"cloud.google.com/go/pubsub"
    )
    
    func delete(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: %v", err)
    	}
    	defer client.Close()
    
    	t := client.Topic(topicID)
    	if err := t.Delete(ctx); err != nil {
    		return fmt.Errorf("Delete: %v", err)
    	}
    	fmt.Fprintf(w, "Deleted topic: %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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.

    
    import com.google.api.gax.rpc.NotFoundException;
    import com.google.cloud.pubsub.v1.TopicAdminClient;
    import com.google.pubsub.v1.TopicName;
    import java.io.IOException;
    
    public class DeleteTopicExample {
      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";
    
        deleteTopicExample(projectId, topicId);
      }
    
      public static void deleteTopicExample(String projectId, String topicId) throws IOException {
        try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
          TopicName topicName = TopicName.of(projectId, topicId);
          try {
            topicAdminClient.deleteTopic(topicName);
            System.out.println("Deleted topic.");
          } catch (NotFoundException e) {
            System.out.println(e.getMessage());
          }
        }
      }
    }

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.

    /**
     * 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 deleteTopic() {
      /**
       * TODO(developer): Uncomment the following line to run the sample.
       */
      // const topicName = 'my-topic';
    
      // Deletes the topic
      await pubSubClient.topic(topicNameOrId).delete();
      console.log(`Topic ${topicNameOrId} deleted.`);
    }
    
    deleteTopic().catch(console.error);

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API PHP do Pub/Sub.

    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 delete_topic($projectId, $topicName)
    {
        $pubsub = new PubSubClient([
            'projectId' => $projectId,
        ]);
        $topic = $pubsub->topic($topicName);
        $topic->delete();
    
        printf('Topic deleted: %s' . PHP_EOL, $topic->name());
    }

    Python

    Antes de testar esta amostra, siga as instruções de configuração do Python 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 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)
    
    publisher.delete_topic(request={"topic": topic_path})
    
    print(f"Topic deleted: {topic_path}")

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Ruby do Pub/Sub.

    # topic_id = "your-topic-id"
    require "google/cloud/pubsub"
    
    pubsub = Google::Cloud::Pubsub.new
    
    topic = pubsub.topic topic_id
    topic.delete
    
    puts "Topic #{topic_id} deleted."

    Listar um tópico

    Console

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

      Acesse Tópicos

      A página Tópicos lista todos os tópicos disponíveis.

    gcloud CLI

    Para listar tópicos, use o comando gcloud pubsub topics list:

    gcloud pubsub topics list

    REST

    Para listar tópicos, use o método projects.topics.list:

    Solicitação:

    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.

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

    Em que:

  • PROJECT_ID é o ID do projeto;
  • Resposta:

    {
      "topics": [
        {
          "name": "projects/PROJECT_ID/topics/mytopic1",
          ...
        },
        {
          "name": "projects/PROJECT_ID/topics/mytopic2",
          ...
        }
      ]
    }

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ do Pub/Sub.

    namespace pubsub = ::google::cloud::pubsub;
    [](pubsub::TopicAdminClient client, std::string const& project_id) {
      int count = 0;
      for (auto const& topic : client.ListTopics(project_id)) {
        if (!topic) throw std::runtime_error(topic.status().message());
        std::cout << "Topic Name: " << topic->name() << "\n";
        ++count;
      }
      if (count == 0) {
        std::cout << "No topics found in project " << project_id << "\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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# do Pub/Sub.

    
    using Google.Api.Gax.ResourceNames;
    using Google.Cloud.PubSub.V1;
    using System.Collections.Generic;
    
    public class ListProjectTopicsSample
    {
        public IEnumerable<Topic> ListProjectTopics(string projectId)
        {
            PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
            ProjectName projectName = ProjectName.FromProject(projectId);
            IEnumerable<Topic> topics = publisher.ListTopics(projectName);
            return topics;
        }
    }

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.

    import (
    	"context"
    	"fmt"
    
    	"cloud.google.com/go/pubsub"
    	"google.golang.org/api/iterator"
    )
    
    func list(projectID string) ([]*pubsub.Topic, error) {
    	// projectID := "my-project-id"
    	ctx := context.Background()
    	client, err := pubsub.NewClient(ctx, projectID)
    	if err != nil {
    		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
    	}
    	defer client.Close()
    
    	var topics []*pubsub.Topic
    
    	it := client.Topics(ctx)
    	for {
    		topic, err := it.Next()
    		if err == iterator.Done {
    			break
    		}
    		if err != nil {
    			return nil, fmt.Errorf("Next: %v", err)
    		}
    		topics = append(topics, topic)
    	}
    
    	return topics, 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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.

    
    import com.google.cloud.pubsub.v1.TopicAdminClient;
    import com.google.pubsub.v1.ProjectName;
    import com.google.pubsub.v1.Topic;
    import java.io.IOException;
    
    public class ListTopicsExample {
      public static void main(String... args) throws Exception {
        // TODO(developer): Replace these variables before running the sample.
        String projectId = "your-project-id";
    
        listTopicsExample(projectId);
      }
    
      public static void listTopicsExample(String projectId) throws IOException {
        try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
          ProjectName projectName = ProjectName.of(projectId);
          for (Topic topic : topicAdminClient.listTopics(projectName).iterateAll()) {
            System.out.println(topic.getName());
          }
          System.out.println("Listed all topics.");
        }
      }
    }

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.

    // 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 listAllTopics() {
      // Lists all topics in the current project
      const [topics] = await pubSubClient.getTopics();
      console.log('Topics:');
      topics.forEach(topic => console.log(topic.name));
    }
    
    listAllTopics().catch(console.error);

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API PHP do Pub/Sub.

    use Google\Cloud\PubSub\PubSubClient;
    
    /**
     * Lists all Pub/Sub topics.
     *
     * @param string $projectId  The Google project ID.
     */
    function list_topics($projectId)
    {
        $pubsub = new PubSubClient([
            'projectId' => $projectId,
        ]);
        foreach ($pubsub->topics() as $topic) {
            printf('Topic: %s' . PHP_EOL, $topic->name());
        }
    }

    Python

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

    from google.cloud import pubsub_v1
    
    # TODO(developer)
    # project_id = "your-project-id"
    
    publisher = pubsub_v1.PublisherClient()
    project_path = f"projects/{project_id}"
    
    for topic in publisher.list_topics(request={"project": project_path}):
        print(topic)

    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 usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Ruby do Pub/Sub.

    require "google/cloud/pubsub"
    
    pubsub = Google::Cloud::Pubsub.new
    
    topics = pubsub.topics
    
    puts "Topics in project:"
    topics.each do |topic|
      puts topic.name
    end

    Por padrão, são retornados no máximo 100 resultados por consulta. Você pode mudar essa quantidade para até 1.000 usando o parâmetro de tamanho de página.

    Monitorar tópicos

    É possível monitorar tópicos no Pub/Sub.

    A seguir