Criar assinaturas de pull

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

Antes de começar

Papéis e permissões necessárias

Para criar uma assinatura, configure o controle de acesso no nível do projeto. Você também precisa de permissões no nível do recurso se suas assinaturas e tópicos estão em projetos diferentes, conforme discutido mais adiante nesta seção.

Para ter as permissões necessárias para criar assinaturas de pull, peça ao administrador para conceder a você Papel do IAM 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 assinaturas de pull. Para conferir 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 assinaturas de pull:

  • Extrair de uma assinatura: pubsub.subscriptions.consume
  • Crie uma assinatura: pubsub.subscriptions.create
  • Para excluir uma assinatura: pubsub.subscriptions.delete
  • Receber uma assinatura: pubsub.subscriptions.get
  • Para listar uma assinatura: pubsub.subscriptions.list
  • Atualizar uma assinatura: pubsub.subscriptions.update
  • Anexe uma assinatura a um tópico: pubsub.topics.attachSubscription
  • Para receber a política do IAM de uma assinatura: pubsub.subscriptions.getIamPolicy
  • Configure a política do IAM para uma assinatura: pubsub.subscriptions.setIamPolicy

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

Se você precisar criar assinaturas de um projeto que estão associadas a um tópico em outro projeto, peça ao administrador do tópico para conceder a você o papel Editor do Pub/Sub (roles/pubsub.editor) no tópico.

Propriedades da assinatura de pull

Ao configurar uma assinatura de pull, é possível especificar o seguinte propriedades.

Propriedades comuns

Saiba mais sobre as propriedades comuns de assinaturas que você pode definir em todas as assinaturas.

Entrega "exatamente uma vez"

Entrega exatamente uma vez. Se definido, o Pub/Sub cumpre as garantias de envio exatamente uma vez. Se não for especificada, a assinatura terá suporte entrega pelo menos uma vez para cada mensagem.

Criar uma assinatura por pull

Os exemplos a seguir demonstram como criar uma assinatura com pull usando as configurações padrão fornecidas.

Console

Para criar uma assinatura de pull, conclua as etapas a seguir.

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

    Acessar "Assinaturas"

  2. Clique em Criar assinatura.

  3. Insira um nome no campo ID da assinatura.

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

  4. Escolha ou crie um tópico no menu suspenso. A assinatura recebe mensagens do tópico.
  5. Mantenha o Delivery type como Pull.
  6. Mantenha todos os outros valores padrão.
  7. 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 tópico para criar uma assinatura.
  3. No menu de contexto, selecione Criar assinatura.

  4. Insira o ID da assinatura.

    Para saber como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.

  5. Mantenha o Delivery type como Pull.
  6. Mantenha todos os outros valores padrão.
  7. Clique em Criar.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Para criar uma assinatura de pull, execute o comando gcloud pubsub subscriptions create. 
    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

    Substitua:

    • SUBSCRIPTION_ID: o nome ou o ID do novo pull assinatura.
    • TOPIC_ID: o nome ou o ID do tópico.

REST

Para criar uma assinatura de pull, use o projects.subscriptions.create:

Solicitação:

A solicitação deve 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 testar esta amostra, 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 API C++ do Pub/Sub documentação de referência.

    Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

    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 testar este exemplo, siga as instruções de configuração do C# na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a API C# do Pub/Sub documentação de referência.

    Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

    
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 este exemplo, siga as instruções de configuração do Go na 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 Go.

    Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

    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: %w", err)
	}
	defer client.Close()

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

    Java

    Antes de testar este exemplo, siga as instruções de configuração do Java na Guia de início rápido do Pub/Sub usando bibliotecas de cliente. Para mais informações, consulte a API Java do Pub/Sub documentação de referência.

    Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

    
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

    /**
 * 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.js

    /**
 * 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 testar este exemplo, siga as instruções de configuração do PHP na 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.

    Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

    use Google\Cloud\PubSub\PubSubClient;

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

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

    Python

    Antes de testar este exemplo, siga as instruções de configuração do Python na 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 Python.

    Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

    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

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

    Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

pubsub = Google::Cloud::Pubsub.new

topic        = pubsub.topic topic_id
subscription = topic.subscribe subscription_id

puts "Pull subscription #{subscription_id} created."

    Monitorar assinaturas de 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 as descrições deles, consulte Documentação de monitoramento do Pub/Sub.

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

    A seguir