Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Crea suscripciones de envío

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

Antes de comenzar

Obtén información sobre las suscripciones.
Comprende cómo funcionan las suscripciones de envío.

Roles y permisos requeridos

Para obtener los permisos que necesitas para crear una suscripción de envío, 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 envío. 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 envío:

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.

Propiedades de la suscripción de envío

Las suscripciones de envío admiten todas las propiedades de suscripción comunes. En las siguientes secciones, se describen las propiedades específicas de las suscripciones de envío.

Extremos

URL del extremo (obligatorio). Una dirección HTTPS de acceso público. El servidor para el extremo de envío debe tener un certificado SSL válido firmado por una autoridad certificada. El servicio Pub/Sub entrega mensajes a los extremos de envío desde la misma Google Cloud región en la que el servicio de Pub/Sub almacena los mensajes. El servicio Pub/Sub entrega mensajes de la misma Google Cloud región según el criterio del mejor esfuerzo.

Si los suscriptores usan un firewall, no pueden recibir solicitudes de envío. Para recibir solicitudes de envío, debes desactivar el firewall y verificar el token web JSON (JWT) que se usa en la solicitud. Si un suscriptor tiene un firewall, es posible que recibas un error 403 permission denied.
Pub/Sub no requiere títulos de propiedad para los dominios URL de suscripción de envío. Si tu dominio recibe solicitudes POST de Pub/Sub inesperadas, puedes informar sospechas de abuso.

Autenticación

Habilitar la autenticación Cuando se habilita, los mensajes que Pub/Sub entrega al extremo de envío incluyen un encabezado de autorización para permitir que el extremo autentique la solicitud. Los mecanismos de autenticación y autorización automáticos están disponibles para los extremos del entorno estándar de App Engine y Cloud Run Functions alojados en el mismo proyecto que la suscripción.

La configuración de autenticación para una suscripción de envío autenticada consta de una cuenta de servicio administrada por el usuario y los parámetros de público que se especifican en una llamada create, patch o ModifyPushConfig. También debes otorgar un rol específico a una cuenta de servicio, como se explica en la siguiente sección.

Público. Es una cadena única, que no distingue entre mayúsculas y minúsculas y que el webhook usa para validar el público objetivo de este token en particular.
Cuenta de servicio. Pub/Sub crea automáticamente una cuenta de servicio para ti con el formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Requisitos previos para habilitar la autenticación

La cuenta de servicio administrada por el usuario es la cuenta de servicio asociada con la suscripción de envío. Esta cuenta se usa como la declaración email del token web JSON (JWT) generado. A continuación, se muestra una lista de requisitos para la cuenta de servicio:

Esta cuenta de servicio administrada por el usuario debe estar en el mismo proyecto que la suscripción de envío.
La principal que crea o modifica la suscripción de envío debe tener el permiso iam.serviceAccounts.actAs en la cuenta de servicio administrada por el usuario para conectar la cuenta de servicio a la suscripción de envío. Para obtener más información, consulta Conecta cuentas de servicio a recursos.
Permisos necesarios: Se debe otorgar a esta cuenta de servicio el iam.serviceAccounts.getOpenIdToken permiso (incluido en el roles/iam.serviceAccountTokenCreatorrol) para permitir que Pub/Sub cree tokens JWT para la cuenta de servicio especificada para autenticar solicitudes de envío.

Separación de la carga útil

La opción Habilitar la separación de la carga útil quita todos los metadatos de los mensajes de Pub/Sub, excepto los datos del mensaje. Con la separación de la carga útil, los datos del mensaje se entregan directamente como el cuerpo HTTP.

También puedes habilitar la opción Escribir los metadatos. La opción Escribir los metadatos vuelve a agregar los metadatos del mensaje que se quitaron anteriormente al encabezado de la solicitud.

Entrega a direcciones de VPC privadas

Pub/Sub opera fuera de las redes de VPC y no puede enviar mensajes directamente a direcciones de VPC privadas. Sin embargo, puedes usar Eventarc para enrutar mensajes a servicios dentro de tu VPC. Pub/Sub puede enviar mensajes a un activador de Eventarc, que luego puede reenviarlos a un servicio dentro de tu VPC, como un servicio de Cloud Run o una ejecución de Workflows. Para obtener más información, consulta la documentación de Eventarc.

Controles del servicio de VPC

Para un proyecto protegido por los Controles del servicio de VPC, ten en cuenta las siguientes limitaciones para las suscripciones de envío:

Solo puedes crear suscripciones de envío nuevas para las que el extremo de envío esté configurado en un servicio de Cloud Run con una URL run.app predeterminada o una ejecución de Workflows. Los dominios personalizados no funcionan.
Cuando enrutas eventos a través de Eventarc a destinos de Workflows para los que el extremo de envío está configurado en una ejecución de Workflows, solo puedes crear suscripciones de envío nuevas a través de Eventarc.
No puedes actualizar las suscripciones de envío existentes. Estas suscripciones de envío continúan funcionando, aunque no están protegidas por los Controles del servicio de VPC.

Crea una suscripción de envío

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

De forma predeterminada, las suscripciones usan la entrega de extracción, a menos que configures explícitamente una configuración de envío, como se muestra en los siguientes ejemplos.

Console

Para crear una suscripción de envío, realiza los pasos que se indican a continuación.

En la Google Cloud consola, ve a la página Suscripciones.
Ir a Suscripciones
Haz clic en Crear suscripción.
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.
Elige o crea un tema desde el menú desplegable. La suscripción recibe mensajes del tema.
Selecciona el Tipo de entrega como Envío.
Especifica una URL del extremo.
Conserva todos los demás valores predeterminados.
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.

En la Google Cloud consola, ve a la página Temas.
Ir a temas
Haz clic en junto al tema en el que se creará una suscripción.
En el menú contextual, selecciona Crear suscripción (Create subscription).
Ingresa el ID de suscripción.
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.
Selecciona el Tipo de entrega como Envío.
Especifica una URL del extremo.
Conserva todos los demás valores predeterminados.
Haz clic en Crear.

gcloud

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.
Para crear una suscripción de envío, ejecuta el gcloud pubsub subscriptions create comando.
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
--topic=TOPIC_ID \
--push-endpoint=PUSH_ENDPOINT
```
Reemplaza lo siguiente:
- SUBSCRIPTION_ID: El nombre o ID de tu nueva suscripción de envío.
- TOPIC_ID: El nombre o ID de tu tema.
- PUSH_ENDPOINT: La URL que se usará como extremo para esta suscripción. Por ejemplo, https://myproject.appspot.com/myhandler.

REST

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

Solicitud:

La solicitud debe autenticarse 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 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",
// Only needed if you are using push delivery
"pushConfig": {
"pushEndpoint": "PUSH_ENDPOINT"
}
}

Aquí:

PROJECT_ID es el ID del proyecto.

SUBSCRIPTION_ID es el ID de la suscripción.

TOPIC_ID es el ID del tema.

PUSH_ENDPOINT es una URL que se usará como extremo. Por ejemplo, https://myproject.appspot.com/myhandler.

Respuesta:

{
"name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
"pushConfig": {
"pushEndpoint": "https://PROJECT_ID.appspot.com/myhandler",
"attributes": {
  "x-goog-version": "v1"
}
},
"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 = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& endpoint) {
  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());
  request.mutable_push_config()->set_push_endpoint(endpoint);
  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;

public class CreatePushSubscriptionSample
{
    public Subscription CreatePushSubscription(string projectId, string topicId, string subscriptionId, string pushEndpoint)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        PushConfig pushConfig = new PushConfig { PushEndpoint = pushEndpoint };

        // The approximate amount of time in seconds (on a best-effort basis) Pub/Sub waits for the
        // subscriber to acknowledge receipt before resending the message.
        var ackDeadlineSeconds = 60;
        var subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig, ackDeadlineSeconds);
        return subscription;
    }
}

Go

En el siguiente ejemplo, se usa la versión principal de la biblioteca cliente de Pub/Sub para Go (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 createWithEndpoint(w io.Writer, projectID, topic, subscription, endpoint string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// endpoint := "https://my-test-project.appspot.com/push"
	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,
		AckDeadlineSeconds: 10,
		PushConfig:         &pubsubpb.PushConfig{PushEndpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("failed to create push sub: %w", err)
	}
	fmt.Fprintf(w, "Created push 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 CreatePushSubscriptionExample {
  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";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    createPushSubscriptionExample(projectId, subscriptionId, topicId, pushEndpoint);
  }

  public static void createPushSubscriptionExample(
      String projectId, String subscriptionId, String topicId, String pushEndpoint)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(pushEndpoint).build();

      // Create a push 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, 10);
      System.out.println("Created push 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 pushEndpoint = 'YOUR_ENDPOINT_URL';
// 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 createPushSubscription(
  pushEndpoint,
  topicNameOrId,
  subscriptionNameOrId,
) {
  const options = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

Node.ts

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

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

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

async function createPushSubscription(
  pushEndpoint: string,
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  const options: CreateSubscriptionOptions = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  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 push subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $endpoint  The endpoint for the push subscription.
 */
function create_push_subscription($projectId, $topicName, $subscriptionName, $endpoint)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create([
        'pushConfig' => ['pushEndpoint' => $endpoint]
    ]);

    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"
# endpoint = "https://my-test-project.appspot.com/push"

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)

push_config = pubsub_v1.types.PushConfig(push_endpoint=endpoint)

# 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,
            "push_config": push_config,
        }
    )

print(f"Push subscription created: {subscription}.")
print(f"Endpoint for subscription is: {endpoint}")

Ruby

En el siguiente ejemplo, se usa la biblioteca cliente de Pub/Sub para Ruby 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"
# endpoint          = "https://your-test-project.appspot.com/push"

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),
  push_config: {
    push_endpoint: endpoint
  }

puts "Push subscription #{subscription_id} created."

Supervisa las suscripciones de envío

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?

Crea o modifica una suscripción con gcloud comandos.
Crea o modifica una suscripción con las APIs de REST.

Crea suscripciones de envío Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.