Ordenar mensajes

El ordenamiento de mensajes es una función de Pub/Sub que te permite recibir mensajes en tus clientes suscriptores en el orden en que los publicaron los clientes publicadores.

Por ejemplo, supongamos que un cliente publicador en una región publica los mensajes 1, 2 y 3 en orden. Con el ordenamiento de mensajes, el cliente suscriptor recibe los mensajes publicados en el mismo orden. Para que se entreguen en orden, el cliente publicador debe publicar los mensajes en la misma región. Sin embargo, los suscriptores pueden conectarse a cualquier región y la garantía de ordenamiento aún se mantiene.

El ordenamiento de mensajes es una función útil para situaciones como la captura de cambios en la base de datos, el seguimiento de sesiones de usuarios y las aplicaciones de transmisión, en las que es importante preservar la cronología de los eventos.

En esta página, se explica el concepto de ordenamiento de mensajes y cómo configurar tus clientes suscriptores para recibir mensajes en orden. Para configurar tus clientes publicadores para el ordenamiento de mensajes, consulta Usa claves de ordenamiento para publicar un mensaje.

Descripción general del ordenamiento de mensajes

El ordenamiento en Pub/Sub se determina de la siguiente manera:

  • Clave de ordenamiento. Una clave de ordenamiento es una cadena que identifica los mensajes relacionados que se deben ordenar. Entre los ejemplos de claves de ordenamiento, se incluyen los IDs de clientes o la clave primaria de una fila en una base de datos. Una clave de ordenamiento puede tener hasta 1 KB de longitud.

    Para lograr el ordenamiento de mensajes, establece la misma clave de ordenamiento en todos los mensajes relacionados que se deben recibir en orden. Además, debes publicar todos los mensajes con la misma clave de ordenamiento en la misma región. Para obtener más información, consulta Usa claves de ordenamiento para publicar un mensaje.

    Los mensajes con una clave de ordenamiento vacía no se ordenan.

  • Habilitar el ordenamiento de mensajes. Para recibir mensajes en orden, debes habilitar el ordenamiento de mensajes en la suscripción. Para obtener más información, consulta Habilita el ordenamiento de mensajes.

    Si el ordenamiento de mensajes no está habilitado, una suscripción recibe mensajes sin un orden esperado. Por ejemplo, supongamos que las suscripciones A y B están adjuntas al mismo tema T, y que el ordenamiento está habilitado en la suscripción A , pero no en la suscripción B. Aunque ambas suscripciones reciben el mismo conjunto de mensajes del tema T, el ordenamiento solo se conserva para la suscripción A.

La capacidad de procesamiento de publicación en cada clave de ordenamiento está limitada a 1 MBps. La capacidad de procesamiento en todas las claves de ordenamiento de un tema está limitada a la cuota disponible en una región de publicación. Este límite se puede aumentar a varios GBps.

En general, si tu solución requiere que los clientes publicadores envíen mensajes ordenados y no ordenados, crea temas separados, uno para los mensajes ordenados y el otro para los mensajes no ordenados.

Consideraciones cuando se usan mensajes ordenados

La siguiente lista contiene información importante sobre el comportamiento de los mensajes ordenados en Pub/Sub:

  • Cardinalidad. Una clave de ordenamiento no es equivalente a una partición en un sistema de mensajería basado en particiones, ya que se espera que las claves de ordenamiento tengan una cardinalidad mucho más alta que las particiones.

  • Ordenamiento dentro de la clave: Se espera que los mensajes publicados con la misma clave de ordenamiento se reciban en orden. Supongamos que, para la clave de ordenamiento A, publicas los mensajes 1, 2 y 3. Con el ordenamiento habilitado, se espera que 1 se entregue antes que 2 y que 2 se entregue antes que 3.

  • Ordenamiento entre claves: No se espera que los mensajes publicados con diferentes claves de ordenamiento se reciban en orden. Supongamos que tienes las claves de ordenamiento A y B. Para la clave de ordenamiento A, los mensajes 1 y 2 se publican en orden. Para la clave de ordenamiento B, los mensajes 3 y 4 se publican en orden. Sin embargo, el mensaje 1 podría llegar antes o después del mensaje 4.

  • Reenvío de mensajes: Pub/Sub entrega cada mensaje al menos una vez, por lo que el servicio de Pub/Sub podría volver a entregarlos. Los reintentos de entrega de un mensaje activan el reenvío de todos los mensajes posteriores para esa clave, incluso los confirmados. Supongamos que un cliente suscriptor recibe los mensajes 1, 2 y 3 para una clave de ordenamiento específica. Si se vuelve a enviar el mensaje 2 (porque venció el plazo de confirmación o la confirmación de mejor esfuerzo no persistió en Pub/Sub), también se vuelve a enviar el mensaje 3. Si el ordenamiento de los mensajes y un tema de mensajes no entregados están habilitados en una suscripción, es posible que este comportamiento no sea así, ya que Pub/Sub reenvía mensajes a temas de mensajes no entregados en base del mejor esfuerzo.

  • Demoras en la confirmación y temas de mensajes no entregados: Los mensajes no confirmados para una clave de ordenamiento determinada pueden retrasar la entrega de mensajes para otras claves de ordenamiento, en especial durante los reinicios del servidor o los cambios de tráfico. Para mantener el orden en estos eventos, asegúrate de confirmar todos los mensajes de manera oportuna. Si no es posible confirmar de manera oportuna, considera usar un tema de mensajes no entregados para evitar la retención indefinida de mensajes. Ten en cuenta que es posible que no se conserve el orden cuando los mensajes se escriben en un tema de mensajes no entregados.

  • Afinidad de mensajes (clientes streamingPull): Por lo general, los mensajes para la misma clave se entregan al mismo cliente suscriptor de streamingPull. Se espera afinidad cuando los mensajes están pendientes para una clave de ordenamiento a un cliente suscriptor específico. Si no hay mensajes pendientes, la afinidad puede cambiar para el balanceo de cargas o las desconexiones del cliente.

    Para garantizar un procesamiento sin problemas, incluso con posibles cambios de afinidad, es fundamental diseñar tu aplicación de streamingPull de manera que pueda controlar los mensajes en cualquier cliente para una clave de ordenamiento determinada.

  • Integración con Dataflow: No habilites el ordenamiento de mensajes para las suscripciones cuando configures Dataflow con Pub/Sub. Dataflow tiene su propio mecanismo para el ordenamiento total de mensajes, lo que garantiza el orden cronológico en todos los mensajes como parte de las operaciones de ventanas. Este método de ordenamiento difiere del enfoque basado en claves de ordenamiento de Pub/Sub. El uso de claves de ordenamiento con Dataflow puede reducir el rendimiento de la canalización.

  • Escalabilidad automática: La entrega ordenada de Pub/Sub se adapta a miles de millones de claves de ordenamiento. Una mayor cantidad de claves de ordenamiento permite una entrega más paralela a los suscriptores, ya que el ordenamiento se aplica a todos los mensajes con la misma clave de ordenamiento.

  • Compensaciones de rendimiento: La entrega ordenada tiene algunas compensaciones. En comparación con la entrega no ordenada, la entrega ordenada disminuye la disponibilidad de publicación y aumenta la latencia de entrega de mensajes de extremo a extremo. En el caso de la entrega ordenada, la conmutación por error requiere coordinación para garantizar que los mensajes se escriban y se lean en el orden correcto.

  • Clave activa: Cuando se usa el ordenamiento de mensajes, todos los mensajes con la misma clave de ordenamiento se envían a tu cliente suscriptor en el orden en que los recibe el servicio. La devolución de llamada del usuario no se ejecuta hasta que se completa la devolución de llamada para el mensaje anterior. La capacidad de procesamiento máxima para los mensajes que comparten la misma clave de ordenamiento cuando se entregan a los suscriptores no está limitada por Pub/Sub , sino por la velocidad de procesamiento de tu cliente suscriptor. Se produce una clave activa cuando se acumula un backlog en una clave de ordenamiento individual porque la cantidad de mensajes producidos por segundo supera la cantidad de mensajes que el suscriptor puede procesar por segundo. Para mitigar las claves activas, usa las claves más detalladas que puedas y minimiza el tiempo de procesamiento por mensaje. También puedes supervisar la métrica subscription/oldest_unacked_message_age para obtener un valor creciente, lo que podría indicar una clave activa.

Para obtener más información sobre cómo usar el ordenamiento de mensajes, consulta los siguientes temas de prácticas recomendadas:

Comportamiento del cliente suscriptor para el ordenamiento de mensajes

Los clientes suscriptores reciben mensajes en el orden en que se publicaron en una región específica. Pub/Sub admite diferentes formas de recibir mensajes, como clientes suscriptores conectados a suscripciones de extracción y de envío. Las bibliotecas cliente usan streamingPull (con la excepción de PHP).

Para obtener más información sobre estos tipos de suscripción, consulta Elige un tipo de suscripción.

En las siguientes secciones, se analiza lo que significa recibir mensajes en orden para cada tipo de cliente suscriptor.

Clientes suscriptores de streamingPull

Cuando usas las bibliotecas cliente con streamingPull, debes especificar una devolución de llamada del usuario que se ejecute cada vez que un cliente suscriptor reciba un mensaje. Con las bibliotecas cliente, para cualquier clave de ordenamiento determinada, la devolución de llamada se ejecuta hasta completarse en los mensajes en el orden correcto. Si los mensajes se confirman dentro de esa devolución de llamada, todos los cálculos en un mensaje se realizan en orden. Sin embargo, si la devolución de llamada del usuario programa otro trabajo asíncrono en los mensajes, el cliente suscriptor debe asegurarse de que el trabajo asíncrono se realice en orden. Una opción es agregar mensajes a una cola de trabajo local que se procesa en orden.

Clientes suscriptores de extracción

Para los clientes suscriptores conectados a suscripciones de extracción, el ordenamiento de mensajes de Pub/Sub admite lo siguiente:

  • Todos los mensajes de una clave de ordenamiento en el PullResponse están en el orden correcto en la lista.

  • Solo puede haber un lote de mensajes pendientes para una clave de ordenamiento a la vez.

El requisito de que solo pueda haber un lote de mensajes pendientes a la vez es necesario para mantener la entrega ordenada, ya que el servicio de Pub/Sub no puede garantizar el éxito ni la latencia de la respuesta que envía para la solicitud de extracción de un suscriptor.

Clientes suscriptores de envío

Las restricciones de envío son aún más estrictas que las de extracción. Para una suscripción de envío, Pub/Sub admite solo un mensaje pendiente para cada clave de ordenamiento a la vez. Cada mensaje se envía a un extremo de envío como una solicitud separada. Por lo tanto, enviar las solicitudes en paralelo tendría el mismo problema que entregar varios lotes de mensajes para la misma clave de ordenamiento a los suscriptores de extracción de forma simultánea. Es posible que las suscripciones de envío no sean una buena opción para los temas en los que los mensajes se publican con frecuencia con la misma clave de ordenamiento o en los que la latencia es extremadamente importante.

Clientes suscriptores de exportación

Las suscripciones de exportación admiten mensajes ordenados. Para las suscripciones de BigQuery, los mensajes con la misma clave de ordenamiento se escriben en su tabla de BigQuery en orden. Para las suscripciones de Cloud Storage, es posible que no todos los mensajes con la misma clave de ordenamiento se escriban en el mismo archivo. Cuando están dentro del mismo archivo, los mensajes para una clave de ordenamiento están en orden. Cuando se distribuyen en varios archivos, los mensajes posteriores para una clave de ordenamiento pueden aparecer en un archivo con un nombre que tiene una marca de tiempo anterior a la marca de tiempo en el nombre del archivo con los mensajes anteriores.

Habilita el ordenamiento de mensajes

Para recibir los mensajes en orden, configura la propiedad de ordenamiento de mensajes de la suscripción de la que recibes mensajes. Recibir mensajes en orden puede aumentar la latencia. No puedes cambiar la propiedad de ordenamiento de mensajes después de crear una suscripción.

Puedes configurar la propiedad de ordenamiento de mensajes cuando creas una suscripción con la Google Cloud consola, Google Cloud CLI o la API de Pub/Sub.

Console

Para crear una suscripción con la propiedad de ordenamiento de mensajes, sigue estos pasos:

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

Ir a Suscripciones

  1. Haz clic en Crear suscripción.

  2. Ingresa un ID de suscripción.

  3. Elige un tema del que deseas recibir mensajes.

  4. En la sección Ordenamiento de mensajes, selecciona Ordenar mensajes con una clave de ordenamiento.

  5. Haga clic en Crear.

gcloud

Para crear una suscripción con la propiedad de ordenamiento de mensajes, usa el gcloud pubsub subscriptions create comando y la --enable-message-ordering marca:

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --enable-message-ordering

Reemplaza SUBSCRIPTION_ID por el ID de la suscripción.

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

Created subscription [SUBSCRIPTION_ID].

REST

Para crear una suscripción con la propiedad de ordenamiento de mensajes, envía una solicitud PUT como la siguiente:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth application-default print-access-token)

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto con el tema
  • SUBSCRIPTION_ID: El ID de la suscripción

Especifica lo siguiente en el cuerpo de la solicitud:

{
  "topic": TOPIC_ID,
  "enableMessageOrdering": true,
}

Reemplaza TOPIC_ID por el ID del tema que deseas adjuntar a la suscripción.

Si la solicitud se realiza de forma correcta, la respuesta es la suscripción en formato JSON:

{
  "name": projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID,
  "topic": projects/PROJECT_ID/topics/TOPIC_ID,
  "enableMessageOrdering": true,
}

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) {
  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.set_enable_message_ordering(true);
  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;
using Grpc.Core;

public class CreateSubscriptionWithOrderingSample
{
    public Subscription CreateSubscriptionWithOrdering(string projectId, string topicId, string subscriptionId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        var topicName = TopicName.FromProjectTopic(projectId, topicId);
        var subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            EnableMessageOrdering = true
        };

        Subscription subscription = null;
        try
        {
            subscription = subscriber.CreateSubscription(subscriptionRequest);
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            // Already exists.  That's fine.
        }
        return subscription;
    }
}

Go

En la siguiente muestra, se usa la versión principal de la biblioteca cliente de Go Pub/Sub (v2). Si aún usas la biblioteca v1, consulta la guía de migración a la v2. Para ver una lista de muestras de código de la v1, consulta las muestras de código obsoletas.

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 createWithOrdering(w io.Writer, projectID, topic, subscription string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	// Message ordering can only be set when creating a subscription.
	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:                  subscription,
		Topic:                 topic,
		EnableMessageOrdering: true,
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription: %v\n", sub)
	return nil
}

Java

Antes de probar esta muestra, sigue las instrucciones de configuración de Java 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.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateSubscriptionWithOrdering {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";

    createSubscriptionWithOrderingExample(projectId, topicId, subscriptionId);
  }

  public static void createSubscriptionWithOrderingExample(
      String projectId, String topicId, String subscriptionId) throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  // Set message ordering to true for ordered messages in the subscription.
                  .setEnableMessageOrdering(true)
                  .build());

      System.out.println("Created a subscription with ordering: " + subscription.getAllFields());
    }
  }
}

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 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 createSubscriptionWithOrdering(
  topicNameOrId,
  subscriptionNameOrId,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, {
      enableMessageOrdering: true,
    });
  console.log(
    `Created subscription ${subscriptionNameOrId} with ordering enabled.`,
  );
  console.log(
    'To process messages in order, remember to add an ordering key to your messages.',
  );
}

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 topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';

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

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

async function createSubscriptionWithOrdering(
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, {
      enableMessageOrdering: true,
    });
  console.log(
    `Created subscription ${subscriptionNameOrId} with ordering enabled.`,
  );
  console.log(
    'To process messages in order, remember to add an ordering key to your messages.',
  );
}

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): Choose an existing topic.
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "enable_message_ordering": True,
        }
    )
    print(f"Created subscription with ordering: {subscription}")

Ruby

En la siguiente muestra, se usa la biblioteca cliente de Ruby Pub/Sub v3. Si aún usas la biblioteca v2, consulta la guía de migración a la v3. Para ver una lista de muestras de código de Ruby v2, consulta las muestras de código obsoletas.

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"

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),
  enable_message_ordering: true

puts "Pull subscription #{subscription_id} created with message ordering."

¿Qué sigue?