Crea suscripciones de extracción

En este documento, se describe cómo crear una suscripción de extracción. Puedes usar la Google Cloud consola, Google Cloud CLI, la biblioteca cliente o la API de Pub/Sub para crear una suscripción de extracción.

Antes de comenzar

• Obtén información sobre las suscripciones.
• Evalúa si tu empresa requiere una suscripción de extracción.
• Comprende cómo funcionan las suscripciones de extracción.

Roles y permisos requeridos

Para obtener los permisos que necesitas para crear una suscripción de extracción, pídele a tu administrador que te otorgue el rol de IAM Editor de Pub/Sub (roles/pubsub.editor) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear una suscripción de extracción. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear una suscripción de extracción:

• pubsub.subscriptions.create en el proyecto
• pubsub.topics.attachSubscription en el tema

También puedes obtener estos permisos con roles personalizados o otros roles predefinidos.

Suscripciones entre proyectos

Si creas una suscripción en un proyecto para un tema en otro proyecto, debes tener el permiso pubsub.subscriptions.create en el proyecto en el que creas la suscripción y el permiso pubsub.topics.attachSubscription en el tema.

Crea una suscripción de extracción

Console

Para crear una suscripción de extracción, sigue estos pasos:

1. En la Google Cloud consola, ve a la página Suscripciones.

   Ir a Suscripciones

2. Haz clic en Crear suscripción.

3. En el campo ID de suscripción, ingresa un nombre.

   Para obtener información sobre cómo asignar un nombre a una suscripción, consulta los Lineamientos para asignar un nombre a un tema o una suscripción.

4. En la lista Tema de Pub/Sub, selecciona un tema del que la suscripción leerá.

5. En Tipo de entrega, selecciona Extraer.

6. Opcional: En la sección Transformaciones, agrega una o más transformaciones de mensajes únicos (SMT). Para obtener más información, consulta Crea una suscripción con SMT.

7. Opcional: En el campo Filtro, ingresa una expresión de filtro para filtrar mensajes de la suscripción. Para obtener más información, consulta Filtra mensajes de una suscripción.

8. En Política de reintento, selecciona una opción. Para obtener más información, consulta Política de reintento de suscripción.

9. Opcional: Habilita un tema de mensajes no entregados para recibir mensajes que no se pueden entregar.

   1. Selecciona la casilla de verificación Mensajes no entregados.

   2. En la lista Tema de mensajes no entregados, selecciona o crea el tema de mensajes no entregados.

   3. En el campo Cantidad máxima de intentos de entrega, ingresa la cantidad máxima de intentos de entrega.

10. Opcional: En la sección Propiedades de entrega, habilita o inhabilita las siguientes opciones de entrega:

    • Entrega “exactamente una vez”

    • Ordenamiento de mensajes

11. Opcional: En la sección Plazo de confirmación, establece el plazo para que el suscriptor procese y confirme los mensajes. Para obtener más información, consulta Extiende el tiempo de confirmación con la administración de arrendamientos.

12. Opcional: En la sección Opciones de ciclo de vida, configura cuánto tiempo la suscripción retiene los mensajes.

    1. En la sección Duración de la retención de mensajes, especifica cuánto tiempo se retienen los mensajes no confirmados.

    2. Para retener los mensajes confirmados y los no confirmados, selecciona la casilla de verificación Retener mensajes confirmados.

    Para obtener más información, consulta Configura la retención de mensajes para una suscripción.

13. Opcional: En Período de vencimiento, selecciona una opción:

    1. Para establecer el vencimiento de la suscripción, selecciona la casilla de verificación Vence después de esta cantidad de días de inactividad. Ingresa la cantidad de días que la suscripción puede permanecer inactiva antes de que Pub/Sub la borre.

    2. Para inhabilitar el vencimiento de la suscripción, selecciona la casilla de verificación Nunca vence.

    Para obtener más información, consulta Vencimiento de la suscripción.

14. Haz clic en Crear.

Desde la sección Temas también puedes crear una suscripción. Este acceso directo es útil para asociar temas a suscripciones.

1. En la Google Cloud consola, ve a la página Temas.

   Ir a temas

2. Haz clic en junto al tema en el que deseas crear una suscripción.

3. En el menú contextual, selecciona Crear suscripción (Create subscription).

4. En la página Agregar suscripción al tema, completa los pasos que se describen en el procedimiento anterior. El ID del tema se completa automáticamente.

gcloud

1. En la Google Cloud consola, activa Cloud Shell.

   Activa Cloud Shell

   En la parte inferior de la Google Cloud consola, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

2. Para crear una suscripción de extracción, ejecuta el gcloud pubsub subscriptions create comando.

   gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

   Reemplaza lo siguiente:

   • SUBSCRIPTION_ID: Es el nombre o el ID de tu nueva suscripción de extracción.
   • TOPIC_ID: Es el nombre o el ID de tu tema.

REST

Para crear una suscripción de extracción, usa el projects.subscriptions.create método:

Solicitud:

La solicitud debe autenticarse con un token de acceso en el encabezado Authorization. Para obtener un token de acceso para las credenciales predeterminadas actuales de la aplicación: gcloud auth application-default print-access-token.

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

Cuerpo de la solicitud:

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

Aquí:

• PROJECT_ID es el ID del proyecto.
• SUBSCRIPTION_ID es el ID de la suscripción.
• TOPIC_ID es el ID del tema.

Respuesta:

{
"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 probar esta muestra, sigue las instrucciones de configuración de C++ en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de 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 probar esta muestra, sigue las instrucciones de configuración de C# en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de 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

En la siguiente muestra, se usa la versión principal de la biblioteca cliente de Go Pub/Sub (v2). Si aún usas la biblioteca v1, consulta la guía de migración a la v2. Para ver una lista de ejemplos de código de la v1, consulta los ejemplos de código obsoletos.

Antes de probar esta muestra, sigue las instrucciones de configuración de Go en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para 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 probar esta muestra, sigue las instrucciones de configuración de Java en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Java .

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 probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para 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.ts

Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para 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 probar esta muestra, sigue las instrucciones de configuración de PHP en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de 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 probar esta muestra, sigue las instrucciones de configuración de Python en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Python de 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

En la siguiente muestra, se usa la biblioteca cliente de Ruby Pub/Sub v3. Si aún usas la biblioteca v2, consulta la guía de migración a la v3. Para ver una lista de ejemplos de código de la v2 de Ruby, consulta los ejemplos de código obsoletos.

Antes de probar esta muestra, sigue las instrucciones de configuración de Ruby en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para 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."

Supervisa las suscripciones de extracción

Cloud Monitoring proporciona varias métricas para supervisar las suscripciones.

Para obtener una lista de todas las métricas disponibles relacionadas con Pub/Sub y sus descripciones, consulta la documentación de Monitoring para Pub/Sub.

También puedes supervisar las suscripciones desde Pub/Sub.

¿Qué sigue?

• Recibe mensajes de una suscripción de extracción.
• Crea o modifica una suscripción con gcloud comandos.
• Crea o modifica una suscripción con las APIs de REST.