Crea suscripciones de envío

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

Antes de comenzar

Roles y permisos requeridos

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

Para obtener los permisos que necesitas para crear suscripciones push, pídele a tu administrador que te otorgue el rol de IAM de 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 suscripciones push. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear suscripciones push:

  • Crea una suscripción: pubsub.subscriptions.create
  • Borrar una suscripción: pubsub.subscriptions.delete
  • Obtener una suscripción: pubsub.subscriptions.get
  • Cómo enumerar una suscripción: pubsub.subscriptions.list
  • Actualizar 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

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

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

Propiedades de suscripción de envío

Cuando configuras una suscripción de envío, 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.

Extremos

URL del extremo (obligatoria). 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 certificadora. El servicio Pub/Sub entrega mensajes a los extremos de envío desde la misma región de Google Cloud en la que el servicio de Pub/Sub almacena los mensajes. El servicio Pub/Sub entrega mensajes de la misma región de Google Cloud según el criterio del mejor esfuerzo.

Pub/Sub ya 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

Habilita la autenticación. Cuando está habilitada, 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 de las funciones de App Engine estándar y Cloud Run alojados en el mismo proyecto que la suscripción.

La configuración de autenticación para una suscripción push 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 un agente de servicio, como se explica en la siguiente sección.

  • Cuenta de servicio administrada por el usuario (obligatoria). La cuenta de servicio asociada con la suscripción de envío. Esta cuenta se usa como el reclamo email del token web JSON (JWT) generado. A continuación, se incluye una lista de los requisitos de la cuenta de servicio:

  • Público. Es una cadena única que no distingue mayúsculas de minúsculas y que el webhook usa para validar el público objetivo de este token en particular.

  • Agente de servicio (obligatorio).

    • Pub/Sub crea automáticamente una cuenta de servicio para ti con el formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

    • Se debe otorgar a este agente de servicio el permiso iam.serviceAccounts.getOpenIdToken (incluido en el rol roles/iam.serviceAccountTokenCreator) para permitir que Pub/Sub cree tokens JWT para solicitudes push autenticadas.

Separación de la carga útil

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

  • Escribir metadatos. Vuelve a agregar los metadatos del mensaje que se quitaron anteriormente al encabezado de la solicitud.

Controles del servicio de VPC

En el caso de 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 push 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 inserción con la configuración predeterminada proporcionada.

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

Console

Para crear una suscripción de envío, 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 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. Elige o crea un tema desde el menú desplegable. La suscripción recibe mensajes del tema.
  5. Selecciona Envío como el Tipo de entrega.
  6. Especifica una URL de extremo.
  7. Conserva todos los demás valores predeterminados.
  8. 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 en el que se creará una suscripción.
  3. En el menú contextual, selecciona Crear suscripción (Create subscription).
  4. 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.

  5. Selecciona Envío como Push en el Tipo de entrega.
  6. Especifica una URL de extremo.
  7. Conserva todos los demás valores predeterminados.
  8. Haz clic en Crear.

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 crear una suscripción push, ejecuta el comando gcloud pubsub subscriptions create.

    gcloud pubsub subscriptions create SUBSCRIPTION_ID \
        --topic=TOPIC_ID \
        --push-endpoint=PUSH_ENDPOINT

    Reemplaza lo siguiente:

    • SUBSCRIPTION_ID: Es el nombre o el ID de tu nueva suscripción push.
    • TOPIC_ID: Es el nombre o el ID de tu tema.
    • PUSH_ENDPOINT: Es 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 método projects.subscriptions.create:

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 tu 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# que encontrarás 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 C# de Pub/Sub.

    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;
    
    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

    Antes de probar esta muestra, sigue las instrucciones de configuración de Go que encontrarás 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 Go de Pub/Sub.

    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 createWithEndpoint(w io.Writer, projectID, subID string, topic *pubsub.Topic, endpoint string) error {
    	// projectID := "my-project-id"
    	// subID := "my-sub"
    	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
    	// 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.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
    		Topic:       topic,
    		AckDeadline: 10 * time.Second,
    		PushConfig:  pubsub.PushConfig{Endpoint: endpoint},
    	})
    	if err != nil {
    		return fmt.Errorf("CreateSubscription: %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 que encontrarás 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 Java de Pub/Sub.

    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 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

    /**
     * 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.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
    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 que encontrarás 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 PHP de Pub/Sub.

    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 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 que encontrarás 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 Python de Pub/Sub.

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

    Antes de probar esta muestra, sigue las instrucciones de configuración de Ruby que encontrarás 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 Ruby de Pub/Sub.

    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"
    # endpoint          = "https://your-test-project.appspot.com/push"
    
    pubsub = Google::Cloud::Pubsub.new
    
    topic        = pubsub.topic topic_id
    subscription = topic.subscribe subscription_id,
                                   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 supervisión de Pub/Sub.

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

    ¿Qué sigue?