Como criar e gerenciar tópicos do Lite

Esta página explica como criar, ver e excluir tópicos do Lite.

Os tópicos Lite são recursos por zona em que é possível publicar mensagens. Ao criar um tópico do Lite, você precisa especificar uma zona em que as mensagens serão armazenadas.

Depois de criar um tópico do Lite, é possível publicar mensagens nele, criar uma assinatura do Lite no tópico e receber mensagens da assinatura do Lite.

Como criar tópicos do Lite

Ao criar um tópico do Lite, você precisa definir a capacidade e o armazenamento dele. O número e a capacidade de partições determinam a capacidade de um tópico do Lite.

Os tópicos do Lite têm as seguintes propriedades:

  • Número de partições: o número de partições no tópico "Lite".
  • Armazenamento por partição: a quantidade de armazenamento, em bytes, de cada partição. É possível especificar de 30 GiB a 10 TiB de armazenamento.
  • Capacidade de publicação: a capacidade máxima de publicação de cada partição. É possível especificar de 4 a 16 MiB por segundo de capacidade, e o valor precisa ser um número inteiro. Para melhores resultados, crie um tópico do Lite com a capacidade mínima de publicação. Se o tráfego aumentar, atualize o tópico do Lite e aumente a capacidade de publicação.
  • Capacidade de assinatura: a capacidade máxima de assinatura de cada partição. É possível especificar de 4 a 32 MiB por segundo de capacidade, e o valor precisa ser um número inteiro.

  • Período de retenção de mensagens: a quantidade máxima de tempo que um tópico do Lite armazena mensagens. Se você não especificar um período de armazenamento de mensagens, o tópico Lite armazenará mensagens até exceder a capacidade de armazenamento.

É possível criar tópicos do Lite com o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub Lite.

Console

  1. No Console do Cloud, acesse a página Tópicos do Lite.

    Acessar a página de tópicos do Lite

  2. Clique em Criar tópico Lite.

  3. Selecione uma região e uma zona na região.

  4. Na seção Nome, insira um ID de tópico Lite. O nome do tópico do Lite inclui o ID do tópico do Lite, a zona e o número do projeto.

  5. Na seção Capacidade, insira o Número de partições a serem provisionadas para a partição.

  6. Na seção Armazenamento de mensagens, insira o Armazenamento por partição.

  7. Opcional: na seção Retenção de mensagens, selecione Descartar mensagens após a duração especificada, mesmo que o armazenamento esteja disponível e insira um período de armazenamento.

  8. Clique em Criar

gcloud

Para criar um tópico do Lite, use o comando gcloud pubsub lite-topics create:

gcloud pubsub lite-topics create TOPIC_ID \
  --zone=ZONE \
  --partitions=NUMBER_OF_PARTITIONS \
  --per-partition-bytes=STORAGE_PER_PARTITION \
  [--message-retention-period=MESSAGE_RETENTION_PERIOD]

Substitua:

  • TOPIC_ID: o ID do tópico do Lite

  • ZONE: o nome de uma zona compatível com o Pub/Sub Lite

  • NUMBER_OF_PARTITIONS: um número inteiro para o número de partições no tópico Lite

  • STORAGE_PER_PARTITION: a quantidade de armazenamento em cada partição, como 30GiB.

  • MESSAGE_RETENTION_PERIOD: a quantidade de tempo em que o tópico do Lite armazena mensagens, como 1d ou 2w

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

Created [TOPIC_ID].

Protocolo

Para criar um tópico Lite, envie uma solicitação POST como esta:

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

Substitua:

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

{
  "partitionConfig": {
       "count": NUMBER_OF_PARTITIONS,
       "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
       }
  },
  "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
  },
}

Substitua:

  • NUMBER_OF_PARTITIONS: um número inteiro para o número de partições no tópico Lite

  • STORAGE_PER_PARTITION: a quantidade de armazenamento em cada partição, como 30GiB.

  • PUBLISHING_CAPACITY: um número inteiro para a capacidade de publicação de cada partição.

  • SUBSCRIBING_CAPACITY: um número inteiro para a capacidade de assinatura de cada partição.

  • MESSAGE_RETENTION_PERIOD: a quantidade de tempo em que o tópico do Lite armazena mensagens, como 1d ou 2w

Se a solicitação for bem-sucedida, a resposta será o tópico do Lite no formato JSON:

{
  "name": projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID,
  "partitionConfig": {
       "count": NUMBER_OF_PARTITIONS,
       "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
       }
  },
  "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
  },
}

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 createTopic(w io.Writer, projectID, region, zone, topicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1" // see https://cloud.google.com/pubsub/lite/docs/locations
	// zone := "us-central1-a"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	const gib = 1 << 30
	// For ranges of fields in TopicConfig, see https://pkg.go.dev/cloud.google.com/go/pubsublite/#TopicConfig
	topic, err := client.CreateTopic(ctx, pubsublite.TopicConfig{
		Name:                       fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, zone, topicID),
		PartitionCount:             2, // Must be >= 1 and cannot decrease after creation.
		PublishCapacityMiBPerSec:   4,
		SubscribeCapacityMiBPerSec: 8,
		PerPartitionBytes:          30 * gib,
		RetentionDuration:          pubsublite.InfiniteRetention,
	})
	if err != nil {
		return fmt.Errorf("client.CreateTopic got err: %v", err)
	}
	fmt.Fprintf(w, "Created topic: %s\n", topic.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.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.Topic;
import com.google.cloud.pubsublite.proto.Topic.PartitionConfig;
import com.google.cloud.pubsublite.proto.Topic.RetentionConfig;
import com.google.protobuf.util.Durations;

public class CreateTopicExample {

  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";
    long projectNumber = Long.parseLong("123456789");
    int partitions = 1;

    createTopicExample(cloudRegion, zoneId, projectNumber, topicId, partitions);
  }

  public static void createTopicExample(
      String cloudRegion, char zoneId, long projectNumber, String topicId, int partitions)
      throws Exception {

    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .setName(TopicName.of(topicId))
            .build();

    Topic topic =
        Topic.newBuilder()
            .setPartitionConfig(
                PartitionConfig.newBuilder()
                    // Set throughput capacity per partition in MiB/s.
                    .setCapacity(
                        PartitionConfig.Capacity.newBuilder()
                            // Must be 4-16 MiB/s.
                            .setPublishMibPerSec(4)
                            // Must be 4-32 MiB/s.
                            .setSubscribeMibPerSec(8)
                            .build())
                    .setCount(partitions))
            .setRetentionConfig(
                RetentionConfig.newBuilder()
                    // How long messages are retained.
                    .setPeriod(Durations.fromDays(1))
                    // Set storage per partition to 30 GiB. This must be 30 GiB-10 TiB.
                    // If the number of bytes stored in any of the topic's partitions grows
                    // beyond this value, older messages will be dropped to make room for
                    // newer ones, regardless of the value of `period`.
                    .setPerPartitionBytes(30 * 1024 * 1024 * 1024L))
            .setName(topicPath.toString())
            .build();

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Topic response = adminClient.createTopic(topic).get();
      System.out.println(response.getAllFields() + "created successfully.");
    }
  }
}

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.pubsublite import AdminClient, Topic
from google.cloud.pubsublite.types import CloudRegion, CloudZone, TopicPath
from google.protobuf.duration_pb2 import Duration

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"
# topic_id = "your-topic-id"
# num_partitions = 1

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
topic_path = TopicPath(project_number, location, topic_id)
topic = Topic(
    name=str(topic_path),
    partition_config=Topic.PartitionConfig(
        # A topic must have at least one partition.
        count=num_partitions,
        # Set throughput capacity per partition in MiB/s.
        capacity=Topic.PartitionConfig.Capacity(
            # Set publish throughput capacity per partition to 4 MiB/s. Must be >= 4 and <= 16.
            publish_mib_per_sec=4,
            # Set subscribe throughput capacity per partition to 4 MiB/s. Must be >= 4 and <= 32.
            subscribe_mib_per_sec=8,
        ),
    ),
    retention_config=Topic.RetentionConfig(
        # Set storage per partition to 30 GiB. This must be in the range 30 GiB-10TiB.
        # If the number of byptes stored in any of the topic's partitions grows beyond
        # this value, older messages will be dropped to make room for newer ones,
        # regardless of the value of `period`.
        per_partition_bytes=30 * 1024 * 1024 * 1024,
        # Allow messages to be retained for 7 days.
        period=Duration(seconds=60 * 60 * 24 * 7),
    ),
)

client = AdminClient(cloud_region)
try:
    response = client.create_topic(topic)
    print(f"{response.name} created successfully.")
except AlreadyExists:
    print(f"{topic_path} already exists.")

Para uma lista das zonas disponíveis, consulte Locais do Pub/Sub Lite.

Depois de criar o tópico do Lite, é possível escalonar a capacidade de armazenamento e a capacidade de armazenamento por partição. Também é possível aumentar, mas não diminuir o número de partições. Para detalhes, consulte Capacidade de escalonamento.

Capacidade de provisionamento

Os tópicos do Lite consistem em partições. Uma partição é compatível com a seguinte capacidade:

  • Capacidade de publicação: a taxa total máxima em que é possível publicar mensagens.
  • Capacidade de assinatura: a taxa total máxima em que as mensagens são encaminhadas para assinaturas do Lite.
  • Armazenamento: o tamanho total máximo das mensagens na partição.

Se você exceder a capacidade de armazenamento, o serviço Pub/Sub Lite nunca falhará. Em vez disso, ela remove a mensagem mais antiga da partição, independentemente do período de armazenamento da mensagem mais antiga. O serviço Pub/Sub Lite remove mensagens da melhor maneira possível.

Para informações sobre como a capacidade está relacionada aos preços, consulte Preços do Pub/Sub Lite

Como atualizar tópicos do Lite

É possível atualizar o período de retenção de mensagens e dimensionar a capacidade de um tópico Lite. Não é possível atualizar a zona de um tópico. Para escalonar a capacidade de um tópico Lite, consulte Capacidade de escalonamento.

É possível atualizar um tópico do Lite com o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub Lite.

Console

  1. No Console do Cloud, acesse a página Tópicos do Lite.

    Acessar a página de tópicos do Lite

  2. Clique no ID do tópico do Lite.

  3. Clique em Editar.

  4. Digite o Número de partições. Isso pode ser aumentado, mas não reduzido.

  5. Insira o Armazenamento por partição e o Período de armazenamento.

  6. Selecione uma Capacidade de publicação.

  7. Selecione uma Capacidade de assinatura.

  8. Insira o Armazenamento por partição.

gcloud

Para atualizar um tópico do Lite, use o comando gcloud pubsub lite-topics update:

gcloud pubsub lite-topics update TOPIC_ID \
  --zone=ZONE \
  --partitions=NUMBER_OF_PARTITIONS \
  --per-partition-publish-mib=PUBLISHING_CAPACITY \
  --per-partition-subscribe-mib=SUBSCRIBING_CAPACITY \
  --per-partition-bytes=STORAGE_PER_PARTITION \
  --message-retention-period=MESSAGE_RETENTION_PERIOD

Substitua:

  • TOPIC_ID: o ID do tópico do Lite

  • ZONE: o nome da zona em que o tópico do Lite está.

  • NUMBER_OF_PARTITIONS: o número de partições a serem configuradas para o tópico do Lite.

  • PUBLISHING_CAPACITY: um número inteiro para a capacidade de publicação de cada partição.

  • SUBSCRIBING_CAPACITY: um número inteiro para a capacidade de assinatura de cada partição.

  • STORAGE_PER_PARTITION: a quantidade de armazenamento em cada partição, como 30GiB.

  • MESSAGE_RETENTION_PERIOD: a quantidade de tempo em que o tópico do Lite armazena mensagens, como 1d ou 2w

Se a solicitação for bem-sucedida, a linha de comando exibirá o tópico Lite:

name: projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
partitionConfig:
  count: NUMBER_OF_PARTITIONS
  capacity:
    publishMibPerSec: PUBLISHING_CAPACITY
    subscribeMibPerSec: SUBSCRIBING_CAPACITY
retentionConfig:
  perPartitionBytes: STORAGE_PER_PARTITION
  period: MESSAGE_RETENTION_PERIOD

Protocolo

Para atualizar um tópico do Lite, envie uma solicitação PATCH como a seguinte:

PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID?updateMask=partitionConfig.capacity,retentionConfig.perPartitionBytes,retentionConfig.period,partitionConfig.count
Authorization: Bearer $(gcloud auth print-access-token)

Substitua:

  • REGION: a região da zona em que o tópico do Lite está

  • PROJECT_NUMBER: o número do projeto com o tópico Lite

  • ZONE: o nome da zona em que o tópico do Lite está.

  • TOPIC_ID: o ID do tópico do Lite

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

{
  "partitionConfig": {
      "count": NUMBER_OF_PARTITIONS,
      "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
      }
   },
   "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
   },
}

Substitua:

  • PUBLISHING_CAPACITY: um número inteiro para a capacidade de publicação de cada partição.

  • SUBSCRIBING_CAPACITY: um número inteiro para a capacidade de assinatura de cada partição.

  • STORAGE_PER_PARTITION: a quantidade de armazenamento em cada partição, como 30GiB.

  • MESSAGE_RETENTION_PERIOD: a quantidade de tempo em que o tópico do Lite armazena mensagens, como 1d ou 2w

  • NUMBER_OF_PARTITIONS: o número de partições a serem configuradas para o tópico do Lite.

Se a solicitação for bem-sucedida, a resposta será o tópico do Lite no formato JSON:

{
  "name": projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID,
  "partitionConfig": {
      "count": NUMBER_OF_PARTITIONS,
      "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
      }
   },
   "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
   },
}

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

	"cloud.google.com/go/pubsublite"
)

func updateTopic(w io.Writer, projectID, region, zone, topicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// zone := "us-central1-a"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	topicPath := fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, zone, topicID)
	// For ranges of fields in TopicConfigToUpdate, see https://pkg.go.dev/cloud.google.com/go/pubsublite/#TopicConfigToUpdate
	config := pubsublite.TopicConfigToUpdate{
		Name:                       topicPath,
		PartitionCount:             3, // Partition count cannot decrease.
		PublishCapacityMiBPerSec:   8,
		SubscribeCapacityMiBPerSec: 16,
		PerPartitionBytes:          60 * 1024 * 1024 * 1024,
		RetentionDuration:          24 * time.Hour,
	}
	updatedCfg, err := client.UpdateTopic(ctx, config)
	if err != nil {
		return fmt.Errorf("client.UpdateTopic got err: %v", err)
	}
	fmt.Fprintf(w, "Updated topic: %#v\n", *updatedCfg)
	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.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.Topic;
import com.google.cloud.pubsublite.proto.Topic.PartitionConfig;
import com.google.cloud.pubsublite.proto.Topic.RetentionConfig;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.Durations;
import java.util.Arrays;

public class UpdateTopicExample {

  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";
    long projectNumber = Long.parseLong("123456789");

    updateTopicExample(cloudRegion, zoneId, projectNumber, topicId);
  }

  public static void updateTopicExample(
      String cloudRegion, char zoneId, long projectNumber, String topicId) throws Exception {

    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .setName(TopicName.of(topicId))
            .build();

    Iterable<String> iterablePaths =
        Arrays.asList(
            "partition_config.scale",
            "retention_config.per_partition_bytes",
            "retention_config.period");

    FieldMask fieldMask = FieldMask.newBuilder().addAllPaths(iterablePaths).build();

    Topic topic =
        Topic.newBuilder()
            .setPartitionConfig(
                PartitionConfig.newBuilder()
                    // Set publishing throughput to 4 times the standard partition
                    // throughput of 4 MiB per sec. This must be in the range [1,4]. A
                    // topic with `scale` of 2 and count of 10 is charged for 20 partitions.
                    .setScale(4)
                    .build())
            .setRetentionConfig(
                RetentionConfig.newBuilder()
                    // Set storage per partition to 200 GiB. This must be 30 GiB-10 TiB.
                    // If the number of bytes stored in any of the topic's partitions grows
                    // beyond this value, older messages will be dropped to make room for
                    // newer ones, regardless of the value of `period`.
                    // Be careful when decreasing storage per partition as it may cause
                    // lost messages.
                    .setPerPartitionBytes(200 * 1024 * 1024 * 1024L)
                    .setPeriod(Durations.fromDays(7)))
            .setName(topicPath.toString())
            .build();

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Topic topicBeforeUpdate = adminClient.getTopic(topicPath).get();
      System.out.println("Before update: " + topicBeforeUpdate.getAllFields());

      Topic topicAfterUpdate = adminClient.updateTopic(topic, fieldMask).get();
      System.out.println("After update: " + topicAfterUpdate.getAllFields());
    }
  }
}

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 NotFound
from google.cloud.pubsublite import AdminClient, Topic
from google.cloud.pubsublite.types import CloudRegion, CloudZone, TopicPath
from google.protobuf.duration_pb2 import Duration
from google.protobuf.field_mask_pb2 import FieldMask

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"
# topic_id = "your-topic-id"

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
topic_path = TopicPath(project_number, location, topic_id)

# Defines which topic fields to update.
field_mask = FieldMask(
    paths=[
        "partition_config.scale",
        "retention_config.per_partition_bytes",
        "retention_config.period",
    ]
)

# Defines how to update the topic fields.
topic = Topic(
    name=str(topic_path),
    partition_config=Topic.PartitionConfig(
        # Set publishing throughput to 2x standard partition throughput of 4 MiB
        # per second. This must in the range [1,4]. A topic with `scale` of 2 and
        # `count` of 10 is charged for 20 partitions.
        scale=2,
    ),
    retention_config=Topic.RetentionConfig(
        # Set storage per partition to 100 GiB. This must be in the range 30 GiB-10TiB.
        # If the number of byptes stored in any of the topic's partitions grows beyond
        # this value, older messages will be dropped to make room for newer ones,
        # regardless of the value of `period`.
        # Be careful when decreasing storage per partition as it may cuase lost messages.
        per_partition_bytes=100 * 1024 * 1024 * 1024,
        # Allow messages to be stored for 14 days.
        period=Duration(seconds=60 * 60 * 24 * 14),
    ),
)

client = AdminClient(cloud_region)
try:
    response = client.update_topic(topic, field_mask)
    print(f"{response.name} updated successfully.")
except NotFound:
    print(f"{topic_path} not found.")

Como escalonar a capacidade de capacidade

Você pode escalonar a capacidade de capacidade de um tópico verticalmente e horizontalmente. O escalonamento vertical envolve o ajuste da capacidade das partições de um tópico para cima ou para baixo. O serviço Pub/Sub Lite provisiona a mesma quantidade de capacidade para cada partição no tópico do Lite. Por exemplo, se você aumentar a capacidade de publicação para 10 MiB por segundo, cada uma das partições receberá 10 MiB por segundo de capacidade de publicação.

Também é possível aumentar horizontalmente a capacidade de um tópico do Lite aumentando o número de partições. Não é possível diminuir o número de partições em um tópico.

Quando você altera o número de partições, a ordem relativa das mensagens não é preservada. A atualização do número de partições em um tópico altera a função de hash usada para mapear da chave de ordenação para partição. As mensagens com a mesma chave publicadas após a atualização da contagem de partições provavelmente serão mapeadas para uma partição diferente daquelas publicadas antes da atualização. Além disso, o redimensionamento de tópico levará algum tempo para ser propagado a todos os editores. Por isso, haverá um breve período em que alguns editores usarão a nova função de hash e outros ainda estarão usando a antiga.

Como escalonar a capacidade de armazenamento

Também é possível aumentar ou diminuir a quantidade de armazenamento em um tópico do Lite. O tópico Lite fornece a mesma quantidade de armazenamento para cada partição. Se você aumentar o armazenamento para 60 GiB, cada uma delas terá 60 GiB de armazenamento.

Se você diminuir a quantidade de armazenamento em um tópico Lite, o serviço Pub/Sub Lite removerá primeiro as mensagens mais antigas.

Para informações sobre como a capacidade está relacionada aos preços, consulte Preços do Pub/Sub Lite

Como ver detalhes do tópico do Lite

Para mais detalhes sobre um tópico do Lite, use o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub Lite.

Console

  1. No Console do Cloud, acesse a página Tópicos do Lite.

    Acessar a página de tópicos do Lite

  2. Clique no ID do tópico do Lite.

gcloud

Para ver detalhes sobre um tópico Lite, use o comando gcloud pubsub lite-topics describe:

gcloud pubsub lite-topics describe TOPIC_ID \
--zone=ZONE

Substitua:

  • TOPIC_ID: o ID do tópico do Lite

  • ZONE: o nome da zona em que o tópico do Lite está.

Se a solicitação for bem-sucedida, a linha de comando exibirá o tópico Lite:

name: projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
partitionConfig:
  count: NUMBER_OF_PARTITIONS
  capacity:
    publishMibPerSec: PUBLISHING_CAPACITY
    subscribeMibPerSec: SUBSCRIBING_CAPACITY
retentionConfig:
  perPartitionBytes: STORAGE_PER_PARTITION
  period: MESSAGE_RETENTION_PERIOD

Protocolo

Para ver detalhes sobre um tópico do Lite, envie uma solicitação GET como a seguinte:

GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
Authorization: Bearer $(gcloud auth print-access-token)

Substitua:

  • REGION: a região da zona em que o tópico do Lite está

  • PROJECT_NUMBER: o número do projeto com o tópico Lite

  • ZONE: o nome da zona em que o tópico do Lite está.

  • TOPIC_ID: o ID do tópico do Lite

Se a solicitação for bem-sucedida, a resposta será o tópico do Lite no formato JSON:

{
  "name": projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID,
  "partitionConfig": {
      "count": NUMBER_OF_PARTITIONS,
      "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
      }
   },
   "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
   },
}

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 getTopic(w io.Writer, projectID, region, zone, topicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// zone := "us-central1-a"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	topicName := fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, zone, topicID)
	topic, err := client.Topic(ctx, topicName)
	if err != nil {
		return fmt.Errorf("client.Topic got err: %v", err)
	}
	fmt.Fprintf(w, "Got topic: %#v\n", *topic)
	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.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.Topic;

public class GetTopicExample {

  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';
    // Choose an existing topic.
    String topicId = "your-topic-id";
    long projectNumber = Long.parseLong("123456789");

    getTopicExample(cloudRegion, zoneId, projectNumber, topicId);
  }

  public static void getTopicExample(
      String cloudRegion, char zoneId, long projectNumber, String topicId) throws Exception {
    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .setName(TopicName.of(topicId))
            .build();

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Topic topic = adminClient.getTopic(topicPath).get();
      long numPartitions = adminClient.getTopicPartitionCount(topicPath).get();
      System.out.println(topic.getAllFields() + "\nhas " + numPartitions + " partition(s).");
    }
  }
}

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 NotFound
from google.cloud.pubsublite import AdminClient
from google.cloud.pubsublite.types import CloudRegion, CloudZone, TopicPath

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"
# topic_id = "your-topic-id"

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
topic_path = TopicPath(project_number, location, topic_id)

client = AdminClient(cloud_region)
try:
    response = client.get_topic(topic_path)
    num_partitions = client.get_topic_partition_count(topic_path)
    print(f"{response.name} has {num_partitions} partition(s).")
except NotFound:
    print(f"{topic_path} not found.")

Como listar tópicos do Lite

É possível listar tópicos do Lite em um projeto usando o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub Lite.

Console

Para visualizar uma lista dos tópicos do Lite em um projeto, consulte a página Tópicos do Lite.

gcloud

Para listar os tópicos do Lite em um projeto, use o comando gcloud pubsub lite-topics list:

gcloud pubsub lite-topics list \
  --zone=ZONE

Substitua ZONE pelo nome da zona em que está o tópico do Lite.

Se a solicitação for bem-sucedida, a linha de comando exibirá os tópicos do Lite:

---
name: projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
partitionConfig:
  count: NUMBER_OF_PARTITIONS
  capacity:
    publishMibPerSec: PUBLISHING_CAPACITY
    subscribeMibPerSec: SUBSCRIBING_CAPACITY
retentionConfig:
  perPartitionBytes: STORAGE_PER_PARTITION
  period: MESSAGE_RETENTION_PERIOND
---
name: projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
partitionConfig:
  count: NUMBER_OF_PARTITIONS
  capacity:
    publishMibPerSec: PUBLISHING_CAPACITY
    subscribeMibPerSec: SUBSCRIBING_CAPACITY
retentionConfig:
  perPartitionBytes: STORAGE_PER_PARTITION
  period: MESSAGE_RETENTION_PERIOND

Protocolo

Para listar os tópicos do Lite em um projeto, envie uma solicitação GET como esta:

GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/topics
Authorization: Bearer $(gcloud auth print-access-token)

Substitua:

  • REGION: a região da zona em que o tópico do Lite está

  • PROJECT_NUMBER: o número do projeto com o tópico Lite

Se a solicitação for bem-sucedida, a resposta será uma lista de tópicos Lite no formato JSON:

{
  "topics": [
      {
          "name": "projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID",
      },
      {
          "name": "projects/PROJECT_NUMBER/locations/ZONE/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"
	"google.golang.org/api/iterator"
)

func listTopics(w io.Writer, projectID, region, zone string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// zone := "us-central1-a"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	parent := fmt.Sprintf("projects/%s/locations/%s", projectID, zone)
	topicIter := client.Topics(ctx, parent)
	for {
		topic, err := topicIter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("topicIter.Next got err: %v", err)
		}
		fmt.Fprintf(w, "Got topic: %#v\n", topic)
	}
	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.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.LocationPath;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.proto.Topic;
import java.util.List;

public class ListTopicsExample {

  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';
    long projectNumber = Long.parseLong("123456789");

    listTopicsExample(cloudRegion, zoneId, projectNumber);
  }

  public static void listTopicsExample(String cloudRegion, char zoneId, long projectNumber)
      throws Exception {

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    LocationPath locationPath =
        LocationPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      List<Topic> topics = adminClient.listTopics(locationPath).get();
      for (Topic topic : topics) {
        System.out.println(topic.getAllFields());
      }
      System.out.println(topics.size() + " topic(s) listed.");
    }
  }
}

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.cloud.pubsublite import AdminClient
from google.cloud.pubsublite.types import CloudRegion, CloudZone, LocationPath

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
location_path = LocationPath(project_number, location)

client = AdminClient(cloud_region)
response = client.list_topics(location_path)

for topic in response:
    print(topic)

print(f"{len(response)} topic(s) listed in your project and location.")

Como excluir tópicos do Lite

É possível excluir tópicos do Lite com o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub Lite.

Console

  1. No Console do Cloud, acesse a página Tópicos do Lite.

    Acessar a página de tópicos do Lite

  2. Clique no ID do tópico do Lite.

  3. Na página Detalhes do tópico do Lite, clique em Excluir.

  4. No campo exibido, digite delete para confirmar que você quer excluir o tópico do Lite.

  5. Clique em Delete.

gcloud

Para excluir um tópico do Lite, use o comando gcloud pubsub lite-topics delete:

  1. Execute o comando delete:

    gcloud pubsub lite-topics delete TOPIC_ID \
     --zone=ZONE
    

    Substitua:

    • TOPIC_ID: o ID do tópico do Lite

    • ZONE: o nome da zona em que o tópico do Lite está.

  2. Para confirmar, digite Y.

Se a solicitação for bem-sucedida, a resposta será:

Deleted topic [TOPIC_ID].

Protocolo

Para excluir um tópico do Lite, envie uma solicitação DELETE como a seguinte:

DELETE https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
Authorization: Bearer $(gcloud auth print-access-token)

Substitua:

  • REGION: a região da zona em que o tópico do Lite está

  • PROJECT_NUMBER: o número do projeto com o tópico Lite

  • ZONE: o nome da zona em que o tópico do Lite está.

  • TOPIC_ID: o ID do tópico do Lite

Se a solicitação for bem-sucedida, a resposta será um objeto JSON vazio.

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 deleteTopic(w io.Writer, projectID, region, zone, topicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// zone := "us-central1-a"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	err = client.DeleteTopic(ctx, fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, zone, topicID))
	if err != nil {
		return fmt.Errorf("client.DeleteTopic got err: %v", err)
	}
	fmt.Fprint(w, "Deleted topic\n")
	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.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;

public class DeleteTopicExample {

  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';
    // Choose an existing topic.
    String topicId = "your-topic-id";
    long projectNumber = Long.parseLong("123456789");

    deleteTopicExample(cloudRegion, zoneId, projectNumber, topicId);
  }

  public static void deleteTopicExample(
      String cloudRegion, char zoneId, long projectNumber, String topicId) throws Exception {
    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .setName(TopicName.of(topicId))
            .build();

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      adminClient.deleteTopic(topicPath).get();
      System.out.println(topicPath.toString() + " deleted successfully.");
    }
  }

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 NotFound
from google.cloud.pubsublite import AdminClient
from google.cloud.pubsublite.types import CloudRegion, CloudZone, TopicPath

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"
# topic_id = "your-topic-id"

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
topic_path = TopicPath(project_number, location, topic_id)

client = AdminClient(cloud_region)
try:
    client.delete_topic(topic_path)
    print(f"{topic_path} deleted successfully.")
except NotFound:
    print(f"{topic_path} not found.")

Se você excluir um tópico Lite, não será possível publicar mensagens nele. As assinaturas do Lite para o tópico do Lite ainda existem, mas não é possível receber mensagens das assinaturas do Lite.