Como gerenciar tópicos e assinaturas

Neste documento, apresentamos informações sobre como criar, excluir e administrar tópicos e assinaturas do 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 Google Cloud ou da ferramenta de linha de comando gcloud. Consulte a referência do gcloud pubsub para uma lista completa de comandos gcloud da API Pub/Sub.

Como criar um tópico

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

Protocolo

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/myproject/topics/mytopic
Authorization: Bearer ACCESS_TOKEN
    

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

Ver no GitHub (em inglês) Feedback
namespace pubsub = google::cloud::pubsub;
[](pubsub::TopicAdminClient client, std::string project_id,
   std::string topic_id) {
  auto topic = client.CreateTopic(pubsub::TopicMutationBuilder(
      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 este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.


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 essa amostra, 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 Pub/Sub Go.

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

	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 essa 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 Pub/Sub Java.

Ver no GitHub (em inglês) Feedback

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 essa 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 Pub/Sub Node.js.

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';

// 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(topicName);
  console.log(`Topic ${topicName} created.`);
}

createTopic();

PHP

Antes de testar essa 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 Pub/Sub PHP.

Ver no GitHub (em inglês) 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 essa 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 Pub/Sub para Python (em inglês).

Ver no GitHub (em inglês) Feedback
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("Topic created: {}".format(topic))

Ruby

Antes de testar essa 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 Pub/Sub Ruby.

# 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."

Como excluir um tópico

Veja um exemplo de como excluir um tópico:

Protocolo

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/myproject/topics/mytopic
Authorization: Bearer ACCESS_TOKEN
    

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

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


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 essa amostra, 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 Pub/Sub Go.

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

	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 essa 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 Pub/Sub Java.

Ver no GitHub (em inglês) Feedback

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 essa 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 Pub/Sub Node.js.

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';

// 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(topicName).delete();
  console.log(`Topic ${topicName} deleted.`);
}

deleteTopic().catch(console.error);

PHP

Antes de testar essa 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 Pub/Sub PHP.

Ver no GitHub (em inglês) 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 essa 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 Pub/Sub para Python (em inglês).

Ver no GitHub (em inglês) Feedback
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("Topic deleted: {}".format(topic_path))

Ruby

Antes de testar essa 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 Pub/Sub Ruby.

# 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 inscrições dele não são excluídas, e o backlog da mensagem da inscrição fica disponível para os inscritos. 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.

Como listar tópicos

Veja um exemplo de como listar tópicos:

Protocolo

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/myproject/topics
Authorization: Bearer ACCESS_TOKEN
    

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

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


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 essa amostra, 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 Pub/Sub Go.

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

	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 essa 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 Pub/Sub Java.

Ver no GitHub (em inglês) Feedback

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 essa 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 Pub/Sub Node.js.

Ver no GitHub (em inglês) Feedback
// 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 essa 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 Pub/Sub PHP.

Ver no GitHub (em inglês) 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 essa 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 Pub/Sub para Python (em inglês).

Ver no GitHub (em inglês) Feedback
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 essa 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 Pub/Sub Ruby.

# 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 remover assinaturas

Ao criar uma assinatura, você a anexa a um tópico, e os assinantes podem receber mensagens da assinatura. Para impedir que os assinantes recebam mensagens, é possível remover assinaturas do tópico.

Antes de remover uma assinatura, você precisa da permissão pubsub.topics.detachSubscription no tópico. É possível remover uma assinatura sem permissões na assinatura, o que é útil para gerenciar um tópico que esteja em um projeto diferente da assinatura. Para mais informações, consulte Controle de acesso do Pub/Sub.

É possível remover a assinatura de um tópico usando o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub.

Console

Para remover uma assinatura, siga estas etapas:

  1. No Console do Cloud, acesse a página Tópicos.

    Acessar a página "Tópicos"

  2. Clique no código do tópico.

  3. Na guia Assinaturas, clique no ID da assinatura que você quer remover.

  4. Na página Detalhes da assinatura, clique em Remover.

  5. Na caixa de diálogo exibida, clique em Remover novamente.

gcloud

Para remover uma assinatura, use o comando gcloud pubsub topics detach-subscription:

gcloud pubsub topics detach-subscription SUBSCRIPTION_ID

Se a solicitação for bem-sucedida, a linha de comando exibirá uma confirmação:

Detached subscription [SUBSCRIPTION_ID].

Protocolo

Para remover uma assinatura, envie uma solicitação como esta:

POST https://pubsub.googleapis.com/v1/subscriptions/PROJECT_ID/subscriptions/SUBSCRIPTION_ID:detach
Authorization: Bearer $(gcloud auth application-default print-access-token)

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

O serviço Pub/Sub pode levar vários minutos para concluir a remoção da assinatura do tópico.

Depois que o serviço do Pub/Sub remove a assinatura do tópico, o serviço do Pub/Sub exclui todas as mensagens retidas para a assinatura. Não é possível recuperar essas mensagens da assinatura nem reconectá-la a um tópico. Para liberar sua cota de projeto do Cloud, exclua a assinatura.

Se a assinatura e o tópico estiverem em projetos diferentes do Cloud, o serviço Pub/Sub adicionará uma entrada aos registros de auditoria dos dois projetos.

Gerenciar inscrições

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 inscritos possam receber mensagens publicadas nela.

Como criar assinaturas

É possível criar assinaturas com o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub.

Console

Para criar uma assinatura, conclua as etapas a seguir.

  1. No Console do Cloud, acesse a página Assinaturas.

    Acessar a página "Assinaturas"

  2. Clique em Criar assinatura.

  3. Insira o ID da assinatura.

  4. Escolha ou crie um tópico no menu suspenso. A assinatura recebe mensagens do tópico.

  5. Clique em Criar

Você também pode criar uma assinatura na seção Tópicos. Esse atalho é útil para associar tópicos a assinaturas.

  1. No Console do Cloud, acesse a página Tópicos.

    Acessar a página "Tópicos"

  2. Clique em ao lado do tópico no qual criar uma assinatura.

  3. No menu de contexto, selecione Criar assinatura.

    O menu de contexto com a opção

  4. Insira o ID da assinatura.

  5. Clique em Criar

gcloud

Para criar uma assinatura, execute o comando gcloud pubsub subscriptions create.

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  [--ack-deadline=ACK_DEADLINE] \
  [--message-retention-duration=MESSAGE_RETENTION_DURATION] \
  [--expiration-period=EXPIRATION_PERIOD] \
  [--push-endpoint=PUSH_ENDPOINT] \
  [--dead-letter-topic=DEAD_LETTER_TOPIC_ID \
  --max-delivery-attempts=MAX_DELIVERY_ATTEMPTS] \
  [--min-retry-delay=MIN_RETRY_DELAY] \
  [--max-retry-delay=MAX_RETRY_DELAY]

API

Para criar uma assinatura, use o método projects.subscriptions.create.

Protocolo

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/myproject/subscriptions/mysubscription
Authorization: Bearer ACCESS_TOKEN

Especifique os campos a seguir no corpo da solicitação:

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

Saída:

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

C++

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

Ver no GitHub (em inglês) Feedback
namespace pubsub = google::cloud::pubsub;
[](pubsub::SubscriptionAdminClient client, std::string const& project_id,
   std::string const& topic_id, std::string const& subscription_id) {
  auto sub = client.CreateSubscription(
      pubsub::Topic(project_id, std::move(topic_id)),
      pubsub::Subscription(project_id, std::move(subscription_id)));
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::runtime_error(sub.status().message());

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

C#

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


using Google.Cloud.PubSub.V1;
using Grpc.Core;

public class CreateSubscriptionSample
{
    public Subscription CreateSubscription(string projectId, string topicId, string subscriptionId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);

        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        Subscription subscription = null;

        try
        {
            subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig: null, ackDeadlineSeconds: 60);
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            // Already exists.  That's fine.
        }
        return subscription;
    }
}

Go

Antes de testar essa amostra, 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 Pub/Sub Go.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub"
)

func create(w io.Writer, projectID, subID string, topic *pubsub.Topic) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

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

Java

Antes de testar essa 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 Pub/Sub Java.

Ver no GitHub (em inglês) Feedback

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreatePullSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";
    String topicId = "your-topic-id";

    createPullSubscriptionExample(projectId, subscriptionId, topicId);
  }

  public static void createPullSubscriptionExample(
      String projectId, String subscriptionId, String topicId) throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);
      // Create a pull subscription with default acknowledgement deadline of 10 seconds.
      // Messages not successfully acknowledged within 10 seconds will get resent by the server.
      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              subscriptionName, topicName, PushConfig.getDefaultInstance(), 10);
      System.out.println("Created pull subscription: " + subscription.getName());
    }
  }
}

Node.js

Antes de testar essa 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 Pub/Sub Node.js.

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

// 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 createSubscription() {
  // Creates a new subscription
  await pubSubClient.topic(topicName).createSubscription(subscriptionName);
  console.log(`Subscription ${subscriptionName} created.`);
}

createSubscription().catch(console.error);

PHP

Antes de testar essa 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 Pub/Sub PHP.

Ver no GitHub (em inglês) 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 essa 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 Pub/Sub para Python (em inglês).

Ver no GitHub (em inglês) Feedback
from google.cloud import pubsub_v1

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

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

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

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

Ruby

Antes de testar essa 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 Pub/Sub Ruby.

# 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."

Os exemplos a seguir mostram como criar uma assinatura com entrega por push. Por padrão, as assinaturas usam a entrega por pull.

C++

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

namespace pubsub = google::cloud::pubsub;
[](pubsub::SubscriptionAdminClient client, std::string const& project_id,
   std::string const& topic_id, std::string const& subscription_id,
   std::string const& endpoint) {
  auto sub = client.CreateSubscription(
      pubsub::Topic(project_id, std::move(topic_id)),
      pubsub::Subscription(project_id, std::move(subscription_id)),
      pubsub::SubscriptionMutationBuilder{}.set_push_config(
          pubsub::PushConfigBuilder{}.set_push_endpoint(endpoint)));
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::runtime_error(sub.status().message());

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

Go

Antes de testar essa amostra, 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 Pub/Sub Go.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub"
)

func createWithEndpoint(w io.Writer, projectID, subID string, topic *pubsub.Topic, endpoint string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// endpoint := "https://my-test-project.appspot.com/push"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	sub, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic:       topic,
		AckDeadline: 10 * time.Second,
		PushConfig:  pubsub.PushConfig{Endpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %v", err)
	}
	fmt.Fprintf(w, "Created subscription: %v\n", sub)
	return nil
}

Java

Antes de testar essa 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 Pub/Sub Java.

Ver no GitHub (em inglês) Feedback

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreatePushSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";
    String topicId = "your-topic-id";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    createPushSubscriptionExample(projectId, subscriptionId, topicId, pushEndpoint);
  }

  public static void createPushSubscriptionExample(
      String projectId, String subscriptionId, String topicId, String pushEndpoint)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);
      PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(pushEndpoint).build();

      // Create a push subscription with default acknowledgement deadline of 10 seconds.
      // Messages not successfully acknowledged within 10 seconds will get resent by the server.
      Subscription subscription =
          subscriptionAdminClient.createSubscription(subscriptionName, topicName, pushConfig, 10);
      System.out.println("Created push subscription: " + subscription.getName());
    }
  }
}

Node.js

Antes de testar essa 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 Pub/Sub Node.js.

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

// 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 createPushSubscription() {
  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://${pubSubClient.projectId}.appspot.com/push`,
    },
  };

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

createPushSubscription().catch(console.error);

PHP

Antes de testar essa 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 Pub/Sub PHP.

Ver no GitHub (em inglês) 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([
        'pushConfig' => ['pushEndpoint' => $endpoint]
    ]);

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

Python

Antes de testar essa 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 Pub/Sub para Python (em inglês).

Ver no GitHub (em inglês) Feedback
from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# endpoint = "https://my-test-project.appspot.com/push"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

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

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

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

Ruby

Antes de testar essa 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 Pub/Sub Ruby.

# 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 usar propriedades de assinatura

Você pode definir as propriedades da assinatura ao criar ou atualizar uma assinatura. Para mais informações sobre como configurar propriedades de assinatura com a ferramenta de linha de comando gcloud, consulte as sinalizações opcionais gcloud pubsub subscriptions create ou gcloud pubsub subscriptions update.

As assinaturas têm as seguintes propriedades:

Property Descrição Padrão
Método de exibição

Você pode receber mensagens com entrega pull ou push. Na entrega pull, o aplicativo do seu assinante inicia solicitações para o servidor do Pub/Sub para recuperar mensagens. Na entrega push, o Pub/Sub inicia solicitações para o aplicativo do seu assinante enviar mensagens.

Se não for especificado, as assinaturas do Pub/Sub usarão a entrega pull.

Prazo de confirmação

Se o seu código não reconhecer a mensagem antes do prazo, a mensagem será enviada novamente.

10 segundos é o prazo de confirmação padrão. O máximo é 10 minutos.

Duração da retenção da mensagem

A duração da retenção da mensagem especifica por quanto tempo o Pub/Sub retém as mensagens após a publicação. Após a duração da retenção de mensagens, o Pub/Sub pode descartar a mensagem, independentemente do estado de confirmação.

Para reter mensagens reconhecidas para a duração da retenção da mensagem, consulte Como reproduzir e descartar mensagens.

7 dias é a duração padrão da retenção de mensagens. O mínimo é 10 minutos e o máximo é 7 dias.
Tópicos com mensagens inativas

Quando um assinante não consegue confirmar uma mensagem, o Pub/Sub pode encaminhar a mensagem para um tópico de mensagem inativa. Para ver detalhes, consulte Encaminhar para tópicos de mensagens inativas.

Se você usar um tópico de mensagens inativas, não será possível ativar a ordem das mensagens.

Se você definir um tópico de mensagem inativa, também será possível especificar o número máximo de tentativas de entrega. O padrão é 5 tentativas de entrega, e você pode especificar de 5 a 100 tentativas.

Se você definir um tópico de mensagem inativa e o tópico estiver em um projeto diferente da assinatura, também será necessário especificar o ID do projeto com o tópico de mensagem inativa.

Período de expiração

As assinaturas sem atividade do assinante (como conexões abertas, pulls ativos ou pushes bem-sucedidos) expiram. Caso o Pub/Sub detecte atividade do assinante, o relógio de exclusão de assinatura será reiniciado.

31 dias é o período de expiração padrão. O mínimo é 1 dia.

Para evitar que uma assinatura expire, defina o período de expiração como never.

Política de repetição

Se o prazo de confirmação expirar ou um assinante responder com uma confirmação negativa, o Pub/Sub poderá enviar a mensagem novamente usando espera exponencial.

Se a política de nova tentativa não estiver definida, o Pub/Sub reenviará a mensagem assim que o prazo de confirmação expirar ou um assinante responder com uma confirmação negativa.

Se a duração máxima da retirada for definida, a duração mínima de retirada será de 10 segundos. Se a duração mínima de espera for definida, a duração máxima padrão de espera é de 600 segundos.

A duração de espera mais longa que você pode especificar é de 600 segundos.

Ordem das mensagens

Se os editores enviarem mensagens com uma chave de ordem e a ordem das mensagens estiver definida, o Pub/Sub entrega as mensagens na ordem.

Se não for definido, o Pub/Sub não entregará mensagens em ordem, incluindo mensagens com chaves de ordenação.

Filtro

O filtro é uma string com uma expressão de filtragem. Se uma assinatura tiver um filtro, ela só entregará as mensagens correspondentes ao filtro. É possível filtrar mensagens pelos atributos.

Se não for especificada, a assinatura não filtrará as mensagens, e os inscritos receberão todas as mensagens.

Como usar políticas de repetição

Quando uma assinatura tem uma política de repetição, o Pub/Sub reenvia as mensagens da melhor forma possível. Você pode receber mensagens antes da duração mínima da retirada.

Se as mensagens estiverem em um lote e a assinatura tiver uma política de repetição, o Pub/Sub reenviará o lote quando uma das seguintes situações ocorrer:

  • O assinante envia uma confirmação negativa para cada mensagem no lote.
  • O prazo de confirmação expira.

Como modificar métodos de exibição

É possível alternar entre assinaturas de push e pull com o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub.

Console

  1. No Console do Cloud, acesse a página Assinaturas.

    Acessar a página "Assinaturas"

  2. Clique em ao lado da assinatura para atualizar.

  3. No menu de contexto, selecione Editar.

    O menu de contexto com a opção Editar destacada.

  4. Em Tipo de entrega, escolha Pull ou Push.

  5. Clique em Update.

gcloud

Para modificar o URL do endpoint de push, execute o comando modify-push-config:

gcloud pubsub subscriptions modify-push-config SUBSCRIPTION_ID
  --push-endpoint=PUSH_ENDPOINT

Se a assinatura já estiver usando a entrega por pull, a configuração do endpoint de push alternará o método para a entrega por push.

É possível alternar a entrega de push para pull alterando o endpoint de push para uma string vazia.

API

Para modificar o URL do endpoint de push, use o método projects.subscriptions.modifyPushConfig.

C++

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

namespace pubsub = google::cloud::pubsub;
[](pubsub::SubscriptionAdminClient client, std::string const& project_id,
   std::string const& subscription_id, std::string const& endpoint) {
  auto status = client.ModifyPushSubscription(
      pubsub::Subscription(project_id, std::move(subscription_id)),
      pubsub::PushConfigBuilder{}.set_push_endpoint(endpoint));
  if (!status.ok()) throw std::runtime_error(status.message());

  std::cout << "The subscription push configuration was successfully"
            << " modified\n";
}

Go

Antes de testar essa amostra, 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 Pub/Sub Go.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

func updateEndpoint(w io.Writer, projectID, subID string, endpoint string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// endpoint := "https://my-test-project.appspot.com/push"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	subConfig, err := client.Subscription(subID).Update(ctx, pubsub.SubscriptionConfigToUpdate{
		PushConfig: &pubsub.PushConfig{Endpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("Update: %v", err)
	}
	fmt.Fprintf(w, "Updated subscription config: %v\n", subConfig)
	return nil
}

Java

Antes de testar essa 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 Pub/Sub Java.

Ver no GitHub (em inglês) Feedback

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class UpdatePushConfigurationExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    updatePushConfigurationExample(projectId, subscriptionId, pushEndpoint);
  }

  public static void updatePushConfigurationExample(
      String projectId, String subscriptionId, String pushEndpoint) throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);
      PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(pushEndpoint).build();
      subscriptionAdminClient.modifyPushConfig(subscriptionName, pushConfig);
      Subscription subscription = subscriptionAdminClient.getSubscription(subscriptionName);
      System.out.println(
          "Updated push endpoint to: " + subscription.getPushConfig().getPushEndpoint());
    }
  }
}

Node.js

Antes de testar essa 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 Pub/Sub Node.js.

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

// 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 modifyPushConfig() {
  const options = {
    // Set to an HTTPS endpoint of your choice. If necessary, register
    // (authorize) the domain on which the server is hosted.
    pushEndpoint: `https://${pubSubClient.projectId}.appspot.com/push`,
  };

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

modifyPushConfig().catch(console.error);

Python

Antes de testar essa 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 Pub/Sub para Python (em inglês).

Ver no GitHub (em inglês) Feedback
from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# endpoint = "https://my-test-project.appspot.com/push"

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

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

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

update_mask = {"paths": {"push_config"}}

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    result = subscriber.update_subscription(
        request={"subscription": subscription, "update_mask": update_mask}
    )

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

Ruby

Antes de testar essa 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 Pub/Sub Ruby.

# 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."

Se a assinatura já estiver usando a entrega por pull, a configuração do endpoint de push alternará o método para a entrega por push.

É possível alternar a entrega de push para pull alterando o endpoint de push para uma string vazia.

Como listar assinaturas

É possível listar as assinaturas em um projeto do Google Cloud com o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub.

Console

Para listar as assinaturas em um projeto, acesse a página Assinaturas.

Acessar a página "Assinaturas"

gcloud

Para listar as assinaturas em um projeto do Google Cloud, execute o comando gcloud pubsub subscriptions list:

gcloud pubsub subscriptions list
   [--project=PROJECT_ID]

API

Para listar as assinaturas em um projeto do Google Cloud, use o método projects.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 Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.

Ver no GitHub (em inglês) Feedback
namespace pubsub = google::cloud::pubsub;
[](pubsub::SubscriptionAdminClient client, std::string const& project_id) {
  int count = 0;
  for (auto const& subscription : client.ListSubscriptions(project_id)) {
    if (!subscription)
      throw std::runtime_error(subscription.status().message());
    std::cout << "Subscription Name: " << subscription->name() << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No subscriptions found in project " << project_id << "\n";
  }
}

C#

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


using Google.Api.Gax.ResourceNames;
using Google.Cloud.PubSub.V1;
using System.Collections.Generic;

public class ListSubscriptionsSample
{
    public IEnumerable<Subscription> ListSubscriptions(string projectId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        ProjectName projectName = ProjectName.FromProject(projectId);
        var subscriptions = subscriber.ListSubscriptions(projectName);
        return subscriptions;
    }
}

Go

Antes de testar essa amostra, 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 Pub/Sub Go.

import (
	"context"
	"fmt"

	"cloud.google.com/go/pubsub"
	"google.golang.org/api/iterator"
)

func list(projectID string) ([]*pubsub.Subscription, 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)
	}

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

Java

Antes de testar essa 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 Pub/Sub Java.

Ver no GitHub (em inglês) Feedback

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.ProjectName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class ListSubscriptionsInProjectExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";

    listSubscriptionInProjectExample(projectId);
  }

  public static void listSubscriptionInProjectExample(String projectId) throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      ProjectName projectName = ProjectName.of(projectId);
      for (Subscription subscription :
          subscriptionAdminClient.listSubscriptions(projectName).iterateAll()) {
        System.out.println(subscription.getName());
      }
      System.out.println("Listed all the subscriptions in the project.");
    }
  }
}

Node.js

Antes de testar essa 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 Pub/Sub Node.js.

Ver no GitHub (em inglês) Feedback
// 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 listSubscriptions() {
  // Lists all subscriptions in the current project
  const [subscriptions] = await pubSubClient.getSubscriptions();
  console.log('Subscriptions:');
  subscriptions.forEach(subscription => console.log(subscription.name));
}

listSubscriptions().catch(console.error);

PHP

Antes de testar essa 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 Pub/Sub PHP.

Ver no GitHub (em inglês) 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 essa 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 Pub/Sub para Python (em inglês).

Ver no GitHub (em inglês) Feedback
from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"

subscriber = pubsub_v1.SubscriberClient()
project_path = f"projects/{project_id}"

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    for subscription in subscriber.list_subscriptions(
        request={"project": project_path}
    ):
        print(subscription.name)

Ruby

Antes de testar essa 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 Pub/Sub Ruby.

# 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

É possível listar as assinaturas de um tópico com o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub.

Console

  1. No Console do Cloud, acesse a página Tópicos.

    Acessar a página "Tópicos"

  2. Selecione um ID de tópico para abrir a página Detalhes do tópico. A seção Assinaturas da página inclui uma lista de assinaturas do tópico.

gcloud

Para listar as assinaturas em um projeto do Google Cloud, execute o comando gcloud pubsub topics list-subscriptions:

gcloud pubsub topics list-subscriptions TOPIC_ID

API

Para listar as assinaturas em um projeto do Google Cloud, use o método projects.topics.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 Pub/Sub: 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) {
  auto const topic =
      pubsub::Topic(std::move(project_id), std::move(topic_id));
  std::cout << "Subscription list for topic " << topic << ":\n";
  for (auto const& name : client.ListTopicSubscriptions(topic)) {
    if (!name) throw std::runtime_error(name.status().message());
    std::cout << "  " << *name << "\n";
  }
}

Go

Antes de testar essa amostra, 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 Pub/Sub Go.

import (
	"context"
	"fmt"

	"cloud.google.com/go/pubsub"
	"google.golang.org/api/iterator"
)

func listSubscriptions(projectID, topicID string) ([]*pubsub.Subscription, error) {
	// projectID := "my-project-id"
	// topicName := "projects/sample-248520/topics/ocr-go-test-topic"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
	}

	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, fmt.Errorf("Next: %v", err)
		}
		subs = append(subs, sub)
	}
	return subs, nil
}

Java

Antes de testar essa 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 Pub/Sub Java.

Ver no GitHub (em inglês) Feedback

import com.google.cloud.pubsub.v1.TopicAdminClient;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class ListSubscriptionsInTopicExample {
  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";

    listSubscriptionInTopicExample(projectId, topicId);
  }

  public static void listSubscriptionInTopicExample(String projectId, String topicId)
      throws IOException {
    try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      for (String subscription : topicAdminClient.listTopicSubscriptions(topicName).iterateAll()) {
        System.out.println(subscription);
      }
      System.out.println("Listed all the subscriptions in the topic.");
    }
  }
}

Node.js

Antes de testar essa 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 Pub/Sub Node.js.

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';

// 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 listTopicSubscriptions() {
  // Lists all subscriptions for the topic
  const [subscriptions] = await pubSubClient
    .topic(topicName)
    .getSubscriptions();

  console.log(`Subscriptions for ${topicName}:`);
  subscriptions.forEach(subscription => console.log(subscription.name));
}

listTopicSubscriptions().catch(console.error);

Python

Antes de testar essa 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 Pub/Sub para Python (em inglês).

Ver no GitHub (em inglês) Feedback
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)

response = publisher.list_topic_subscriptions(request={"topic": topic_path})
for subscription in response:
    print(subscription)

Ruby

Antes de testar essa 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 Pub/Sub Ruby.

# 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

É possível excluir assinaturas com o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub.

Console

  1. No Console do Cloud, acesse a página Assinaturas.

    Acessar a página "Assinaturas"

  2. Selecione a assinatura a ser excluída.

  3. Clique em Excluir.

gcloud

Para excluir uma assinatura, execute o comando gcloud pubsub subscriptions delete:

gcloud pubsub subscriptions delete SUBSCRIPTION_ID

API

Para excluir uma assinatura, use o método projects.topics.subscriptions.delete.

C++

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

Ver no GitHub (em inglês) Feedback
namespace pubsub = google::cloud::pubsub;
[](pubsub::SubscriptionAdminClient client, std::string const& project_id,
   std::string const& subscription_id) {
  auto status = client.DeleteSubscription(pubsub::Subscription(
      std::move(project_id), std::move(subscription_id)));
  // Note that kNotFound is a possible result when the library retries.
  if (status.code() == google::cloud::StatusCode::kNotFound) {
    std::cout << "The subscription was not found\n";
    return;
  }
  if (!status.ok()) throw std::runtime_error(status.message());

  std::cout << "The subscription was successfully deleted\n";
}

C#

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


using Google.Cloud.PubSub.V1;

public class DeleteSubscriptionSample
{
    public void DeleteSubscription(string projectId, string subscriptionId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        subscriber.DeleteSubscription(subscriptionName);
    }
}

Go

Antes de testar essa amostra, 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 Pub/Sub Go.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

func delete(w io.Writer, projectID, subID string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %v", err)
	}

	sub := client.Subscription(subID)
	if err := sub.Delete(ctx); err != nil {
		return fmt.Errorf("Delete: %v", err)
	}
	fmt.Fprintf(w, "Subscription %q deleted.", subID)
	return nil
}

Java

Antes de testar essa 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 Pub/Sub Java.

Ver no GitHub (em inglês) Feedback

import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.ProjectSubscriptionName;
import java.io.IOException;

public class DeleteSubscriptionExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";

    deleteSubscriptionExample(projectId, subscriptionId);
  }

  public static void deleteSubscriptionExample(String projectId, String subscriptionId)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);
      try {
        subscriptionAdminClient.deleteSubscription(subscriptionName);
        System.out.println("Deleted subscription.");
      } catch (NotFoundException e) {
        System.out.println(e.getMessage());
      }
    }
  }
}

Node.js

Antes de testar essa 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 Pub/Sub Node.js.

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';

// 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 deleteSubscription() {
  // Deletes the subscription
  await pubSubClient.subscription(subscriptionName).delete();
  console.log(`Subscription ${subscriptionName} deleted.`);
}

deleteSubscription().catch(console.error);

PHP

Antes de testar essa 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 Pub/Sub PHP.

Ver no GitHub (em inglês) 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 essa 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 Pub/Sub para Python (em inglês).

Ver no GitHub (em inglês) Feedback
from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# subscription_id = "your-subscription-id"

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

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscriber.delete_subscription(request={"subscription": subscription_path})

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

Ruby

Antes de testar essa 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 Pub/Sub Ruby.

# 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 recurso

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

projects/project-identifier/collection/relative-name

O identificador do projeto precisa ser o ID do projeto, disponível no Console do Google Cloud. Por exemplo, projects/myproject/topics/mytopic;

A coleção precisa ser subscriptions ou topics.

O nome relativo precisa:

  • não começar com a string goog;
  • começar com uma letra;
  • conter entre 3 e 255 caracteres;
  • conter apenas os caracteres a seguir:

    • 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 sem codificação para URLs. Mas, é preciso garantir que os caracteres sejam codificados/decodificados corretamente quando usados em URLs. Por exemplo, mi-tópico é um nome relativo inválido. No entanto, mi-t%C3%B3pico é válido.

      Isso é particularmente importante para chamadas REST.