Esta página se ha traducido con Cloud Translation API.

Crear suscripciones de inserción

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

Antes de empezar

Consulta información sobre las suscripciones.
Consulta cómo funcionan las suscripciones push.

Roles y permisos necesarios

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

Para obtener los permisos que necesitas para crear suscripciones push, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Editor de Pub/Sub (roles/pubsub.editor) en el proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear suscripciones push. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para crear suscripciones push, se necesitan los siguientes permisos:

Crear una suscripción: pubsub.subscriptions.create
Eliminar una suscripción: pubsub.subscriptions.delete
Obtener una suscripción: pubsub.subscriptions.get
Mostrar una suscripción: pubsub.subscriptions.list
Actualizar una suscripción: pubsub.subscriptions.update
Adjuntar una suscripción a un tema: pubsub.topics.attachSubscription
Obtener la política de gestión de identidades y accesos de una suscripción: pubsub.subscriptions.getIamPolicy
Configura la política de gestión de identidades y accesos de una suscripción: pubsub.subscriptions.setIamPolicy

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

Si necesitas crear suscripciones push en un proyecto que estén asociadas a un tema de otro proyecto, pide al administrador del tema que te conceda el rol de editor de Pub/Sub (roles/pubsub.editor) de IAM en el tema.

Propiedades de suscripción de inserción

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

Propiedades comunes

Consulta las propiedades de suscripción comunes que puedes definir en todas las suscripciones.

Endpoints

URL del endpoint (obligatoria). Una dirección HTTPS de acceso público. El servidor del endpoint de envío debe tener un certificado SSL válido firmado por una autoridad de certificación. El servicio Pub/Sub envía mensajes a los endpoints de inserción desde la misma región en la que el servicio Pub/Sub almacena los mensajes. Google Cloud El servicio Pub/Sub entrega mensajes de la misma región en la medida de lo posible. Google Cloud

Si los suscriptores usan un cortafuegos, no podrán recibir solicitudes push. Para recibir solicitudes push, debes desactivar el cortafuegos y verificar el JSON Web Token (JWT) utilizado en la solicitud. Si un suscriptor tiene un cortafuegos, es posible que recibas un 403 permission deniederror.
Pub/Sub ya no requiere una prueba de propiedad para los dominios de URL de suscripción push. Si tu dominio recibe solicitudes POST inesperadas de Pub/Sub, puedes denunciar un posible abuso.

Autenticación

Habilita la autenticación. Cuando está habilitada, los mensajes que Pub/Sub envía al endpoint push incluyen un encabezado de autorización para permitir que el endpoint autentique la solicitud. Los mecanismos de autenticación y autorización automáticos están disponibles para los endpoints de funciones de App Engine Standard y Cloud Run alojados en el mismo proyecto que la suscripción.

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

Audiencia. Una cadena única que no distingue entre mayúsculas y minúsculas que el webhook usa para validar la audiencia a la que va dirigido este token concreto.
Cuenta de servicio. Pub/Sub crea automáticamente una cuenta de servicio con el formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Requisitos previos para habilitar la autenticación

La cuenta de servicio gestionada por el usuario es la cuenta de servicio asociada a la suscripción push. Esta cuenta se usa como la reclamación email del JSON Web Token (JWT) generado. A continuación, se muestra una lista de los requisitos de la cuenta de servicio:

Esta cuenta de servicio gestionada por el usuario debe estar en el mismo proyecto que la suscripción push.
La entidad de seguridad que cree o modifique la suscripción push debe tener el permiso iam.serviceAccounts.actAs en la cuenta de servicio gestionada por el usuario para adjuntar la cuenta de servicio a la suscripción push. Para obtener más información, consulta el artículo sobre cómo asociar cuentas de servicio a recursos.
Permisos necesarios: se debe conceder a esta cuenta de servicio el permiso iam.serviceAccounts.getOpenIdToken (incluido en el rol roles/iam.serviceAccountTokenCreator) para permitir que Pub/Sub cree tokens JWT para que la cuenta de servicio especificada autentique las solicitudes push.

Retirada de envoltorio de la carga útil

La opción Habilitar el desempaquetado de la carga útil elimina de los mensajes de Pub/Sub todos los metadatos de los mensajes, excepto los datos de los mensajes. Con el desempaquetado de la carga útil, los datos del mensaje se envían directamente como cuerpo HTTP.

También puede habilitar la opción Escribir metadatos. La opción Escribir metadatos vuelve a añadir los metadatos del mensaje que se habían eliminado anteriormente al encabezado de la solicitud.

Enviar a direcciones de VPC privadas

Pub/Sub funciona 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 de tu VPC. Pub/Sub puede insertar mensajes en un activador de Eventarc, que puede reenviarlos a un servicio 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 de Servicio de VPC

En el caso de los proyectos protegidos por Controles de Servicio de VPC, ten en cuenta las siguientes limitaciones de las suscripciones push:

Solo puedes crear suscripciones push nuevas cuyo endpoint push esté configurado en un servicio de Cloud Run con una URL run.app predeterminada o en una ejecución de Workflows. Los dominios personalizados no funcionan.
Cuando enrutes eventos a través de Eventarc a destinos de Workflows cuyo endpoint de inserción esté configurado para una ejecución de Workflows, solo podrás crear suscripciones de inserción a través de Eventarc.
No puedes actualizar las suscripciones push. Estas suscripciones push siguen funcionando, aunque no están protegidas por Controles de Servicio de VPC.

Crear una suscripción de inserción

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

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

Consola

Para crear una suscripción push, sigue estos pasos:

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, introduce un nombre.
Para obtener información sobre cómo asignar un nombre a una suscripción, consulta las directrices para asignar un nombre a un tema o a una suscripción.
Elige o crea un tema en el menú desplegable. La suscripción recibe mensajes del tema.
Seleccione Envío como Tipo de publicación.
Especifica una URL de endpoint.
Mantén el resto de los valores predeterminados.
Haz clic en Crear.

También puedes crear una suscripción desde la sección Temas. 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 sobre el que quieras crear una suscripción.
En el menú contextual, selecciona Crear suscripción.
Introduce el ID de suscripción.
Para obtener información sobre cómo asignar un nombre a una suscripción, consulta las directrices para asignar un nombre a un tema o a una suscripción.
Seleccione Envío como Tipo de publicación.
Especifica una URL de endpoint.
Mantén el resto de los valores predeterminados.
Haz clic en Crear.

gcloud

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.
Para crear una suscripción de inserción, ejecuta el comando gcloud pubsub subscriptions create.
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
--topic=TOPIC_ID \
--push-endpoint=PUSH_ENDPOINT
```
Haz los cambios siguientes:
- SUBSCRIPTION_ID: El nombre o el ID de tu nueva suscripción push.
- TOPIC_ID: el nombre o el ID del tema.
- PUSH_ENDPOINT: la URL que se va a usar como endpoint de esta suscripción. Por ejemplo, https://myproject.appspot.com/myhandler.

REST

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

Solicitud:

La solicitud debe autenticarse con un token de acceso en el encabezado Authorization. Para obtener un token de acceso de las credenciales predeterminadas de la aplicación actuales, ejecuta 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"
}
}

Donde:

PROJECT_ID es el ID del proyecto.

SUBSCRIPTION_ID es el ID de tu suscripción.

El ID de tu tema es TOPIC_ID.

PUSH_ENDPOINT es una URL que se usa como endpoint. 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 este ejemplo, sigue las instrucciones de configuración de C++ que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de C++ de Pub/Sub.

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 este ejemplo, sigue las instrucciones de configuración de C# que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de C# de Pub/Sub.


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 de cliente de Pub/Sub de Go (v2). Si sigues usando la biblioteca v1, consulta la guía de migración a la versión 2. Para ver una lista de ejemplos de código de la versión 1, consulta los ejemplos de código obsoletos.

Antes de probar este ejemplo, sigue las instrucciones de configuración de Go que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de Pub/Sub.

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 este ejemplo, sigue las instrucciones de configuración de Java que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de Java de Pub/Sub.


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 este ejemplo, sigue las instrucciones de configuración de Node.js que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de Node.js de Pub/Sub.

/**
 * 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 este ejemplo, sigue las instrucciones de configuración de PHP que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para 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 este ejemplo, sigue las instrucciones de configuración de Python que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para 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 de cliente de Ruby Pub/Sub v3. Si sigues usando la biblioteca v2, consulta la guía de migración a la versión 3. Para ver una lista de ejemplos de código de Ruby v2, consulta los ejemplos de código obsoletos.

Antes de probar este ejemplo, sigue las instrucciones de configuración de Ruby que se indican en la guía de inicio rápido sobre cómo usar bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API de Ruby de Pub/Sub.

# 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."

Monitorizar las suscripciones push

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

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

También puedes monitorizar las suscripciones en Pub/Sub.

Siguientes pasos

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

Crear suscripciones de inserción Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.