Entrega exatamente uma vez

Esta página explica como receber e acusar a receção de mensagens através da funcionalidade exatamente uma vez do Pub/Sub, que lhe permite acompanhar e impedir o processamento duplicado de mensagens. Quando a funcionalidade está ativada, o Pub/Sub oferece a seguinte semântica:

• Os subscritores podem determinar se os reconhecimentos de mensagens foram bem-sucedidos.

• Não ocorre uma nova entrega após a mensagem ser reconhecida com êxito.

• Não ocorre reenvio enquanto houver uma mensagem pendente. Uma mensagem é considerada pendente até o prazo de confirmação expirar ou a mensagem ser confirmada.

• No caso de várias entregas válidas, devido à expiração do prazo de confirmação ou à confirmação negativa iniciada pelo cliente, só é possível usar o ID de confirmação mais recente para confirmar a mensagem. Todas as solicitações com um ID de confirmação anterior falham.

Com a opção "Exatamente uma vez" ativada, os subscritores podem garantir que as mensagens são processadas uma vez seguindo estas diretrizes:

• Confirmar a receção de mensagens dentro do prazo de confirmação.

• Manter informações sobre o progresso do processamento de uma mensagem até que seja confirmada com êxito.

• Use as informações sobre o progresso do processamento de uma mensagem para evitar trabalho duplicado quando uma confirmação falha.

Apenas o tipo de subscrição pull suporta a entrega exatamente uma vez, incluindo subscritores que usam a API StreamingPull. As subscrições de envio e exportação não suportam a entrega exatamente uma vez.

O Pub/Sub suporta a entrega exatamente uma vez, numa região da nuvem, com base num ID da mensagem exclusivo definido pelo Pub/Sub.

Versões da biblioteca cliente recomendadas

• Para um melhor desempenho, use a versão mais recente da biblioteca cliente, Python v2.13.6 ou superior, Java v1.139.0 ou superior, PHP v1.39.0 ou superior, C# v3.2.0 ou superior, C++ v2.1.0, Go v1.25.1 ou superior, Node v3.2.0 ou superior e Ruby v2.12.1 ou superior.

Reenvio versus duplicado

É importante compreender a diferença entre reenvios esperados e inesperados.

• Uma nova entrega pode ocorrer devido a uma confirmação negativa iniciada pelo cliente de uma mensagem ou quando o cliente não prolonga o prazo de confirmação da mensagem antes de este expirar. As reentregas são consideradas válidas e o sistema está a funcionar conforme previsto.

  Para resolver problemas de reenvios, consulte o artigo Lidar com duplicados.

• Um duplicado ocorre quando uma mensagem é reenviada após uma confirmação bem-sucedida ou antes da expiração do prazo de confirmação.

• Uma mensagem reenviada mantém o mesmo ID da mensagem entre as tentativas de reenvio.

As subscrições com a entrega exatamente uma vez ativada não recebem entregas duplicadas.

Suporte de entrega exatamente uma vez nas bibliotecas cliente

• As bibliotecas cliente suportadas têm uma interface para confirmação com resposta (exemplo: Go). Pode usar esta interface para verificar se o pedido de confirmação foi bem-sucedido. Se o pedido de confirmação for bem-sucedido, é garantido que os clientes não recebem uma nova entrega. Se o pedido de confirmação falhar, os clientes podem esperar uma nova entrega.

• Os clientes também podem usar as bibliotecas de cliente suportadas sem a interface de confirmação. No entanto, nestes casos, as falhas de confirmação podem levar a reenvios silenciosos de mensagens.

• As bibliotecas cliente suportadas têm interfaces para definir o tempo mínimo de extensão do aluguer (exemplo: Go). Tem de definir o valor da extensão mínima de concessão para um número elevado para evitar expirações de confirmação relacionadas com a rede. O valor máximo é de 600 segundos.

• Se estiver a usar a biblioteca de cliente Java e inicializar o subscritor com um canal gRPC personalizado através do método setChannelProvider(), é recomendável que também defina maxInboundMetadataSize para, pelo menos, 1 MB quando criar o TransportChannelProvider. Para esta configuração, pode usar o método InstantiatingGrpcChannelProvider.Builder.setMaxInboundMetadataSize() ou o método ManagedChannelBuilder.maxInboundMetadataSize().

Os valores predefinidos e o intervalo das variáveis relacionadas com a entrega exatamente uma vez e os nomes das variáveis podem diferir entre as bibliotecas de cliente. Por exemplo, na biblioteca cliente Java, as seguintes variáveis controlam o fornecimento exatamente uma vez.

No caso da entrega exatamente uma vez, o pedido modifyAckDeadline ou acknowledgment para o Pub/Sub falha quando o ID de confirmação já expirou. Nestes casos, o serviço considera o ID de confirmação expirado como inválido, uma vez que pode já estar em curso uma entrega mais recente. Isto é intencional para a entrega exatamente uma vez. Em seguida, vê que os pedidos acknowledgment e ModifyAckDeadline devolvem uma resposta INVALID_ARGUMENT. Quando a entrega exatamente uma vez está desativada, estes pedidos devolvem OK nos casos de IDs de confirmação expirados.

Para garantir que os pedidos acknowledgment e ModifyAckDeadline têm IDs de confirmação válidos, considere definir o valor de minDurationPerAckExtension para um número elevado.

Considerações regionais

A garantia de entrega exatamente uma vez só se aplica quando os subscritores se ligam ao serviço na mesma região. Se a sua aplicação de subscrição estiver distribuída por várias regiões, pode levar à entrega de mensagens duplicadas, mesmo quando a entrega exatamente uma vez está ativada. Os publicadores podem enviar mensagens para qualquer região e a garantia de exatamente uma vez é mantida.

Quando executa a sua aplicação no Google Cloud, por predefinição, esta liga-se ao ponto final do Pub/Sub na mesma região. Por conseguinte, a execução da sua aplicação numa única região dentro do Google Cloud geralmente garante que está a interagir com uma única região.

Quando executa a sua aplicação subscritora fora de Google Cloud ou em várias regiões, pode garantir que está a estabelecer ligação a uma única região usando um ponto final de localização ao configurar o cliente do Pub/Sub. Todos os pontos finais de localização do Pub/Sub apontam para regiões únicas. Para saber mais acerca dos pontos finais de localização, consulte o artigo Pontos finais do Pub/Sub. Para ver uma lista de todos os pontos finais de localização do Pub/Sub, consulte a Lista de pontos finais de localização.

Crie subscrições com entrega exatamente uma vez

Pode criar uma subscrição com entrega exatamente uma vez através da Google Cloud consola, da Google Cloud CLI, da biblioteca cliente ou da API Pub/Sub.

Subscrição de obtenção

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --enable-exactly-once-delivery

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

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "enableExactlyOnceDelivery": true,
}

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_exactly_once_delivery(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";
}

using Google.Cloud.PubSub.V1;
using Grpc.Core;

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

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            EnableExactlyOnceDelivery = 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;
    }
}

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

func createSubscriptionWithExactlyOnceDelivery(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()

	pbSub := &pubsubpb.Subscription{
		Name:                      subscription,
		Topic:                     topic,
		EnableExactlyOnceDelivery: true,
	}
	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, pbSub)
	if err != nil {
		return fmt.Errorf("failed to create exactly once sub: %w", err)
	}
	fmt.Fprintf(w, "Created a subscription with exactly once delivery enabled: %v\n", sub)
	return nil
}

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 CreateSubscriptionWithExactlyOnceDelivery {
  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";

    createSubscriptionWithExactlyOnceDeliveryExample(projectId, topicId, subscriptionId);
  }

  public static void createSubscriptionWithExactlyOnceDeliveryExample(
      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())
                  // Enable exactly once delivery in the subscription.
                  .setEnableExactlyOnceDelivery(true)
                  .build());

      System.out.println(
          "Created a subscription with exactly once delivery enabled: "
              + subscription.getAllFields());
    }
  }
}

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_exactly_once_delivery": True,
        }
    )
    print(
        f"Created subscription with exactly once delivery enabled: {subscription}"
    )

/**
 * 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 createSubscriptionWithExactlyOnceDelivery(
  topicNameOrId,
  subscriptionNameOrId,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, {
      enableExactlyOnceDelivery: true,
    });
  console.log(
    `Created subscription ${subscriptionNameOrId} with exactly-once delivery.`,
  );
  console.log(
    'To process messages, remember to check the return value of ackWithResponse().',
  );
}

/**
 * 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 createSubscriptionWithExactlyOnceDelivery(
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, {
      enableExactlyOnceDelivery: true,
    });
  console.log(
    `Created subscription ${subscriptionNameOrId} with exactly-once delivery.`,
  );
  console.log(
    'To process messages, remember to check the return value of ackWithResponse().',
  );
}

# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"

pubsub = Google::Cloud::PubSub.new project_id: project_id
subscription_admin = pubsub.subscription_admin

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id),
  enable_exactly_once_delivery: true

puts "Created subscription with exactly once delivery enabled: " \
     "#{subscription_id}"

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub subscription with `Exactly Once Delivery` enabled.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 */
function create_subscription_with_exactly_once_delivery(
    string $projectId,
    string $topicName,
    string $subscriptionName
): void {
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create([
        'enableExactlyOnceDelivery' => true
    ]);

    // Exactly Once Delivery status for the subscription
    $status = $subscription->info()['enableExactlyOnceDelivery'];

    printf('Subscription created with exactly once delivery status: %s' . PHP_EOL, $status ? 'true' : 'false');
}

Monitorize as subscrições de fornecimento exatamente uma vez

A métrica subscription/exactly_once_warning_count regista o número de eventos que podem levar a possíveis reentregas (válidas ou duplicadas). Esta métrica contabiliza o número de vezes que o Pub/Sub não processa pedidos associados a IDs de confirmação (pedido ModifyAckDeadline ou acknowledgment). Os motivos da falha podem ser baseados no servidor ou no cliente. Por exemplo, se a camada de persistência usada para manter as informações de entrega exatamente uma vez não estiver disponível, seria um evento baseado no servidor. Se o cliente tentar acusar a receção de uma mensagem com um ID de acusação de receção inválido, trata-se de um evento baseado no cliente.

Compreenda a métrica

subscription/exactly_once_warning_count capta eventos que podem ou não resultar em reenvios reais e podem ser ruidosos com base no comportamento do cliente. Por exemplo: os pedidos acknowledgment ou ModifyAckDeadline repetidos com IDs de confirmação inválidos incrementam a métrica repetidamente.

As seguintes métricas também são úteis para compreender o comportamento do cliente:

• subscription/expired_ack_deadlines_count A métrica mostra o número de expirações do ID de confirmação. O ID de confirmação expira e pode levar a falhas nos pedidos ModifyAckDeadline e acknowledgment.

• service.serviceruntime.googleapis.com/api/request_countA métrica pode ser usada para captar falhas de pedidos ModifyAckDeadline ou acknowledgment nos casos em que os pedidos chegam ao Google Cloud , mas não chegam ao Pub/Sub. Existem falhas que esta métrica não captura, por exemplo, quando os clientes estão desligados do Google Cloud.

Na maioria dos casos de eventos de falha que podem ser repetidos, as bibliotecas de cliente suportadas repetem o pedido automaticamente.

Quotas

As subscrições de entrega única estão sujeitas a requisitos de quota adicionais. Estas quotas são aplicadas:

• Número de mensagens consumidas de subscrições com entrega exatamente uma vez ativada por região.
• Número de mensagens reconhecidas ou cujo prazo é prolongado quando usa subscrições com a entrega exatamente uma vez ativada por região.

Para mais informações acerca destas quotas, consulte a tabela no tópico Quotas.

Entrega exatamente uma vez e subscrições ordenadas

O Pub/Sub suporta a entrega exatamente uma vez com a entrega ordenada.

Quando usar a ordenação com a entrega exatamente uma vez, o Pub/Sub espera que as confirmações estejam em ordem. Se as confirmações estiverem desordenadas, o serviço falha os pedidos com erros temporários. Se o prazo de confirmação expirar antes de uma confirmação em ordem para a entrega, o cliente recebe uma nova entrega da mensagem. Devido a isto, quando usa a ordenação com o fornecimento exatamente uma vez, o débito do cliente é limitado a uma ordem de mil mensagens por segundo.

Subscrições push e entrega exatamente uma vez

O Pub/Sub suporta a entrega exatamente uma vez apenas com subscrições de obtenção.

Os clientes que consomem mensagens das subscrições push confirmam as mensagens respondendo aos pedidos push com uma resposta bem-sucedida. No entanto, os clientes não sabem se a subscrição do Pub/Sub recebeu a resposta e a processou. Isto é diferente das subscrições de obtenção, em que os pedidos de confirmação são iniciados pelos clientes e a subscrição do Pub/Sub responde se o pedido foi processado com êxito. Por este motivo, a semântica de entrega exatamente uma vez não se alinha bem com as subscrições push.

Factos importantes

• Se o prazo de confirmação não for especificado no momento de criação da subscrição, as subscrições com entrega única têm um prazo de confirmação predefinido de 60 segundos.

• Os prazos de confirmação predefinidos mais longos são benéficos para evitar o reenvio causado por eventos de rede. As bibliotecas cliente suportadas não usam o prazo de confirmação da subscrição predefinido.

• As subscrições de entrega única têm uma latência de publicação para subscrição significativamente mais elevada em comparação com as subscrições normais.

• Se precisar de um débito elevado, os seus clientes de entrega exatamente uma vez também têm de usar a obtenção de streaming.

• Uma subscrição pode receber várias cópias da mesma mensagem devido a duplicados do lado da publicação, mesmo com a entrega exatamente uma vez ativada. Os duplicados do lado da publicação podem dever-se a várias novas tentativas de publicação únicas por parte do cliente de publicação ou do serviço Pub/Sub. Várias publicações únicas pelo cliente de publicação, em várias tentativas, resultam em reenvios com diferentes IDs de mensagens. As várias publicações únicas do serviço Pub/Sub, para responder a um pedido de publicação do cliente, resultam em reenvios com os mesmos IDs das mensagens.

• Pode tentar novamente as falhas em subscription/exactly_once_warning_count, e as bibliotecas de cliente suportadas tentam novamente estas falhas automaticamente. No entanto, não é possível tentar novamente as falhas relacionadas com IDs de confirmação inválidos.