Criar assinaturas de pull

Este documento descreve como criar uma assinatura por pull. É possível usar o Google Cloud console, a Google Cloud CLI, a biblioteca de cliente ou a API Pub/Sub para criar uma assinatura por pull.

Antes de começar

• Saiba mais sobre assinaturas.
• Avalie se sua empresa precisa de uma assinatura por pull.
• Entenda como as assinaturas de pull funcionam.

Papéis e permissões necessárias

Para receber as permissões necessárias para criar uma assinatura de pull, peça ao administrador para conceder a você o papel do IAM de Editor do Pub/Sub (roles/pubsub.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar uma assinatura por pull. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar uma assinatura por pull:

• pubsub.subscriptions.create no projeto
• pubsub.topics.attachSubscription no tópico

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

Assinaturas entre projetos

Se você criar uma assinatura em um projeto para um tópico em outro projeto, será necessário ter a permissão pubsub.subscriptions.create no projeto em que você está criando a assinatura e a permissão pubsub.topics.attachSubscription no tópico.

Criar uma assinatura por pull

Console

Para criar uma assinatura por pull, siga estas etapas:

1. No Google Cloud console, acesse a página Assinaturas.

   Acessar "Assinaturas"

2. Clique em Criar assinatura.

3. No campo ID da assinatura, insira um nome.

   Para informações sobre como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.

4. Na lista Tópico do Pub/Sub, selecione um tópico para a assinatura ler.

5. Em Tipo de entrega, selecione Pull.

6. Opcional: na seção Transformações , adicione uma ou mais transformações de mensagem única (SMTs, na sigla em inglês). Para mais informações, consulte Criar uma assinatura com SMTs.

7. Opcional: no campo Filtro, insira uma expressão de filtro para filtrar mensagens da assinatura. Para mais informações, consulte Filtrar mensagens de uma assinatura.

8. Em Política de nova tentativa, selecione uma opção. Para mais informações, consulte Política de nova tentativa de assinatura.

9. Opcional: ative um tópico de mensagens inativas para receber mensagens não entregues.

   1. Marque a caixa de seleção Mensagens mortas.

   2. Na lista Tópico de mensagens mortas, selecione ou crie o tópico de mensagens mortas.

   3. No campo Número máximo de tentativas de entrega, insira o número máximo de tentativas de entrega.

10. Opcional: na seção Propriedades de entrega, ative ou desative as seguintes opções de entrega:

    • Entrega única

    • Ordem das mensagens

11. Opcional: na seção Prazo de confirmação, defina o prazo para o assinante processar e confirmar as mensagens. Para mais informações, consulte Estender o tempo de confirmação com o gerenciamento de concessão.

12. Opcional: na seção Opções de vida útil, configure por quanto tempo a assinatura retém as mensagens.

    1. Na seção Duração da retenção de mensagens, especifique por quanto tempo as mensagens não confirmadas são retidas.

    2. Para reter mensagens confirmadas e não confirmadas, marque a caixa de seleção Retain acknowledged messages (Reter mensagens confirmadas).

    Para mais informações, consulte Configurar a retenção de mensagens para uma assinatura.

13. Opcional: em Período de validade, selecione uma opção:

    1. Para definir a expiração da assinatura, marque a caixa de seleção Expire after this many days of inactivity (Expirar após tantos dias de inatividade). Insira o número de dias que a assinatura pode permanecer inativa antes que o Pub/Sub a exclua.

    2. Para desativar a expiração da assinatura, marque a caixa de seleção Never expire (Nunca expirar).

    Para mais informações, consulte Expiração da assinatura.

14. 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 Google Cloud console, acesse a página Tópicos.

   Acesse Tópicos

2. Clique em ao lado do tópico em que você quer criar uma assinatura.

3. No menu de contexto, selecione Criar assinatura.

4. Na página Adicionar assinatura ao tópico, conclua as etapas descritas no procedimento anterior. O ID do tópico é preenchido automaticamente.

gcloud

1. No Google Cloud console, ative o Cloud Shell.

   Ativar o Cloud Shell

   Na parte de baixo do Google Cloud console, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

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

   gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

   Substitua:

   • SUBSCRIPTION_ID: o nome ou ID da nova assinatura por pull.
   • TOPIC_ID: o nome ou ID do tópico.

REST

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

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 atual: gcloud auth application-default print-access-token.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer ACCESS_TOKEN

Corpo da solicitação:

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

Em que:

• PROJECT_ID é o ID do projeto.
• SUBSCRIPTION_ID é o ID da assinatura.
• TOPIC_ID é o ID do tópico.

Resposta:

{
"name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
"pushConfig": {},
"ackDeadlineSeconds": 10,
"messageRetentionDuration": "604800s",
"expirationPolicy": {
"ttl": "2678400s"
}
}

C++

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

namespace pubsub_admin = ::google::cloud::pubsub_admin;
namespace pubsub = ::google::cloud::pubsub;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  auto sub = client.CreateSubscription(request);
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::move(sub).status();

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

C#

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

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

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

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

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

import (
	"context"
	"fmt"
	"io"

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

func create(w io.Writer, projectID, topic, subscription string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription: %v\n", sub)
	return nil
}

Java

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

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.SubscriptionName;
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);
      SubscriptionName subscriptionName = SubscriptionName.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 tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub para Node.js (em inglês).

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';

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

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createSubscription(topicNameOrId, subscriptionNameOrId) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

Node.ts

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';

// Imports the Google Cloud client library
import {PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createSubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

PHP

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

use Google\Cloud\PubSub\PubSubClient;

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

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# 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(f"Subscription created: {subscription}")

Ruby

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

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

# topic_id        = "your-topic-id"
# subscription_id = "your-subscription-id"

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

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id)

puts "Pull subscription #{subscription_id} created."

Monitorar assinaturas por pull

O Cloud Monitoring fornece várias métricas para monitorar assinaturas.

Para uma lista de todas as métricas disponíveis relacionadas ao Pub/Sub e suas descrições, consulte a documentação do Monitoring para o Pub/Sub.

Também é possível monitorar assinaturas no Pub/Sub.

A seguir

• Receber mensagens de uma assinatura por pull.
• Criar ou modificar uma assinatura com gcloud comandos.
• Criar ou modificar uma assinatura com APIs REST.