Exporta mensajes de Pub/Sub Lite a Pub/Sub

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En este documento, se describe cómo configurar la exportación automática de mensajes de Pub/Sub Lite a Pub/Sub.

Estas son algunas situaciones en las que puedes usar esta función:

  • Interoperar entre cargas de trabajo que usan una combinación de Pub/Sub Lite y Pub/Sub
  • Migrar una carga de trabajo de Pub/Sub Lite a Pub/Sub
  • Usa funciones avanzadas de Pub/Sub, como las suscripciones de envío y el filtrado, desde una aplicación existente que se base en Pub/Sub Lite.
  • Consolidar varias canalizaciones de datos

Descripción general

Para exportar mensajes de Pub/Sub Lite a Pub/Sub, debes crear un tipo especial de suscripción que se denomina suscripción de exportación. Una suscripción de exportación recibe mensajes de un tema de Lite, los convierte en mensajes de Pub/Sub y los envía a un tema de Pub/Sub de destino.

Diagrama de la exportación de mensajes de Pub/Sub Lite

Un tema Lite puede tener una combinación de suscripciones de exportación y suscripciones estándar. Los dos tipos de suscripción son idénticos en términos de uso de cuota y capacidad de procesamiento de reserva. Una suscripción de exportación consume la capacidad de procesamiento de suscripción de Lite y se cobra por la capacidad de procesamiento de publicación de Pub/Sub.

Una suscripción de exportación conecta un tema de Lite a exactamente un tema de Pub/Sub. Sin embargo, un tema Lite puede tener varias suscripciones de exportación que se conectan a diferentes temas de Pub/Sub (arquitectura fan-out). También puedes exportar desde varios temas Lite al mismo tema de Pub/Sub (arquitectura fan-in).

Authentication

Una suscripción de exportación accede a los recursos de Pub/Sub y Pub/Sub Lite. Para crear una suscripción de exportación, necesitas los siguientes permisos:

  • pubsublite.subscriptions.create. Las siguientes funciones predefinidas contienen este permiso:

    • roles/pubsublite.admin
    • roles/pubsublite.editor

    Consulta Control de acceso para Pub/Sub Lite.

  • pubsub.topics.get. Las siguientes funciones predefinidas contienen este permiso:

    • roles/pubsub.admin
    • roles/pubsub.editor
    • roles/pubsub.viewer

    Consulta Control de acceso para Pub/Sub.

Agentes de servicio

Se publica una suscripción de exportación en un tema de Pub/Sub. Para ello, utiliza una cuenta de servicio administrada por Google.

Cuando creas la primera suscripción de exportación en un proyecto, se crea de forma automática un agente de servicio de Pub/Sub Lite administrado por Google. Si creas suscripciones de exportación adicionales en el mismo proyecto, usarán el mismo agente de servicio. El agente de servicio tiene el siguiente esquema de nombres: service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com.

El agente de servicio se crea con permisos para publicar en todos los temas de Pub/Sub y Pub/Sub Lite dentro del mismo proyecto que la suscripción de exportación. Si tu tema de Pub/Sub de destino se encuentra en un proyecto diferente al de la suscripción de exportación, debes otorgar permisos adicionales al agente de servicio mediante la función Publicador de Pub/Sub (roles/pubsub.publisher). Puedes otorgar permisos para un proyecto completo o un tema individual. Recomendamos otorgar permisos a nivel del tema según el principio de privilegio mínimo.

Para obtener más información, consulta Controla el acceso a través de Google Cloud Console. También puedes usar el comando gcloud projects add-iam-policy-binding para agregar funciones de IAM:

gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \
 --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsublite.iam.gserviceaccount.com
 --role=roles/pubsub.publisher

Reemplaza lo siguiente:

  • TOPIC_NAME: Es el nombre del tema de Pub/Sub de destino en el que se agregará la vinculación de política de IAM.
  • PROJECT_NUMBER: Es el número del proyecto de la suscripción a exportación de Pub/Sub Lite.

Crea una suscripción de exportación

Puedes crear una suscripción de exportación Lite con Google Cloud Console, Google Cloud CLI o la API de Pub/Sub Lite.

Una suscripción de exportación Lite debe estar en el mismo proyecto y la misma ubicación que el tema de Lite al que está conectado. Para crear el tema Lite, consulta Crea y administra temas Lite.

Si adjuntas una suscripción de exportación a un tema de Lite, asegúrate de que todos los mensajes publicados en él sean compatibles con Pub/Sub. Para obtener más información, consulta Compatibilidad con mensajes.

Una vez creada, no puedes cambiar una suscripción de exportación a una estándar, ni viceversa.

Consola

  1. Ve a la página Suscripciones Lite.

    Ir a Suscripciones de Lite

  2. Haz clic en Crear suscripción Lite.

  3. Ingresa un ID de suscripción de Lite.

  4. Selecciona un tema de Lite para recibir mensajes.

  5. Selecciona Entregar mensajes de inmediato o Entregar mensajes después de almacenarlos.

  6. Elige un tipo de Compensación inicial.

  7. Selecciona Exportar a tema de Pub/Sub.

  8. En la lista Tema de destino, elige un tema de Pub/Sub para recibir los mensajes Lite exportados.

  9. Opcional. Especifica un tema de mensajes no entregados.

    1. Selecciona la casilla de verificación Habilitar mensajes no entregados.
    2. Selecciona un tema de Lite para usarlo como tema de mensajes no entregados o haz clic en Create Topic de Lite a fin de crear un tema de mensajes no entregados. El tema de mensajes no entregados debe estar en la misma ubicación (zona o región) y proyecto que la suscripción de exportación.

  10. Haz clic en Crear.

gcloud

Para crear una suscripción de exportación, usa el comando gcloud pubsub lite-subscriptions create:

gcloud pubsub lite-subscriptions create SUBSCRIPTION_ID \
  --location=LOCATION \
  --topic=TOPIC_ID \
  --export-pubsub-topic=PUBSUB_TOPIC_NAME \
  --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
  --export-desired-state=DESIRED_STATE

Reemplaza lo siguiente:

  • SUBSCRIPTION_ID: El ID de la suscripción Lite que se creará.
  • LOCATION: Es la ubicación de la suscripción Lite.
  • TOPIC_ID: El ID del tema de Lite que se adjuntará a la suscripción de Lite.
  • PUBSUB_TOPIC_NAME: Es el nombre del tema de Pub/Sub al que se realizará la exportación. Especifica el nombre completo si el tema se encuentra en otro proyecto: projects/my-project-id/topics/my-topic-id.
  • DEAD_LETTER_TOPIC_ID: Opcional El ID de un tema de Lite que se usará como el tema de mensajes no entregados. El tema de mensajes no entregados debe estar en la misma ubicación (zona o región) y proyecto que la suscripción de exportación.
  • DESIRED_STATE: Opcional El estado inicial de la suscripción. Se admiten los siguientes valores:
    • active: La suscripción exporta mensajes Lite a Pub/Sub. (predeterminado)
    • paused: Se suspendió la exportación de mensajes Lite.

Si la solicitud es exitosa, la línea de comandos muestra una confirmación:

Created [SUBSCRIPTION_ID].

Protocolo

Para crear una suscripción de exportación de Lite, envía una solicitud POST como la siguiente:

POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

Reemplaza lo siguiente:

  • REGION: Es la región en la que se almacenará la suscripción Lite.
  • PROJECT_NUMBER: Es el número del proyecto en el que se creará la suscripción Lite.
  • LOCATION: Es el nombre de una ubicación que admite Pub/Sub Lite.
  • SUBSCRIPTION_ID: El ID de la suscripción Lite.

Especifica los siguientes campos en el cuerpo de la solicitud:

{
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Reemplaza lo siguiente:

  • DELIVERY_REQUIREMENT: Es el requisito de entrega, ya sea DELIVER_AFTER_STORED o DELIVER_IMMEDIATELY.
  • DESIRED_STATE: El estado inicial de la suscripción. Se admiten los siguientes valores:
    • ACTIVE: La suscripción exporta mensajes Lite a Pub/Sub.
    • PAUSED: Se suspendió la exportación de mensajes Lite.
  • DEAD_LETTER_TOPIC_ID: Es el ID de un tema de Lite existente para usarlo como tema de mensajes no entregados. El tema debe estar en la misma ubicación (zona o región) y debe ser el mismo proyecto que la suscripción de exportación.
  • PUBSUB_TOPIC_NAME: Es el nombre del tema de Pub/Sub al que se realizará la exportación. Formato de ejemplo: projects/my-project-id/topics/my-topic-id.

Si la solicitud es exitosa, la respuesta es la suscripción Lite en formato JSON:

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      },
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

Comienza a usarlo

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/pubsublite"
)

func createPubsubExportSubscription(w io.Writer, projectID, region, location, topicID, subID, pubsubTopicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// NOTE: location can be either a region ("us-central1") or a zone ("us-central1-a")
	// For a list of valid locations, see https://cloud.google.com/pubsub/lite/docs/locations.
	// location := "us-central1"
	// NOTE: topic and subscription must be in the same region/zone (e.g. "us-central1-a")
	// topicID := "my-topic"
	// subID := "my-subscription"
	// pubsubTopicID := "destination-topic-id"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	// Initialize the subscription to the oldest retained messages for each
	// partition.
	targetLocation := pubsublite.AtTargetLocation(pubsublite.Beginning)

	sub, err := client.CreateSubscription(ctx, pubsublite.SubscriptionConfig{
		Name:                fmt.Sprintf("projects/%s/locations/%s/subscriptions/%s", projectID, location, subID),
		Topic:               fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, location, topicID),
		DeliveryRequirement: pubsublite.DeliverImmediately, // Can also be DeliverAfterStored.
		// Configures an export subscription that writes messages to a Pub/Sub topic.
		ExportConfig: &pubsublite.ExportConfig{
			DesiredState: pubsublite.ExportActive, // Can also be ExportPaused.
			Destination: &pubsublite.PubSubDestinationConfig{
				Topic: fmt.Sprintf("projects/%s/topics/%s", projectID, pubsubTopicID),
			},
		},
	}, targetLocation)
	if err != nil {
		return fmt.Errorf("client.CreateSubscription got err: %v", err)
	}
	fmt.Fprintf(w, "Created export subscription: %s\n", sub.Name)
	return nil
}

Java

Antes de ejecutar esta muestra, sigue las instrucciones de configuración para Java que se encuentran en las Bibliotecas cliente de Pub/Sub Lite. 

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.BacklogLocation;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudRegionOrZone;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.SeekTarget;
import com.google.cloud.pubsublite.SubscriptionName;
import com.google.cloud.pubsublite.SubscriptionPath;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.ExportConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.PubSubConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.State;
import com.google.cloud.pubsublite.proto.Subscription;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig.DeliveryRequirement;
import java.util.concurrent.ExecutionException;

public class CreatePubsubExportSubscriptionExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String cloudRegion = "your-cloud-region";
    char zoneId = 'b';
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String pubsubTopicId = "destination-topic-id";
    long projectNumber = Long.parseLong("123456789");
    // True if using a regional location. False if using a zonal location.
    // https://cloud.google.com/pubsub/lite/docs/topics
    boolean regional = false;

    createPubsubExportSubscriptionExample(
        cloudRegion, zoneId, projectNumber, topicId, subscriptionId, pubsubTopicId, regional);
  }

  public static void createPubsubExportSubscriptionExample(
      String cloudRegion,
      char zoneId,
      long projectNumber,
      String topicId,
      String subscriptionId,
      String pubsubTopicId,
      boolean regional)
      throws Exception {

    CloudRegionOrZone location;
    if (regional) {
      location = CloudRegionOrZone.of(CloudRegion.of(cloudRegion));
    } else {
      location = CloudRegionOrZone.of(CloudZone.of(CloudRegion.of(cloudRegion), zoneId));
    }

    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(location)
            .setName(TopicName.of(topicId))
            .build();

    SubscriptionPath subscriptionPath =
        SubscriptionPath.newBuilder()
            .setLocation(location)
            .setProject(ProjectNumber.of(projectNumber))
            .setName(SubscriptionName.of(subscriptionId))
            .build();

    com.google.pubsub.v1.TopicName pubsubTopicName =
        com.google.pubsub.v1.TopicName.of(String.valueOf(projectNumber), pubsubTopicId);

    Subscription subscription =
        Subscription.newBuilder()
            .setDeliveryConfig(
                // Possible values for DeliveryRequirement:
                // - `DELIVER_IMMEDIATELY`
                // - `DELIVER_AFTER_STORED`
                // You may choose whether to wait for a published message to be successfully written
                // to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
                // suitable for applications that need higher throughput.
                DeliveryConfig.newBuilder()
                    .setDeliveryRequirement(DeliveryRequirement.DELIVER_IMMEDIATELY))
            .setExportConfig(
                // Configures an export subscription that writes messages to a Pub/Sub topic.
                ExportConfig.newBuilder()
                    // Possible values for State:
                    // - `ACTIVE`: enable message processing.
                    // - `PAUSED`: suspend message processing.
                    .setDesiredState(State.ACTIVE)
                    .setPubsubConfig(
                        PubSubConfig.newBuilder().setTopic(pubsubTopicName.toString())))
            .setName(subscriptionPath.toString())
            .setTopic(topicPath.toString())
            .build();

    // Target location within the message backlog that the subscription should be initialized to.
    SeekTarget initialLocation = SeekTarget.of(BacklogLocation.BEGINNING);

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(location.extractRegion()).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources, or
    // use "try-with-close" statement to do this automatically.
    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Subscription response = adminClient.createSubscription(subscription, initialLocation).get();
      System.out.println(response.getAllFields() + " created successfully.");
    } catch (ExecutionException e) {
      try {
        throw e.getCause();
      } catch (AlreadyExistsException alreadyExists) {
        System.out.println("This subscription already exists.");
      } catch (Throwable throwable) {
        throwable.printStackTrace();
      }
    }
  }
}

Python

Antes de ejecutar esta muestra, sigue las instrucciones de configuración para Python en las bibliotecas cliente de Pub/Sub Lite. 

from google.api_core.exceptions import AlreadyExists
from google.cloud.pubsub_v1 import PublisherClient
from google.cloud.pubsublite import AdminClient, Subscription, ExportConfig
from google.cloud.pubsublite.types import (
    BacklogLocation,
    CloudRegion,
    CloudZone,
    SubscriptionPath,
    TopicPath,
)

def create_lite_pubsub_export_subscription(
    project_number,
    cloud_region="us-central1",
    zone_id="a",
    topic_id="my-topic-id",
    subscription_id="my-subscription-id",
    pubsub_topic_id="destination-topic-id",
    regional=True,
    target_location=BacklogLocation.BEGINNING,
):
    if regional:
        location = CloudRegion(cloud_region)
    else:
        location = CloudZone(CloudRegion(cloud_region), zone_id)

    topic_path = TopicPath(project_number, location, topic_id)
    subscription_path = SubscriptionPath(project_number, location, subscription_id)
    destination_topic_path = PublisherClient.topic_path(project_number, pubsub_topic_id)

    subscription = Subscription(
        name=str(subscription_path),
        topic=str(topic_path),
        delivery_config=Subscription.DeliveryConfig(
            # Possible values for delivery_requirement:
            # - `DELIVER_IMMEDIATELY`
            # - `DELIVER_AFTER_STORED`
            # You may choose whether to wait for a published message to be successfully written
            # to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
            # suitable for applications that need higher throughput.
            delivery_requirement=Subscription.DeliveryConfig.DeliveryRequirement.DELIVER_IMMEDIATELY,
        ),
        # Configures an export subscription that writes messages to a Pub/Sub topic.
        export_config=ExportConfig(
            # Possible values for desired_state:
            # - `ACTIVE`: enable message processing.
            # - `PAUSED`: suspend message processing.
            desired_state=ExportConfig.State.ACTIVE,
            pubsub_config=ExportConfig.PubSubConfig(
                topic=destination_topic_path,
            ),
        ),
    )

    # Initialize client that will be used to send requests across threads. This
    # client only needs to be created once, and can be reused for multiple requests.
    client = AdminClient(cloud_region)
    try:
        response = client.create_subscription(subscription, target_location)
        print(f"{response.name} created successfully.")
    except AlreadyExists:
        print(f"{subscription_path} already exists.")

Actualiza una suscripción de exportación

Puedes actualizar las suscripciones de Lite con Google Cloud Console, Google Cloud CLI o la API de Pub/Sub Lite. La nueva configuración puede tardar hasta 30 segundos en aplicarse.

Consola

  1. Ve a la página Suscripciones Lite.

    Ir a Suscripciones de Lite

  2. Haz clic en el ID de suscripción Lite.

  3. En la página Detalles de la suscripción Lite, haz clic en Editar.

gCloud

Para actualizar una suscripción Lite, usa el comando gcloud pubsub lite-subscriptions update:

gcloud pubsub lite-subscriptions update SUBSCRIPTION_ID \
--location=LOCATION \
--delivery-requirement=DELIVERY_REQUIREMENT \
--export-pubsub-topic=PUBSUB_TOPIC_NAME \
--export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
--export-desired-state=DESIRED_STATE

Reemplaza lo siguiente:

  • SUBSCRIPTION_ID: El ID de la suscripción Lite
  • LOCATION: Es la ubicación de la suscripción Lite.
  • DELIVERY_REQUIREMENT: Opcional El requisito de entrega, ya sea deliver-after-stored o deliver-immediately
  • PUBSUB_TOPIC_NAME: Opcional El nombre del tema de Pub/Sub al que se realizará la exportación. Especifica el nombre completo si el tema se encuentra en otro proyecto: projects/my-project-id/topics/my-topic-id.
  • DEAD_LETTER_TOPIC_ID: Es el ID de un tema de Lite existente para usarlo como tema de mensajes no entregados. El tema debe estar en la misma ubicación (zona o región) y debe ser el mismo proyecto que la suscripción de exportación.
  • DESIRED_STATE: Opcional El estado deseado de la suscripción. Se admiten los siguientes valores:
    • active: La suscripción exporta mensajes Lite a Pub/Sub. (predeterminado)
    • paused: Se suspendió la exportación de mensajes Lite.

Si la solicitud es exitosa, la línea de comandos muestra el tema de Lite:

Updated subscription [SUBSCRIPTION_ID].
deliveryConfig:
deliveryRequirement: DELIVERY_REQUIREMENT
exportConfig:
currentState: DESIRED_STATE
deadLetterTopic: projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID
desiredState: DESIRED_STATE
pubsubConfig:
  topic: PUBSUB_TOPIC_NAME
name: projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
topic: projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID

Protocolo

Para actualizar una suscripción Lite, envía una solicitud PATCH como la siguiente:

PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID?updateMask=deliveryConfig.deliveryRequirement,exportConfig
Authorization: Bearer $(gcloud auth print-access-token)

Reemplaza lo siguiente:

  • REGION: Es la región en la que se creó la suscripción Lite.
  • PROJECT_NUMBER: Es el número del proyecto en el que se creó la suscripción Lite.
  • LOCATION: La ubicación en la que se creó la suscripción Lite
  • SUBSCRIPTION_ID: El ID de la suscripción Lite.

Especifica los siguientes campos en el cuerpo de la solicitud:

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Reemplaza lo siguiente:

  • DELIVERY_REQUIREMENT: Es el requisito de entrega, ya sea DELIVER_AFTER_STORED o DELIVER_IMMEDIATELY.
  • DESIRED_STATE: Es el estado deseado de la suscripción. Se admiten los siguientes valores:
    • ACTIVE: La suscripción exporta mensajes Lite a Pub/Sub.
    • PAUSED: Se suspendió la exportación de mensajes Lite.
  • DEAD_LETTER_TOPIC_ID: Es el ID de un tema de Lite existente para usarlo como tema de mensajes no entregados. El tema debe estar en la misma ubicación (zona o región) y debe ser el mismo proyecto que la suscripción de exportación.
  • PUBSUB_TOPIC_NAME: Es el nombre del tema de Pub/Sub de destino. Formato de ejemplo: projects/my-project-id/topics/my-topic-id.

Si la solicitud es exitosa, la respuesta es la suscripción Lite en formato JSON:

{
"deliveryConfig": {
  "deliveryRequirement": "DELIVERY_REQUIREMENT",
},
"exportConfig": {
  "desiredState": "DESIRED_STATE",
  "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
  "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" }
},
"name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

Cómo pausar o iniciar una suscripción de exportación

Las suscripciones de exportación tienen una configuración llamada estado deseado que tiene uno de estos dos valores:

  • Activa: La suscripción exporta mensajes Lite a Pub/Sub.
  • Detenida: La exportación de mensajes Lite está suspendida.

Para cambiar el estado deseado en Google Cloud Console, sigue estos pasos:

  1. Ve a la página Suscripciones Lite.

    Ir a Suscripciones de Lite

  2. Haz clic en el ID de suscripción Lite.

  3. En la página Detalles de la suscripción Lite, haz clic en Pausar o en Iniciar.

También puedes actualizar el estado deseado con Google Cloud CLI o la API de Pub/Sub Lite. Consulta Actualiza una suscripción de exportación.

Prácticas recomendadas

En esta sección, se describen algunas prácticas recomendadas para usar las suscripciones de exportación.

Reservas

Recomendamos usar una suscripción de exportación con una reserva, en lugar de establecer de forma explícita la capacidad de procesamiento de la suscripción.

Compatibilidad de los mensajes

Si un mensaje de Pub/Sub Lite no es compatible con Pub/Sub, la suscripción de exportación no lo publica en Pub/Sub. En su lugar, coloca el mensaje en el tema de mensajes no entregados, si se asignó uno. Si no se asignó ningún tema de mensajes no entregados, los mensajes incompatibles simplemente se descartan.

Cuando publiques mensajes en el tema Lite, ten en cuenta los siguientes problemas de compatibilidad:

  • Claves. Las claves de Pub/Sub Lite tienen el tipo bytes, mientras que las claves de ordenamiento de Pub/Sub son del tipo string. Para ser compatible, la clave de Pub/Sub Lite debe contener solo caracteres UTF-8.

  • Atributos: Los atributos de los mensajes tienen los siguientes requisitos:

    • Para ser compatibles, todos los atributos de mensaje de Pub/Sub Lite deben tener un solo valor. Pub/Sub Lite admite atributos de mensaje con valores múltiples, pero Pub/Sub solo admite atributos de valor único.
    • Los atributos de los mensajes no deben superar los límites de mensajes de Pub/Sub, incluidos el máximo de atributos por mensaje, y el tamaño máximo de clave y valor por atributo.

Tema de mensajes no entregados

Para retener y manejar los mensajes incompatibles, recomendamos usar un tema de mensajes no entregados. Puedes asignar un tema de mensajes no entregados cuando crees la suscripción de exportación, o puedes actualizar una suscripción de exportación existente para usar un tema de mensajes no entregados. Si la suscripción recibe un mensaje que no es compatible con Pub/Sub, publica el mensaje en el tema de mensajes no entregados.

Un tema de mensajes no entregados es un tema normal de Pub/Sub Lite. Debe estar en la misma ubicación y proyecto que la suscripción de exportación, y debe ser un tema diferente del tema de origen.

Por lo general, un tema de mensajes no entregados tiene un uso bajo de capacidad de procesamiento. Por lo tanto, recomendamos asignar una reserva al tema de mensajes no entregados, en lugar de asignar la capacidad de procesamiento al tema.

Errores de entrega

Una suscripción de exportación intenta entregar todos los mensajes compatibles al tema de Pub/Sub de destino. Si la entrega de mensajes falla, la suscripción de exportación se suspende. Para encontrar la categoría de error, verifica la métrica subscription/export_status. Los siguientes valores indican un error:

  • PERMISSION_DENIED: No tienes permisos suficientes para exportar los mensajes.
  • NOT_FOUND: No se encontraron uno o más recursos; por ejemplo, el tema de destino no existe.

Para obtener más información sobre la solución de problemas, consulta Soluciona problemas de exportaciones de suscripciones.

Después de resolver el error, la suscripción de exportación se reinicia de forma automática debido a reintentos periódicos.

Precios

Se te cobra por los recursos de Pub/Sub y Pub/Sub que consume la suscripción de exportación. En particular, se te cobra por el rendimiento y el almacenamiento de la suscripción asignada en la suscripción de Pub/Sub Lite, que están configuradas para el tema de Pub/Sub Lite. También se te cobra por publicar en el tema de Pub/Sub de destino. Consulta los precios de Pub/Sub.

No se aplican cargos adicionales por usar la función de exportación, y tampoco hay diferencias de precios entre las suscripciones de exportación de Pub/Sub Lite y las suscripciones estándar.

Soluciona problemas relacionados con las suscripciones de exportación

En esta sección, se describen algunas sugerencias de solución de problemas para las suscripciones de exportación.

Se pausó la suscripción de exportación

Si la suscripción está pausada, no se exportarán mensajes.

Para detectar este problema, haz lo siguiente:

  • Google Cloud Console: consulta los detalles de la suscripción. Si la suscripción está pausada, el Estado deseado y el Estado actual son Paused.

  • Métricas: La métrica subscription/export_status es PAUSED.

Para resolver este problema, inicia la suscripción.

Se borró el tema de destino o tema de mensajes no entregados

Se produce un error si borras el tema de Pub/Sub conectado a una suscripción de exportación o el tema de mensajes no entregados.

Para detectar este problema, haz lo siguiente:

  • Google Cloud Console: consulta los detalles de la suscripción. Si se borró el tema, el Estado actual es Not found.

  • Métricas: La métrica subscription/export_status. Si se borró el tema, el valor es NOT_FOUND.

Para resolver este problema, verifica el tema de Pub/Sub de destino y el tema de mensajes no entregados (si se configuró uno).

Si se borró el destino de Pub/Sub, vuelve a crear el tema con el mismo nombre. La suscripción de exportación reanuda la publicación, suponiendo que los permisos no cambiaron.

Si se borró el tema de mensajes no entregados, crea un tema nuevo y actualiza la suscripción de exportación para hacer referencia a él.

Mensajes incompatibles

Si los mensajes son incompatibles con Pub/Sub, no se exportan.

Para detectar este problema, haz lo siguiente:

  • Métricas: La métrica subscription/unexportable_message_count muestra el recuento de mensajes incompatibles que no se pudieron exportar.

A fin de resolver este problema, usa un tema de mensajes no entregados para conservar los mensajes incompatibles. Examinar los mensajes para determinar la causa, luego transformarlos y volver a publicarlos si es necesario Consulta Compatibilidad con mensajes.

La exportación está limitada

Para detectar este problema, haz lo siguiente:

  • Métricas: La métrica subscription/flow_control_status muestra un motivo de control de flujo de NO_CLIENT_TOKENS, que indica que se alcanzó el límite por partición de bytes o mensajes pendientes. El trabajo pendiente aumentará en las suscripciones de exportación asociadas hasta que se resuelva el problema.

Este error tiene varias causas posibles. La mayoría de las causas posibles ocurren en el backend, pero verifica lo siguiente:

  • Asegúrate de publicar mensajes Lite que compartan la misma clave a una tasa de menos de 1 MiB/s por clave. La suscripción de exportación escribe claves de mensaje Lite como claves de ordenamiento de Pub/Sub, y Pub/Sub tiene un límite de 1 MiB/s en cada clave de ordenamiento. Exceder este límite puede causar una limitación.

El usuario no está autorizado para realizar esta acción.

El agente de servicio de Pub/Sub Lite debe tener permisos para publicar en el tema de Pub/Sub de destino.

Para detectar este problema, haz lo siguiente:

  • Google Cloud Console: consulta los detalles de la suscripción. Si hay errores de permisos, el Estado actual es Permission denied.

  • Métricas: La métrica subscription/export_status es PERMISSON_DENIED.

Por ejemplo, las siguientes situaciones pueden causar este error:

  • Al agente de servicio de Pub/Sub Lite le falta el permiso o la función correctos para publicar mensajes en el tema de Pub/Sub de destino en un proyecto diferente.
  • El agente de servicio se quitó de la política de IAM del proyecto superior de la suscripción de exportación.
  • El agente de servicio de Pub/Sub Lite aún se está configurando. Un agente de servicio se crea de forma automática cuando creas la primera suscripción de exportación en un proyecto. El error de permiso se debe resolver automáticamente en 10 minutos.

Para resolver el problema, verifica si al agente de servicio se le otorgó el permiso o la función correctos. Consulta Agentes de servicio.

¿Qué sigue?

Elige entre Pub/Sub o Pub/Sub Lite.