Como gerenciar tópicos e assinaturas

Neste documento, fornecemos informações sobre como criar, excluir e administrar tópicos e assinaturas do Cloud Pub/Sub. Para saber mais sobre como publicar e acessar dados de mensagens, consulte o Guia do editor e a Visão geral do assinante.

Como gerenciar tópicos

É possível criar, excluir e visualizar tópicos por meio da API, do Console do GCP ou da ferramenta de linha de comando gcloud. Veja a referência do gcloud pubsub para uma lista completa dos comandos gcloud para a API do Cloud Pub/Sub.

Para uma introdução sobre o Console do GCP, consulte o Guia de início rápido do Console do GCP.

Criar um tópico

É necessário criar um tópico para poder publicar ou inscrever-se nele. Veja um exemplo de como criar um tópico:

Protocolo

Solicitação:

PUT https://pubsub.googleapis.com/v1/projects/myproject/topics/mytopic

Resposta:

200 OK

{
 "name": "projects/myproject/topics/mytopic"
}

Linha de comando

  gcloud pubsub topics create myTopic

C#

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

Ver no GitHub Feedback

            PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();

            TopicName topicName = new TopicName(projectId, topicId);
            try
            {
                publisher.CreateTopic(topicName);
            }
            catch (RpcException e)
            when (e.Status.StatusCode == StatusCode.AlreadyExists)
            {
                // Already exists.  That's fine.
            }

Go

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

Ver no GitHub Feedback

t, err := client.CreateTopic(ctx, topic)
if err != nil {
	return err
}
fmt.Printf("Topic created: %v\n", t)

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud Pub/Sub para Java.

Ver no GitHub Feedback

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  // projectId <=  unique project identifier, eg. "my-project-id"
  // topicId <= "my-topic-id"
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  Topic topic = topicAdminClient.createTopic(topicName);
  return topic;
}

Node.js

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

Ver no GitHub Feedback

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

// Creates a client
const pubsub = new PubSub();

/**
 * TODO(developer): Uncomment the following line to run the sample.
 */
// const topicName = 'my-topic';

// Creates a new topic
await pubsub.createTopic(topicName);
console.log(`Topic ${topicName} created.`);

PHP

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

Ver no GitHub Feedback

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

Ver no GitHub Feedback

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(project_id, topic_name)

topic = publisher.create_topic(topic_path)

print('Topic created: {}'.format(topic))

Ruby

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

Ver no GitHub Feedback

# project_id = "Your Google Cloud Project ID"
# topic_name = "Your Pubsub topic name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic  = pubsub.create_topic topic_name

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

Excluir um tópico

Veja um exemplo de como excluir um tópico:

Protocolo

Solicitação:

DELETE https://pubsub.googleapis.com/v1/projects/myproject/topics/mytopic

Resposta:

200 OK

{
 "name": "projects/myproject/topics/mytopic"
}

COMANDO GCLOUD

  gcloud pubsub topics delete myTopic

C#

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

Ver no GitHub Feedback

PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
TopicName topicName = new TopicName(projectId, topicId);
publisher.DeleteTopic(topicName);
Console.WriteLine("Topic deleted.");

Go

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

Ver no GitHub Feedback

t := client.Topic(topic)
if err := t.Delete(ctx); err != nil {
	return err
}
fmt.Printf("Deleted topic: %v\n", t)

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud Pub/Sub para Java.

Ver no GitHub Feedback

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  topicAdminClient.deleteTopic(topicName);
  return topicName;
}

Node.js

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

Ver no GitHub Feedback

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

// Creates a client
const pubsub = new PubSub();

/**
 * TODO(developer): Uncomment the following line to run the sample.
 */
// const topicName = 'my-topic';

// Deletes the topic
await pubsub.topic(topicName).delete();
console.log(`Topic ${topicName} deleted.`);

PHP

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

Ver no GitHub Feedback

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

Ver no GitHub Feedback

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(project_id, topic_name)

publisher.delete_topic(topic_path)

print('Topic deleted: {}'.format(topic_path))

Ruby

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

Ver no GitHub Feedback

# project_id = "Your Google Cloud Project ID"
# topic_name = "Your Pubsub topic name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic = pubsub.topic topic_name
topic.delete

puts "Topic #{topic_name} deleted."

Quando você exclui um tópico, as assinaturas dele não são excluídas e o backlog da mensagem da assinatura fica disponível para os 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 recém-excluído, verá um erro por um breve período de tempo após a exclusão.

Listar tópicos

Veja um exemplo de como listar tópicos:

Protocolo

Solicitação:

GET https://pubsub.googleapis.com/v1/projects/myproject/topics

Resposta:

200 OK

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

COMANDO GCLOUD

   gcloud pubsub topics list

C#

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

Ver no GitHub Feedback

ProjectName projectName = new ProjectName(projectId);
IEnumerable<Topic> topics = publisher.ListTopics(projectName);
foreach (Topic topic in topics)
{
    Console.WriteLine($"{topic.Name}");
}

Go

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

Ver no GitHub Feedback

var topics []*pubsub.Topic

it := client.Topics(ctx)
for {
	topic, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return nil, err
	}
	topics = append(topics, topic)
}

return topics, nil

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud Pub/Sub para Java.

Ver no GitHub Feedback

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  ListTopicsRequest listTopicsRequest =
      ListTopicsRequest.newBuilder().setProject(ProjectName.format(projectId)).build();
  ListTopicsPagedResponse response = topicAdminClient.listTopics(listTopicsRequest);
  Iterable<Topic> topics = response.iterateAll();
  for (Topic topic : topics) {
    // do something with the topic
  }
  return response;
}

Node.js

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

Ver no GitHub Feedback

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

// Creates a client
const pubsub = new PubSub();

// Lists all topics in the current project
const [topics] = await pubsub.getTopics();
console.log('Topics:');
topics.forEach(topic => console.log(topic.name));

PHP

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

Ver no GitHub Feedback

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

Ver no GitHub Feedback

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"

publisher = pubsub_v1.PublisherClient()
project_path = publisher.project_path(project_id)

for topic in publisher.list_topics(project_path):
    print(topic)

Ruby

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

Ver no GitHub Feedback

# project_id = "Your Google Cloud Project ID"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

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.

Como gerenciar assinaturas

Nesta seção, você aprenderá a gerenciar assinaturas de push e pull. Para uma visão geral e comparação das assinaturas de pull e de push, consulte a visão geral do assinante.

É necessário criar uma assinatura em um tópico para que os assinantes possam receber mensagens publicadas nele.

Consulte também a referência da gcloud para ver comandos de assinantes.

As assinaturas têm várias propriedades que podem ser definidas no momento da criação ou atualizadas depois, como:

• Método de entrega: por padrão, as assinaturas do Cloud Pub/Sub usam o método pull. Para alternar para entrega de push, basta especificar um URL de endpoint de push HTTPS válido e não vazio. Para voltar à entrega de pull, especifique um URL vazio.

• Prazo de confirmação: caso o código não confirme a mensagem antes do prazo, ela será enviada novamente. O padrão é 10 segundos. O prazo máximo personalizado que pode ser especificado é de 600 segundos (10 minutos).

Protocolo

Solicitação:

PUT https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription

{
  "topic": "projects/someproject/topics/sometopic"
  // Only needed if you are using push delivery
  "pushConfig": {
    "pushEndpoint": "https://myproject.appspot.com/myhandler"
  }
}

Resposta:

200 OK

{
  "name": "projects/myproject/subscriptions/mysubscription",
  "topic": "projects/someproject/topics/sometopic",
  "pushConfig": {
    "pushEndpoint": "https://myproject.appspot.com/myhandler"
  },
  "ackDeadlineSeconds": 10
}

COMANDO GCLOUD

   gcloud pubsub subscriptions create mySubscription --topic myTopic

C#

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

Ver no GitHub Feedback

SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
TopicName topicName = new TopicName(projectId, topicId);
SubscriptionName subscriptionName = new SubscriptionName(projectId,
    subscriptionId);
try
{
    Subscription subscription = subscriber.CreateSubscription(
        subscriptionName, topicName, pushConfig: null,
        ackDeadlineSeconds: 60);
}
catch (RpcException e)
when (e.Status.StatusCode == StatusCode.AlreadyExists)
{
    // Already exists.  That's fine.
}

Go

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

Ver no GitHub Feedback

sub, err := client.CreateSubscription(ctx, subName, pubsub.SubscriptionConfig{
	Topic:       topic,
	AckDeadline: 20 * time.Second,
})
if err != nil {
	return err
}
fmt.Printf("Created subscription: %v\n", sub)

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud Pub/Sub para Java.

Ver no GitHub Feedback

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  // eg. projectId = "my-test-project", topicId = "my-test-topic"
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  // eg. subscriptionId = "my-test-subscription"
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);
  // create a pull subscription with default acknowledgement deadline
  Subscription subscription =
      subscriptionAdminClient.createSubscription(
          subscriptionName, topicName, PushConfig.getDefaultInstance(), 0);
  return subscription;
}

Node.js

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

Ver no GitHub Feedback

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

// Creates a client
const pubsub = new PubSub();

/**
 * TODO(developer): Uncomment the following lines to run the sample.
 */
// const topicName = 'my-topic';
// const subscriptionName = 'my-sub';

// Creates a new subscription
await pubsub.topic(topicName).createSubscription(subscriptionName);
console.log(`Subscription ${subscriptionName} created.`);

PHP

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

Ver no GitHub Feedback

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 */
function create_subscription($projectId, $topicName, $subscriptionName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create();

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

Python

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

Ver no GitHub Feedback

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"
# TODO subscription_name = "Your Pub/Sub subscription name"

subscriber = pubsub_v1.SubscriberClient()
topic_path = subscriber.topic_path(project_id, topic_name)
subscription_path = subscriber.subscription_path(
    project_id, subscription_name)

subscription = subscriber.create_subscription(
    subscription_path, topic_path)

print('Subscription created: {}'.format(subscription))

Ruby

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

Ver no GitHub Feedback

# project_id        = "Your Google Cloud Project ID"
# topic_name        = "Your Pubsub topic name"
# subscription_name = "Your Pubsub subscription name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic        = pubsub.topic topic_name
subscription = topic.subscribe subscription_name

puts "Pull subscription #{subscription_name} created."

É possível criar assinaturas de push fornecendo um URL de endpoint HTTP, como mostrado nestes exemplos:

COMANDO GCLOUD

   gcloud pubsub subscriptions create mySubscription --topic myTopic --push-endpoint="https://myapp.appspot.com/push"

Go

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

Ver no GitHub Feedback

// For example, endpoint is "https://my-test-project.appspot.com/push".
sub, err := client.CreateSubscription(ctx, subName, pubsub.SubscriptionConfig{
	Topic:       topic,
	AckDeadline: 10 * time.Second,
	PushConfig:  pubsub.PushConfig{Endpoint: endpoint},
})
if err != nil {
	return err
}
fmt.Printf("Created subscription: %v\n", sub)

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud Pub/Sub para Java.

Ver no GitHub Feedback

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);

  // eg. endpoint = "https://my-test-project.appspot.com/push"
  PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(endpoint).build();

  // acknowledgement deadline in seconds for the message received over the push endpoint
  int ackDeadlineInSeconds = 10;

  Subscription subscription =
      subscriptionAdminClient.createSubscription(
          subscriptionName, topicName, pushConfig, ackDeadlineInSeconds);
  return subscription;
}

Node.js

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

Ver no GitHub Feedback

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

// Creates a client
const pubsub = new PubSub();

/**
 * TODO(developer): Uncomment the following lines to run the sample.
 */
// const topicName = 'my-topic';
// const subscriptionName = 'my-sub';

const options = {
  pushConfig: {
    // Set to an HTTPS endpoint of your choice. If necessary, register
    // (authorize) the domain on which the server is hosted.
    pushEndpoint: `https://${pubsub.projectId}.appspot.com/push`,
  },
};

await pubsub.topic(topicName).createSubscription(subscriptionName, options);
console.log(`Subscription ${subscriptionName} created.`);

PHP

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

Ver no GitHub Feedback

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub push 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 $endpoint  The endpoint for the push subscription.
 */
function create_push_subscription($projectId, $topicName, $subscriptionName, $endpoint)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create([
        'endpoint' => $endpoint
    ]);

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

Python

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

Ver no GitHub Feedback

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"
# TODO subscription_name = "Your Pub/Sub subscription name"
# TODO endpoint = "https://my-test-project.appspot.com/push"

subscriber = pubsub_v1.SubscriberClient()
topic_path = subscriber.topic_path(project_id, topic_name)
subscription_path = subscriber.subscription_path(
    project_id, subscription_name)

push_config = pubsub_v1.types.PushConfig(
    push_endpoint=endpoint)

subscription = subscriber.create_subscription(
    subscription_path, topic_path, push_config)

print('Push subscription created: {}'.format(subscription))
print('Endpoint for subscription is: {}'.format(endpoint))

Ruby

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

Ver no GitHub Feedback

# project_id        = "Your Google Cloud Project ID"
# topic_name        = "Your Pubsub topic name"
# subscription_name = "Your Pubsub subscription name"
# endpoint          = "Endpoint where your app receives messages"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic        = pubsub.topic topic_name
subscription = topic.subscribe subscription_name,
                               endpoint: endpoint

puts "Push subscription #{subscription_name} created."

Como alternar entre assinaturas de push e pull

Você pode usar o console do GPC do Cloud Pub/Sub para alterar o tipo de assinatura. No console, edite a assinatura e altere o Tipo de entrega para Pull ou Push.

Como alternativa, você pode usar a ferramenta de linha de comando gcloud. Especificamente, use o comando modify-push-config para modificar o URL do ponto de extremidade de envio.

• Para converter uma assinatura de push para pull, altere o URL para uma string vazia.
• Para converter uma assinatura de pull para push, defina um URL válido.

Observação: se você estiver alternando de uma assinatura de push para pull, deverá permitir um curto período de tempo para que a alteração entre em vigor. O intervalo geralmente é de alguns segundos, mas pode levar vários minutos em casos raros. Durante esse tempo, o sistema pode continuar a entregar mensagens para o endpoint e você verá erros nas solicitações pull.

Exemplos: como modificar o endpoint de uma assinatura ou mecanismo de entrega

Depois que uma assinatura é criada, é possível atualizar o endpoint de push da assinatura ou alternar entre push e pull. Veja alguns exemplos de como atualizar uma assinatura de pull ou push atual, especificando um URL de endpoint de push HTTPS válido e não vazio:

COMANDO GCLOUD

   gcloud pubsub subscriptions modify-push-config mySubscription --push-endpoint="https://anotherapp.appspot.com/push"

Go

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

Ver no GitHub Feedback

// For example, endpoint is "https://my-test-project.appspot.com/push".
subConfig, err := client.Subscription(subName).Update(ctx, pubsub.SubscriptionConfigToUpdate{
	PushConfig: &pubsub.PushConfig{Endpoint: endpoint},
})
if err != nil {
	return err
}
fmt.Printf("Updated subscription config: %#v", subConfig)

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud Pub/Sub para Java.

Ver no GitHub Feedback

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);
  PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(endpoint).build();
  subscriptionAdminClient.modifyPushConfig(subscriptionName, pushConfig);
}

Node.js

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

Ver no GitHub Feedback

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

// Creates a client
const pubsub = new PubSub();

/**
 * TODO(developer): Uncomment the following line to run the sample.
 */
// const topicName = 'my-topic';
// const subscriptionName = 'my-sub';

const options = {
  // Set to an HTTPS endpoint of your choice. If necessary, register
  // (authorize) the domain on which the server is hosted.
  pushEndpoint: `https://${pubsub.projectId}.appspot.com/push`,
};

await pubsub
  .topic(topicName)
  .subscription(subscriptionName)
  .modifyPushConfig(options);
console.log(`Modified push config for subscription ${subscriptionName}.`);

Python

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

Ver no GitHub Feedback

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"
# TODO subscription_name = "Your Pub/Sub subscription name"
# TODO endpoint = "https://my-test-project.appspot.com/push"

subscriber = pubsub_v1.SubscriberClient()
subscription_path = subscriber.subscription_path(
    project_id, subscription_name)

push_config = pubsub_v1.types.PushConfig(
    push_endpoint=endpoint)

subscription = pubsub_v1.types.Subscription(
    name=subscription_path,
    push_config=push_config)

update_mask = {
    'paths': {
        'push_config',
    }
}

subscriber.update_subscription(subscription, update_mask)
result = subscriber.get_subscription(subscription_path)

print('Subscription updated: {}'.format(subscription_path))
print('New endpoint for subscription is: {}'.format(
    result.push_config))

Ruby

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

Ver no GitHub Feedback

# project_id        = "Your Google Cloud Project ID"
# subscription_name = "Your Pubsub subscription name"
# new_endpoint      = "Endpoint where your app receives messages""
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

subscription          = pubsub.subscription subscription_name
subscription.endpoint = new_endpoint

puts "Push endpoint updated."

Como modificar políticas de expiração de assinatura

Beta

Este produto ou recurso está em um estado de pré-lançamento e pode ser alterado ou ter suporte limitado. Para mais informações, consulte Estágios de lançamento do produto.

Por padrão, as assinaturas expiram após 31 dias de inatividade. Se o Cloud Pub/Sub detectar atividade do assinante (como conexões abertas, pulls ativos ou pushes bem-sucedidos), o relógio de exclusão da assinatura será reiniciado.

Para alterar esse comportamento, modifique a política de expiração da assinatura. É possível definir a duração da política no momento de criação da assinatura ou modificá-la posteriormente. O valor mínimo permitido para uma política de expiração é de 1 dia. Não há máximo. Use qualquer uma das seguintes opções para configurar a política:

• Os sinalizadores de duração e expiração disponíveis nos comandos de assinatura da gcloud beta. Exemplo:

  alias pubsub='gcloud beta pubsub'
  # subscription that expires after one day of inactivity
  pubsub subscriptions create mySubscription --expiration-period=1d --topic myTopic
  # make the subscription non-expiring
  pubsub subscriptions update mySubscription --expiration-period=never
  

• As bibliotecas de cliente do Cloud Pub/Sub oferecem suporte para políticas de expiração.

• Métodos RPC:

  • CreateSubscription
  • UpdateSubscription

• Método REST:

  • projects.subscriptions.create

Como reter mensagens confirmadas e não confirmadas

Por padrão, o Cloud Pub/Sub garante que as assinaturas retenham mensagens não confirmadas por sete dias a partir do momento da publicação. Após a duração especificada para esta propriedade, as mensagens poderão ser perdidas, independentemente do estado de confirmação delas. É possível usar messageRetentionDuration para especificar a quantidade de tempo que uma assinatura precisa reter mensagens, até um máximo de sete dias. Também é possível definir a assinatura para reter mensagens confirmadas durante esse período. Consulte Como reproduzir e descartar mensagens.

Observação: quando você modifica a duração da retenção de mensagens ou a política de expiração da assinatura, a duração da expiração precisa ser um valor maior que a duração da retenção de mensagens. Os padrões são 7 e 31 dias, respectivamente.

Como listar assinaturas

É possível listar todas as assinaturas de um projeto ou apenas as de um determinado tópico. Consulte Controle de acesso para ver detalhes sobre limitação do acesso, se necessário. Veja exemplos de como listar todas as inscrições de um projeto.

COMANDO GCLOUD

   gcloud pubsub subscriptions list

C#

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

Ver no GitHub Feedback

SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
ProjectName projectName = new ProjectName(projectId);
IEnumerable<Subscription> subscriptions =
    subscriber.ListSubscriptions(projectName);
foreach (Subscription subscription in subscriptions)
{
    Console.WriteLine($"{subscription}");
}

Go

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

Ver no GitHub Feedback

var subs []*pubsub.Subscription
it := client.Subscriptions(ctx)
for {
	s, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return nil, err
	}
	subs = append(subs, s)
}

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud Pub/Sub para Java.

Ver no GitHub Feedback

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ListSubscriptionsRequest listSubscriptionsRequest =
      ListSubscriptionsRequest.newBuilder()
          .setProject(ProjectName.of(projectId).toString())
          .build();
  ListSubscriptionsPagedResponse response =
      subscriptionAdminClient.listSubscriptions(listSubscriptionsRequest);
  Iterable<Subscription> subscriptions = response.iterateAll();
  for (Subscription subscription : subscriptions) {
    // do something with the subscription
  }
  return response;
}

Node.js

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

Ver no GitHub Feedback

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

// Creates a client
const pubsub = new PubSub();

// Lists all subscriptions in the current project
const [subscriptions] = await pubsub.getSubscriptions();
console.log('Subscriptions:');
subscriptions.forEach(subscription => console.log(subscription.name));

PHP

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

Ver no GitHub Feedback

use Google\Cloud\PubSub\PubSubClient;

/**
 * Lists all Pub/Sub subscriptions.
 *
 * @param string $projectId  The Google project ID.
 */
function list_subscriptions($projectId)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    foreach ($pubsub->subscriptions() as $subscription) {
        printf('Subscription: %s' . PHP_EOL, $subscription->name());
    }
}

Python

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

Ver no GitHub Feedback

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"

subscriber = pubsub_v1.SubscriberClient()
project_path = subscriber.project_path(project_id)

for subscription in subscriber.list_subscriptions(project_path):
    print(subscription.name)

Ruby

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

Ver no GitHub Feedback

# project_id = Your Google Cloud Project ID
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

subscriptions = pubsub.list_subscriptions

puts "Subscriptions:"
subscriptions.each do |subscription|
  puts subscription.name
end

Como acessar assinaturas

Veja exemplos de como acessar assinaturas de um tópico específico.

COMANDO GCLOUD

   gcloud pubsub topics list-subscriptions myTopic

Go

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

Ver no GitHub Feedback

var subs []*pubsub.Subscription

it := client.Topic(topicID).Subscriptions(ctx)
for {
	sub, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return nil, err
	}
	subs = append(subs, sub)
}

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud Pub/Sub para Java.

Ver no GitHub Feedback

try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
  ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
  ListTopicSubscriptionsRequest request =
      ListTopicSubscriptionsRequest.newBuilder().setTopic(topicName.toString()).build();
  ListTopicSubscriptionsPagedResponse response =
      topicAdminClient.listTopicSubscriptions(request);
  Iterable<String> subscriptionNames = response.iterateAll();
  for (String subscriptionName : subscriptionNames) {
    // do something with the subscription name
  }
  return response;
}

Node.js

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

Ver no GitHub Feedback

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

// Creates a client
const pubsub = new PubSub();

/**
 * TODO(developer): Uncomment the following line to run the sample.
 */
// const topicName = 'my-topic';

// Lists all subscriptions for the topic
const [subscriptions] = await pubsub.topic(topicName).getSubscriptions();
console.log(`Subscriptions for ${topicName}:`);
subscriptions.forEach(subscription => console.log(subscription.name));

Python

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

Ver no GitHub Feedback

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO topic_name = "Your Pub/Sub topic name"

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(project_id, topic_name)

for subscription in publisher.list_topic_subscriptions(topic_path):
    print(subscription)

Ruby

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

Ver no GitHub Feedback

# project_id = "Your Google Cloud Project ID"
# topic_name = "Your Pubsub topic name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

topic         = pubsub.topic topic_name
subscriptions = topic.subscriptions

puts "Subscriptions in topic #{topic.name}:"
subscriptions.each do |subscription|
  puts subscription.name
end

Como excluir assinaturas

Veja exemplos de como excluir assinaturas em um projeto quando elas não forem mais necessárias.

COMANDO GCLOUD

   gcloud pubsub subscriptions delete mySubscription

C#

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

Ver no GitHub Feedback

SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
SubscriptionName subscriptionName = new SubscriptionName(projectId,
    subscriptionId);
subscriber.DeleteSubscription(subscriptionName);
Console.WriteLine("Subscription deleted.");

Go

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

Ver no GitHub Feedback

sub := client.Subscription(subName)
if err := sub.Delete(ctx); err != nil {
	return err
}
fmt.Println("Subscription deleted.")

Java

Antes de testar essa amostra, siga as instruções de configuração do Java no guia de início rápido do Cloud Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud Pub/Sub para Java.

Ver no GitHub Feedback

try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
  ProjectSubscriptionName subscriptionName =
      ProjectSubscriptionName.of(projectId, subscriptionId);
  subscriptionAdminClient.deleteSubscription(subscriptionName);
  return subscriptionName;
}

Node.js

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

Ver no GitHub Feedback

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

// Creates a client
const pubsub = new PubSub();

/**
 * TODO(developer): Uncomment the following line to run the sample.
 */
// const subscriptionName = 'my-sub';

// Deletes the subscription
await pubsub.subscription(subscriptionName).delete();
console.log(`Subscription ${subscriptionName} deleted.`);

PHP

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

Ver no GitHub Feedback

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 */
function delete_subscription($projectId, $subscriptionName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $subscription = $pubsub->subscription($subscriptionName);
    $subscription->delete();

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

Python

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

Ver no GitHub Feedback

from google.cloud import pubsub_v1

# TODO project_id = "Your Google Cloud Project ID"
# TODO subscription_name = "Your Pub/Sub subscription name"

subscriber = pubsub_v1.SubscriberClient()
subscription_path = subscriber.subscription_path(
    project_id, subscription_name)

subscriber.delete_subscription(subscription_path)

print('Subscription deleted: {}'.format(subscription_path))

Ruby

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

Ver no GitHub Feedback

# project_id        = "Your Google Cloud Project ID"
# subscription_name = "Your Pubsub subscription name"
require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new project: project_id

subscription = pubsub.subscription subscription_name
subscription.delete

puts "Subscription #{subscription_name} deleted."

Nomes de recursos

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

projects/project-identifier/collection/relative-name

project-identifier precisa ser o código do projeto, disponível no Console do Google Cloud Platform. Por exemplo, projects/myproject/topics/mytopic.

A collection precisa ser uma das subscriptions ou dos topics.

relative-name precisa:

• começar com uma letra;
• conter entre 3 e 255 caracteres;

• conter apenas os seguintes caracteres:

  • letras: [A-Za-z]
  • números: [0-9]
  • traços: -
  • sublinhados: _
  • pontos: .
  • sinais diacríticos: ~
  • sinais de adição: +

  • sinais de porcentagem: %

    Os caracteres especiais mencionados acima podem ser usados em nomes de recursos, mas é preciso garantir que os caracteres sejam codificados/decodificados corretamente quando usados em URLs. Isso é particularmente importante para chamadas REST.

O relative-name não pode começar com a string goog.

É possível incluir caracteres especiais no nome de recurso. Por exemplo, mi-tópico é um relative-name inválido. No entanto, mi-t%C3%B3pico é válido.

Observação: as bibliotecas de cliente podem ter diferentes abordagens para nomear recursos, como especificar project e relative-name em campos separados.