Crea suscripciones de extracción

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

Antes de comenzar

Roles y permisos requeridos

Para crear una suscripción, debes configurar el control de acceso a nivel de proyecto. También necesitas permisos a nivel de recursos si tus suscripciones y temas se encuentran en proyectos diferentes, como se explica más adelante en esta sección.

Si quieres obtener los permisos que necesitas para crear suscripciones 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.

Este rol predefinido contiene los permisos necesarios para crear suscripciones 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 suscripciones de extracción:

  • Extraer de una suscripción: pubsub.subscriptions.consume
  • Crea una suscripción: pubsub.subscriptions.create
  • Borrar una suscripción: pubsub.subscriptions.delete
  • Obtener una suscripción: pubsub.subscriptions.get
  • Muestra una suscripción: pubsub.subscriptions.list
  • Actualiza una suscripción: pubsub.subscriptions.update
  • Adjuntar una suscripción a un tema: pubsub.topics.attachSubscription
  • Obtén la política de IAM de una suscripción: pubsub.subscriptions.getIamPolicy
  • Configura la política de IAM para una suscripción: pubsub.subscriptions.setIamPolicy

Es posible que también puedas obtener estos permisos con funciones personalizadas o con otras funciones predefinidas.

Si necesitas crear suscripciones de extracción en un proyecto que estén asociados con un tema de otro proyecto, pídele al administrador de temas que también te otorgue el rol de IAM (roles/pubsub.editor) del editor de Pub/Sub en el tema.

Propiedades de la suscripción de extracción

Cuando configuras una suscripción de extracción, puedes especificar las siguientes propiedades.

Propiedades comunes

Obtén información sobre las propiedades de suscripción comunes que puedes configurar en todas las suscripciones.

Entrega “exactamente una vez”

Entrega “exactamente una vez”. Si se configura, Pub/Sub entrega garantías de entrega exactamente una vez. Si no se especifica, la suscripción admite la entrega al menos una vez para cada mensaje.

Crea una suscripción de extracción

En los siguientes ejemplos, se muestra cómo crear una suscripción con entrega de extracción mediante la configuración predeterminada proporcionada.

Console

Para crear una suscripción de extracción, completa los siguientes pasos.

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

    Ir a Suscripciones

  2. Haz clic en Crear suscripción.

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

    Si quieres obtener información para asignarle un nombre a una suscripción, consulta Lineamientos para asignar el nombre de un tema o una suscripción.

  4. Elige o crea un tema desde el menú desplegable. La suscripción recibe mensajes del tema.
  5. Mantén el Tipo de entrega como Extracción.
  6. Conserva todos los demás valores predeterminados.
  7. 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 consola de Google Cloud, ve a la página Temas.

    Ir a temas

  2. Haz clic en junto al tema para crear una suscripción.
  3. En el menú contextual, selecciona Crear suscripción (Create subscription).

  4. Ingresa el ID de suscripción.

    Si quieres obtener información para asignarle un nombre a una suscripción, consulta Lineamientos para asignar el nombre de un tema o una suscripción.

  5. Mantén el Tipo de entrega como Extracción.
  6. Conserva todos los demás valores predeterminados.
  7. Haz clic en Crear.

gcloud

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

    Activar Cloud Shell

    En la parte inferior de la consola de Google Cloud, 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 comando gcloud pubsub subscriptions create. 
    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

    Reemplaza lo siguiente:

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

REST

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

Solicitud:

La solicitud se debe autenticar con un token de acceso en el encabezado Authorization. A fin de obtener un token de acceso para las credenciales predeterminadas actuales de la aplicación, usa lo siguiente: 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++ que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub C++.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar esta muestra, sigue las instrucciones de configuración de C# que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub C#.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar esta muestra, sigue las instrucciones de configuración de Go que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Go.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar esta muestra, sigue las instrucciones de configuración de Java que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Java.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar esta muestra, sigue las instrucciones de configuración de PHP que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub PHP.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar esta muestra, sigue las instrucciones de configuración de Python que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Python.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar esta muestra, sigue las instrucciones de configuración de Ruby que se encuentran en la guía de inicio rápido de Pub/Sub con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub Ruby.

    Para autenticarte en Pub/Sub, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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."

    ¿Qué sigue?