Criar assinaturas de pull

Neste documento, descrevemos 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 funcionam as assinaturas pull.

Papéis e permissões necessárias

Para receber as permissões necessárias para criar uma assinatura de extração, 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 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 assunto

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

Assinaturas entre projetos

Se você criar uma assinatura em um projeto para um tópico em outro, será necessário ter a permissão pubsub.subscriptions.create no projeto em que a assinatura está sendo criada 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 console do Google Cloud , acesse a página Assinaturas.

   Acesse 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 envio, 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 novas tentativas, selecione uma opção. Para mais informações, consulte Política de novas tentativas de assinatura.

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

   1. Marque a caixa de seleção Mensagem morta.

   2. Na lista Tópico de dead-letter, selecione ou crie o tópico de dead-letter.

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

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

    • Entrega exatamente uma vez

    • 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ões.

12. Opcional: na seção Opções de ciclo de vida, configure por quanto tempo a assinatura vai reter mensagens.

    1. Na seção Período de retenção de mensagens, especifique por quanto tempo as mensagens não confirmadas serão retidas.

    2. Para reter mensagens confirmadas e não confirmadas, marque a caixa de seleção 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 Expirar após este número de dias de inatividade. Insira o número de dias que a assinatura pode ficar inativa antes de o Pub/Sub excluí-la.

    2. Para desativar a expiração da assinatura, marque a caixa de seleção 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 console do Google Cloud , acesse a página Tópicos.

   Acesse Tópicos

2. Clique em ao lado do tema 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 console do Google Cloud , ative o Cloud Shell.

   Ativar o Cloud Shell

   Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud 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 comando gcloud pubsub subscriptions create.

   gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

   Substitua:

   • SUBSCRIPTION_ID: o nome ou ID da sua nova assinatura de extração.
   • TOPIC_ID: o nome ou ID do tópico.

REST

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

Solicitação:

A solicitação precisa ser autenticada com um token de acesso no cabeçalho Authorization. Para receber um token de acesso para as Application Default Credentials atuais: 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 sua 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 para 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 para 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 Pub/Sub para Go (v2). Se você ainda estiver usando a biblioteca v1, consulte o guia de migração para a v2. Para conferir uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.

Antes de testar esta amostra, siga as instruções de configuração do Go no 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 para 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 descontinuados.

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

Rust

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

use google_cloud_pubsub::client::SubscriptionAdmin;

pub async fn sample(
    client: &SubscriptionAdmin,
    project_id: &str,
    topic_id: &str,
    subscription_id: &str,
) -> anyhow::Result<()> {
    let subscription_name = format!("projects/{project_id}/subscriptions/{subscription_id}");
    let topic_name = format!("projects/{project_id}/topics/{topic_id}");

    let subscription = client
        .create_subscription()
        .set_name(subscription_name)
        .set_topic(topic_name)
        .send()
        .await?;

    println!("successfully created subscription {subscription:?}");
    Ok(())
}

Monitorar assinaturas de pull

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

Para conferir 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.
• Crie ou modifique uma assinatura com comandos gcloud.
• Crie ou modifique uma assinatura com APIs REST.