Exportar mensagens do Pub/Sub Lite para o Pub/Sub

Observação: o Pub/Sub Lite foi descontinuado. A partir de 18 de março de 2026, o Pub/Sub Lite será desativado.

• Clientes atuais: o Pub/Sub Lite vai continuar funcional até 18 de março de 2026. Se você não tiver usado o Pub/Sub Lite no período de 90 dias anterior a 24 de setembro de 2024 (26 de junho de 2024 a 24 de setembro de 2024), não será possível acessar o Pub/Sub Lite a partir de 24 de setembro de 2024.
• Novos clientes: o Pub/Sub Lite não estará mais disponível para novos clientes depois de 24 de setembro de 2024.

É possível migrar o serviço Pub/Sub Lite para o Google Cloud Managed Service para Apache Kafka ou o Pub/Sub.

Este documento descreve como configurar a exportação automática de mensagens do Pub/Sub Lite para o Pub/Sub.

Confira alguns cenários em que você pode usar esse recurso:

• Interoperação entre cargas de trabalho que usam uma combinação do Pub/Sub Lite e do Pub/Sub.
• Migre uma carga de trabalho do Pub/Sub Lite para o Pub/Sub.
• Use recursos avançados do Pub/Sub, como assinaturas de push e filtragem, em um aplicativo baseado no Pub/Sub Lite.
• Consolidar vários pipelines de dados.

Visão geral

Para exportar mensagens do Pub/Sub Lite para o Pub/Sub, crie um tipo especial de assinatura chamado assinatura de exportação. Uma assinatura de exportação recebe mensagens de um tópico do Lite, as converte em mensagens do Pub/Sub e as envia para um tópico de destino do Pub/Sub.

Um tópico Lite pode ter uma combinação de assinaturas de exportação e padrão. Os dois tipos de assinatura são idênticos em termos de uso de cota e taxa de transferência de reserva. Uma assinatura de exportação consome a capacidade de capacidade de inscrição do Lite e é cobrada pelo throughput de publicação do Pub/Sub.

Uma assinatura de exportação conecta um tópico do Lite a exatamente um tópico do Pub/Sub. No entanto, um tópico Lite pode ter várias assinaturas de exportação que se conectam a diferentes tópicos do Pub/Sub (arquitetura fan-out). Também é possível exportar de vários tópicos Lite para o mesmo tópico do Pub/Sub (arquitetura fan-in).

Autenticação

Uma assinatura de exportação acessa os recursos do Pub/Sub Lite e do Pub/Sub. Para criar uma assinatura de exportação, você precisa das seguintes permissões:

• pubsublite.subscriptions.create. Os papéis predefinidos a seguir contêm essa permissão:

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

  Consulte Controle de acesso do Pub/Sub Lite.

• pubsub.topics.get. Os seguintes papéis predefinidos contêm essa permissão:

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

  Consulte Controle de acesso do Pub/Sub.

Agentes de serviço

Uma assinatura de exportação é publicada em um tópico do Pub/Sub em seu nome. Para isso, ele usa um agente de serviço.

Depois de criar a primeira assinatura de exportação em um projeto, um agente de serviço do Pub/Sub Lite é criado automaticamente. Se você criar outras assinaturas de exportação no mesmo projeto, elas vão usar o mesmo agente de serviço. O agente de serviço tem o seguinte esquema de nomenclatura: service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com.

O agente de serviço é criado com permissões para publicar em todos os tópicos do Pub/Sub e do Pub/Sub Lite no mesmo projeto da assinatura de exportação. Se o tópico do Pub/Sub de destino estiver em um projeto diferente da assinatura de exportação, será necessário conceder ao agente de serviço permissões adicionais adicionando o papel de Editor do Pub/Sub (roles/pubsub.publisher). É possível conceder permissões para um projeto inteiro ou um tópico individual. Recomendamos conceder permissões no nível do tópico, seguindo o princípio de privilégio mínimo.

Para mais informações, consulte Como controlar o acesso pelo console do Google Cloud. Também é possível usar o comando gcloud projects add-iam-policy-binding para adicionar papéis de IAM:

gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \
 --member=serviceAccount:[e-mail]
 --role=roles/pubsub.publisher

Substitua:

• TOPIC_NAME: o nome do tópico do Pub/Sub de destino para adicionar a vinculação de política do IAM.
• PROJECT_NUMBER: o número do projeto da assinatura de exportação do Pub/Sub Lite.

Criar uma assinatura de exportação

É possível criar uma assinatura de exportação do Lite usando o console do Google Cloud, a Google Cloud CLI ou a API Pub/Sub Lite.

Uma assinatura de exportação do Lite precisa estar no mesmo projeto e local do tópico do Lite anexado. Para criar o tópico do Lite, consulte Criar e gerenciar tópicos do Lite.

Se você anexar uma assinatura de exportação a um tópico do Lite, verifique se todas as mensagens publicadas no tópico do Lite são compatíveis com o Pub/Sub. Para mais informações, consulte Compatibilidade de mensagens.

Depois que ela é criada, não é possível mudar uma assinatura de exportação para uma padrão ou vice-versa.

Console

1. Acesse a página Assinaturas Lite.

   Acessar "Assinaturas Lite"

2. Clique em Criar assinatura do Lite.

3. Insira um ID de assinatura do Lite.

4. Selecione um tópico do Lite para receber mensagens.

5. Selecione Entregar mensagens imediatamente ou Entregar mensagens após o armazenamento.

6. Escolha um tipo de Deslocamento inicial.

7. Selecione Exportar para o tópico do Pub/Sub.

8. Na lista Tópico de destino, escolha um tópico do Pub/Sub para receber as mensagens exportadas do Lite.

9. Opcional. Especifique um tópico de mensagens inativas.

   1. Marque a caixa de seleção Ativar mensagens mortas.
   2. Selecione um tópico do Lite para usar como tópico de mensagens inativas ou clique em Criar tópico do Lite para criar um novo tópico de mensagens inativas. O tópico de mensagens inativas precisa estar no mesmo local (zona ou região) e projeto que a assinatura de exportação.

10. Clique em Criar.

gcloud

Para criar uma assinatura de exportação, use o 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

Substitua:

• SUBSCRIPTION_ID: o ID da assinatura Lite a ser criada.
• LOCATION: o local da assinatura do Lite.
• TOPIC_ID: o ID do tópico do Lite a ser anexado à assinatura do Lite.
• PUBSUB_TOPIC_NAME: o nome do tópico do Pub/Sub para exportar. Especifique o nome completo se o tópico estiver em outro projeto: projects/my-project-id/topics/my-topic-id.
• DEAD_LETTER_TOPIC_ID: opcional. O ID de um tópico do Lite a ser usado como mensagem inativa. O tópico de mensagens inativas precisa estar no mesmo local (zona ou região) e projeto da assinatura de exportação.
• DESIRED_STATE: opcional. O estado inicial da assinatura. Os valores a seguir são compatíveis:
  • active: a assinatura exporta mensagens do Lite para o Pub/Sub. (padrão).
  • paused: a exportação de mensagens do Lite é suspensa.

Se a solicitação for bem-sucedida, a linha de comando exibirá uma confirmação:

Created [SUBSCRIPTION_ID].

Protocolo

Para criar uma assinatura de exportação do Lite, envie uma solicitação POST como esta:

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

Substitua:

• REGION: a região em que a assinatura do Lite será armazenada.
• PROJECT_NUMBER: o número do projeto para criar a assinatura do Lite.
• LOCATION: o nome de um local compatível com o Pub/Sub Lite.
• SUBSCRIPTION_ID: o ID da assinatura do Lite.

Especifique os campos a seguir no corpo da solicitação:

{
  "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"
      }
  }
}

Substitua:

• DELIVERY_REQUIREMENT: o requisito de entrega, DELIVER_AFTER_STORED ou DELIVER_IMMEDIATELY.
• DESIRED_STATE: o estado inicial da assinatura. Os seguintes valores são aceitos:
  • ACTIVE: a assinatura exporta mensagens do Lite para o Pub/Sub.
  • PAUSED: a exportação de mensagens do Lite é suspensa.
• DEAD_LETTER_TOPIC_ID: o ID de um tópico do Lite para usar como tópico de mensagens inativas. O tópico precisa estar no mesmo local (zona ou região) e projeto que a própria assinatura de exportação.
• PUBSUB_TOPIC_NAME: o nome do tópico do Pub/Sub para exportar. Exemplo de formato: projects/my-project-id/topics/my-topic-id.

Se a solicitação for bem-sucedida, a resposta será a assinatura do Lite no 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",
}

Go

Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub 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: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Created export subscription: %s\n", sub.Name)
	return nil
}

Java

Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do 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 executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do 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.")

Atualizar uma assinatura de exportação

É possível atualizar assinaturas do Lite com o console do Google Cloud, a Google Cloud CLI ou a API Pub/Sub Lite. Pode levar até 30 segundos para que as novas configurações sejam aplicadas.

Console

1. Acesse a página Assinaturas Lite.

   Acessar as assinaturas do Lite

2. Clique no ID da assinatura do Lite.

3. Na página Detalhes da assinatura do Lite, clique em Editar.

gCloud

Para atualizar uma assinatura do Lite, use o 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

Substitua:

• SUBSCRIPTION_ID: o ID da assinatura do Lite
• LOCATION: o local da assinatura do Lite.
• DELIVERY_REQUIREMENT: opcional. O requisito de entrega, deliver-after-stored ou deliver-immediately.
• PUBSUB_TOPIC_NAME: opcional. O nome do tópico do Pub/Sub para exportar. Especifique o nome completo se o tópico estiver em um projeto diferente: projects/my-project-id/topics/my-topic-id.
• DEAD_LETTER_TOPIC_ID: o ID de um tópico do Lite para usar como tópico de mensagens inativas. O tópico precisa estar no mesmo local (zona ou região) e projeto que a própria assinatura de exportação.
• DESIRED_STATE: opcional. O estado desejado da assinatura. Os valores a seguir são compatíveis:
  • active: a assinatura exporta mensagens do Lite para o Pub/Sub. (padrão).
  • paused: a exportação de mensagens do Lite é suspensa.

Se a solicitação for bem-sucedida, a linha de comando exibirá a assinatura do 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 atualizar uma assinatura Lite, envie uma solicitação PATCH como esta:

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)

Substitua:

• REGION: a região em que a assinatura do Lite foi criada.
• PROJECT_NUMBER: o número do projeto em que a assinatura do Lite foi criada.
• LOCATION: o local em que a assinatura do Lite foi criada.
• SUBSCRIPTION_ID: o ID da assinatura do Lite.

Especifique os campos a seguir no corpo da solicitação:

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

Substitua:

• DELIVERY_REQUIREMENT: o requisito de entrega, DELIVER_AFTER_STORED ou DELIVER_IMMEDIATELY.
• DESIRED_STATE: o estado desejado para a assinatura. Os seguintes valores são aceitos:
  • ACTIVE: a assinatura exporta mensagens do Lite para o Pub/Sub.
  • PAUSED: a exportação de mensagens do Lite é suspensa.
• DEAD_LETTER_TOPIC_ID: o ID de um tópico do Lite para usar como tópico de mensagens inativas. O tópico precisa estar no mesmo local (zona ou região) e projeto que a própria assinatura de exportação.
• PUBSUB_TOPIC_NAME: o nome do tópico do Pub/Sub de destino. Exemplo de formato: projects/my-project-id/topics/my-topic-id.

Se a solicitação for bem-sucedida, a resposta será a assinatura do Lite no 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",
}

Pausar ou iniciar uma assinatura de exportação

As assinaturas de exportação têm uma configuração chamada estado desejado, que tem um destes dois valores:

• Ativo: a assinatura exporta mensagens do Lite para o Pub/Sub.
• Pausada: a exportação de mensagens do Lite está suspensa.

Para mudar o estado desejado no console do Google Cloud:

1. Acesse a página Assinaturas Lite.

   Acessar as assinaturas do Lite

2. Clique no ID da assinatura do Lite.

3. Na página Detalhes da assinatura do Lite, clique em Pausar ou Iniciar.

Também é possível atualizar o estado desejado usando a Google Cloud CLI ou a API Pub/Sub Lite. Consulte Atualizar uma assinatura de exportação.

Práticas recomendadas

Esta seção descreve algumas práticas recomendadas ao usar assinaturas de exportação.

Reservas

Recomendamos usar uma assinatura de exportação com uma reserva em vez de definir explicitamente a capacidade de transferência da assinatura.

Compatibilidade de mensagens

Se uma mensagem do Pub/Sub Lite não for compatível com o Pub/Sub, a assinatura de exportação não vai publicar a mensagem no Pub/Sub. Em vez disso, ela coloca a mensagem no tópico de mensagens inativas, se um tiver sido atribuído. Se nenhum tópico de mensagens inativas foi atribuído, as mensagens incompatíveis são simplesmente descartadas.

Ao publicar mensagens no tópico do Lite, esteja ciente dos seguintes problemas de compatibilidade:

• Chaves. As chaves do Pub/Sub Lite são do tipo bytes, enquanto as chaves de ordenação do Pub/Sub são do tipo string. Para ser compatível, a chave do Pub/Sub Lite precisa conter apenas caracteres UTF-8.

• Atributos. Os atributos de mensagem têm os seguintes requisitos:

  • Para ser compatível, todos os atributos de mensagem do Pub/Sub Lite precisam ter um único valor. O Pub/Sub Lite oferece suporte a atributos de mensagem com vários valores, mas o Pub/Sub só oferece suporte a atributos de valor único.
  • Os atributos da mensagem não podem exceder os limites de mensagens do Pub/Sub, incluindo o número máximo de atributos por mensagem e o tamanho máximo de chave e valor por atributo.

Tópico de mensagens inativas

Para reter e processar mensagens incompatíveis, recomendamos usar um tópico de mensagens inativas. É possível atribuir um tópico de mensagens inativas ao criar a assinatura de exportação ou atualizar uma assinatura de exportação para usar um tópico de mensagens inativas. Se a assinatura receber uma mensagem incompatível com o Pub/Sub, ela vai publicar a mensagem no tópico de mensagens inativas.

Um tópico de mensagens inativas é um tópico normal do Pub/Sub Lite. Ele precisa estar no mesmo local e projeto da assinatura de exportação e ser um tópico diferente do tópico de origem.

Normalmente, um tópico de mensagens inativas tem baixa utilização de capacidade. Portanto, recomendamos atribuir uma reserva ao tópico de mensagens inativas em vez de alocar a capacidade de processamento ao tópico.

Erros de entrega

Uma assinatura de exportação tenta entregar todas as mensagens compatíveis ao tópico do Pub/Sub de destino. Se a entrega da mensagem falhar, a assinatura de exportação será suspensa. Para encontrar a categoria de erro, verifique a métrica subscription/export_status. Os valores a seguir indicam um erro:

• PERMISSION_DENIED: permissões insuficientes para exportar mensagens.
• NOT_FOUND: um ou mais recursos não foram encontrados. Por exemplo, o tópico de destino não existe.

Para mais informações sobre a solução de problemas, consulte Resolver problemas com as assinaturas de exportação.

Depois que você resolve o erro, a assinatura de exportação é reiniciada automaticamente devido a novas tentativas periódicas.

Preços

Você vai receber cobranças pelos recursos do Pub/Sub Lite e do Pub/Sub que a assinatura de exportação consome. Especificamente, você vai pagar pela capacidade e pelo armazenamento alocados na assinatura do Pub/Sub Lite, que são configurados para o tópico do Pub/Sub Lite. Você também vai receber cobranças por publicar no tópico de destino do Pub/Sub. Consulte os preços do Pub/Sub.

Não há cobranças extras pelo uso do recurso de exportação, e não há diferença de preço entre as assinaturas de exportação do Pub/Sub Lite e as assinaturas padrão.

Resolver problemas com as inscrições de exportação

Esta seção descreve algumas dicas de solução de problemas para exportar assinaturas.

A assinatura de exportação está pausada

Se a assinatura for pausada, nenhuma mensagem será exportada.

Para detectar esse problema:

• Console do Google Cloud: confira os detalhes da assinatura. Se a assinatura estiver pausada, Estado desejado e Estado atual serão Paused.

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

Para resolver esse problema, inicie a assinatura.

O tópico de destino ou tópico de mensagens inativas foi excluído

Se você excluir o tópico do Pub/Sub anexado a uma assinatura de exportação ou o tópico de mensagens inativas, um erro vai ocorrer.

Para detectar esse problema:

• Console do Google Cloud: confira os detalhes da assinatura. Se o tópico foi excluído, o estado atual é Not found.

• Métricas: a métrica subscription/export_status. Se o tópico foi excluído, o valor será NOT_FOUND.

Para resolver esse problema, verifique o tópico do Pub/Sub de destino e o tópico de mensagens inativas (se um foi configurado).

Se o Pub/Sub de destino foi excluído, recrie o tópico com o mesmo nome. A assinatura de exportação retoma a publicação, supondo que as permissões não tenham mudado.

Se o tópico de mensagens inativas foi excluído, crie um novo tópico e atualize a assinatura de exportação para fazer referência a ele.

Mensagens incompatíveis

Se as mensagens forem incompatíveis com o Pub/Sub, elas não serão exportadas.

Para detectar esse problema:

• Métricas: a métrica subscription/unexportable_message_count mostra a contagem de mensagens incompatíveis que não puderam ser exportadas.

Para resolver esse problema, use um tópico de mensagens inativas para reter as mensagens incompatíveis. Examine as mensagens para determinar a causa e, em seguida, transforme e publique novamente, se necessário. Consulte Compatibilidade de mensagens.

A exportação é limitada

Para detectar esse problema:

• Métricas: a métrica subscription/flow_control_status mostra um motivo de controle de fluxo de NO_CLIENT_TOKENS, o que indica que o limite por partição de bytes ou mensagens pendentes foi atingido. Até que o problema seja resolvido, o volume de trabalho vai aumentar para as assinaturas de exportação associadas.

Esse erro tem várias causas raiz possíveis. A maioria das causas possíveis ocorre no back-end, mas verifique o seguinte:

• Publique mensagens Lite que compartilham a mesma chave a uma taxa de menos de 1 MiB/s por chave. A assinatura de exportação grava chaves de mensagem do Lite como chaves de ordenação do Pub/Sub, e o Pub/Sub tem um limite de 1 MiB/s em cada chave de ordenação. Exceder esse limite pode causar limitação.

O usuário não tem autorização para realizar essa ação

O agente de serviço do Pub/Sub Lite precisa ter permissões para publicar no tópico de destino do Pub/Sub.

Para detectar esse problema:

• Console do Google Cloud: confira os detalhes da assinatura. Se houver erros de permissão, o estado atual será Permission denied.

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

Por exemplo, as seguintes situações podem causar esse erro:

• O agente de serviço do Pub/Sub Lite não tem a permissão ou o papel correto para publicar mensagens no tópico de destino do Pub/Sub em um projeto diferente.
• O agente de serviço foi removido da política do IAM do projeto pai da assinatura de exportação.
• O agente de serviço do Pub/Sub Lite ainda está sendo configurado. Um agente de serviço é criado automaticamente quando você cria a primeira assinatura de exportação em um projeto. O erro de permissão será resolvido automaticamente em até 10 minutos.

Para resolver o problema, verifique se o agente de serviço recebeu a permissão ou o papel correto. Consulte Agentes de serviço.

A seguir

Escolha entre o Pub/Sub e o Pub/Sub Lite.