Neste documento, explicamos como criar, atualizar, visualizar e excluir um tópico do Pub/Sub. Neste documento, também explicamos como nomear tópicos e assinaturas.
Propriedades de um tópico
Ao criar ou atualizar um tópico, é necessário especificar as propriedades dele.
Adicione uma assinatura padrão. Adiciona uma assinatura padrão ao tópico do Pub/Sub. É possível criar outra assinatura para o tópico depois que ele for criado. A assinatura padrão tem as seguintes propriedades:
- ID da assinatura de
-sub
- Tipo de entrega pull
- Duração da retenção de mensagens de sete dias
- Expiração após 31 dias de inatividade
- Prazo para a confirmação de 10 segundos
- Política de repetição imediata
- ID da assinatura de
Esquema. O esquema é um formato que o campo de dados de mensagem precisa seguir. Um esquema é um contrato entre o editor e o assinante que o Pub/Sub aplica. Os esquemas de tópicos ajudam a padronizar os tipos de mensagem e as permissões para que eles sejam consumidos por diferentes equipes na sua organização. O Pub/Sub cria uma autoridade central para tipos e permissões de mensagens. Para criar um tópico com esquema, consulte Criar e gerenciar esquemas.
Duração da retenção da mensagem. Especifica por quanto tempo o tópico do Pub/Sub retém mensagens após a publicação. Depois que a duração da retenção da mensagem terminar, o Pub/Sub poderá descartá-la, independentemente do estado de confirmação. As taxas de armazenamento de mensagens são cobradas pelo armazenamento de todas as mensagens publicadas no tópico.
- Padrão = não ativado
- Valor mínimo = 10 minutos
- Valor máximo = 31 dias
Usar uma chave de criptografia gerenciada pelo cliente (CMEK). Especifica se o tópico é criptografado com uma CMEK. O Pub/Sub criptografa mensagens com chaves gerenciadas pelo Google por padrão. Se você especificar essa opção, o Pub/Sub usará o padrão de criptografia de envelope com CMEK. Nessa abordagem, o Cloud KMS não criptografa as mensagens. Em vez disso, o Cloud KMS criptografa as chaves de criptografia de dados (DEKs, na sigla em inglês) criadas pelo Pub/Sub para cada tópico. O Pub/Sub criptografa as mensagens usando a DEK mais recente que foi gerada para o tópico. O Pub/Sub descriptografa as mensagens pouco antes de serem entregues aos assinantes. Para mais informações sobre como criar uma chave, consulte Configurar a criptografia de mensagens.
Diretrizes para nomear um tópico ou uma assinatura
Um nome de recurso do Pub/Sub identifica um recurso do Pub/Sub de maneira exclusiva, como uma assinatura ou um tópico, e precisa ter o seguinte formato:
projects/project-identifier/collection/ID
project-identifier.
precisa ser o ID do projeto, disponível no Console do Google Cloud. Por exemplo,projects/sampleproject/topics/sampletopic
.collection.
precisa sersubscriptions
,snapshots
outopics
.ID.
precisa estar em conformidade com as seguintes diretrizes:- Não começar com a string
goog
- Começar com uma letra
- conter entre 3 e 255 caracteres;
- Contém apenas os seguintes caracteres: letras
[A-Za-z]
, números[0-9]
, traços-
, sublinhados_
, pontos.
, til~
, sinais de adição+
e sinais de porcentagem%
Você pode usar os caracteres especiais na lista anterior em nomes de recursos sem codificação de URL. No entanto, é necessário garantir que qualquer outro caractere especial seja codificado ou decodificado corretamente quando usado em URLs. Por exemplo,
mi-tópico
é um nome relativo inválido. No entanto,mi-t%C3%B3pico
é válido. Esse formato é importante quando você faz chamadas REST.- Não começar com a string
Crie um tópico
Crie um tópico para publicar ou se inscrever nele.
Console
Para criar um tópico, siga estas etapas:
No Console do Google Cloud, acesse a página Tópicos do Pub/Sub.
Clique em Criar tópico.
No campo Código do tópico, insira um código para o tópico.
Mantenha a opção Adicionar uma assinatura padrão.
Não selecione as outras opções.
Clique em Criar tópico.
gcloud
Para criar um tópico, execute o
comando
gcloud pubsub topics create
:
gcloud pubsub topics create TOPIC_ID
REST
Para criar um tópico, use o
método
projects.topics.create
:
A solicitação precisa ser autenticada com um token de acesso no cabeçalho Authorization
. Para conseguir um token de acesso para o Application Default Credentials: gcloud auth application-default print-access-token
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Em que:
Resposta:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID" }
C++
Antes de testar esta amostra, siga as instruções de configuração do C++ no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
PHP
Antes de testar esta amostra, siga as instruções de configuração do PHP no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub para Python (em inglês).
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Restrições da política da organização
As políticas organizacionais podem restringir a criação de tópicos, por exemplo, uma política pode restringir o armazenamento de mensagens em uma região do Compute Engine. Para evitar erros de criação de tópicos, examine e atualize as políticas organizacionais, conforme necessário, antes de criar um tópico.
Se o projeto for recém-criado, aguarde alguns minutos para que a política da organização seja inicializada antes de criar um tópico.
Acesse as políticas da organização
Criar um tópico com um esquema
Ao criar um tópico, é recomendável atribuí-lo a um esquema.
Veja a seguir algumas diretrizes sobre o uso de esquemas:
- Não é possível adicionar esquemas a tópicos existentes.
- Só é possível especificar um esquema ao criar um tópico.
- Depois que um esquema for associado a um tópico, não será possível atualizá-lo nem remover a associação dele a ele.
- É possível aplicar o mesmo esquema a outros tópicos novos.
- Se você excluir um esquema, a publicação de todos os tópicos associados falhará.
Para saber mais sobre esquemas, consulte Criar e gerenciar esquemas.
Console
Para criar um tópico e atribuir um esquema a ele, siga estas etapas:
No Console do Google Cloud, acesse a página tópicos do Pub/Sub.
Clique em Criar tópico.
No campo Código do tópico, insira um código para o tópico.
Marque a caixa Usar um esquema. Não altere as outras opções.
Clique em Selecionar um esquema do Pub/Sub e escolha Criar um novo esquema. Se você quiser usar um esquema atual, pule para a etapa 7.
No campo Schema ID, insira um ID para seu esquema.
Em Tipo de esquema, selecione Avro ou o buffer de protocolo.
No campo Definição de esquema, insira a definição de Buffer de protocolo Avro para seu esquema.
Clique em Criar para salvar o esquema.
Na caixa de diálogo Criar um tópico, procure seu esquema no campo Selecionar um esquema do Pub/Sub.
Clique em Criar para salvar o tópico e atribuí-lo com o esquema selecionado.
gcloud
Para criar um tópico atribuído com um esquema criado anteriormente, execute o
comando
gcloud pubsub topics create
:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID
Em que:
- TOPIC_ID é o ID do tópico que você está criando.
- ENCODING_TYPE é a codificação das mensagens validadas no esquema. Esse valor precisa ser definido como
JSON
ouBINARY
. - SCHEMA_ID é o ID de um esquema atual.
Também é possível atribuir um esquema de outro projeto do Google Cloud:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --schema-project=SCHEMA_PROJECT \ --project=TOPIC_PROJECT
Em que:
- SCHEMA_PROJECT é o ID do projeto do Google Cloud para o esquema.
- TOPIC_PROJECT é o ID do projeto do Google Cloud para o tópico.
REST
Para criar um tópico, use o método
projects.topics.create
:
Solicitação:
A solicitação precisa ser autenticada com um token de acesso no cabeçalho Authorization
. Para conseguir um token de acesso para o Application Default Credentials: gcloud auth application-default print-access-token
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Corpo da solicitação:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" } }
Em que:
- PROJECT_ID é o ID do projeto;
- TOPIC_ID é o ID do tópico.
- SCHEMA_NAME é o nome do esquema em que as mensagens publicadas precisam ser validadas. O formato é:
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE é a codificação das mensagens validadas no esquema. Precisa ser definido como
JSON
ouBINARY
.
Resposta:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" } }
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ 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 C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# 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 C#.
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.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java 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 Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js 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 Node.js.
PHP
Antes de tentar esse exemplo, siga as instruções de configuração do PHP 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 PHP.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python 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 Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby 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 Ruby.
Excluir um tópico
Quando você exclui um tema, as assinaturas dele não são excluídas. O
backlog da mensagem da assinatura está disponível para assinantes. Depois que um tópico é excluído, as assinaturas dele ficam com o nome de tópico _deleted-topic_
. Se você tentar criar um tópico com o mesmo nome de um que acabou de ser excluído, ocorrerá um erro por um breve período.
Console
No Console do Google Cloud, acesse a página Tópicos do Pub/Sub.
Selecione um tópico e clique em
Mais ações.Clique em Excluir.
A janela Excluir tópico será exibida.
Digite
delete
e clique em Excluir.
gcloud
Para excluir um tópico, use o
comando
gcloud pubsub topics delete
:
gcloud pubsub topics delete TOPIC_ID
REST
Para excluir um tópico, use o
método
projects.topics.delete
:
Solicitação:
A solicitação precisa ser autenticada com um token de acesso no cabeçalho Authorization
. Para conseguir um token de acesso para o Application Default Credentials: gcloud auth application-default print-access-token
.
DELETE https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Em que:
Resposta:
Se a solicitação for bem-sucedida, a resposta será um objeto JSON vazio.
C++
Antes de testar esta amostra, siga as instruções de configuração do C++ no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
PHP
Antes de testar esta amostra, siga as instruções de configuração do PHP no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub para Python (em inglês).
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Listar um tópico
Console
No Console do Google Cloud, acesse a página Tópicos do Pub/Sub.
A página Tópicos lista todos os tópicos disponíveis.
gcloud
Para listar tópicos, use o comando gcloud pubsub topics list
:
gcloud pubsub topics list
REST
Para listar tópicos, use o
método
projects.topics.list
:
Solicitação:
A solicitação precisa ser autenticada com um token de acesso no cabeçalho Authorization
. Para conseguir um token de acesso para o Application Default Credentials: gcloud auth application-default print-access-token
.
GET https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics Authorization: Bearer ACCESS_TOKEN
Em que:
Resposta:
{ "topics": [ { "name": "projects/PROJECT_ID/topics/mytopic1", ... }, { "name": "projects/PROJECT_ID/topics/mytopic2", ... } ] }
C++
Antes de testar esta amostra, siga as instruções de configuração do C++ no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
PHP
Antes de testar esta amostra, siga as instruções de configuração do PHP no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub para Python (em inglês).
Ruby
Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
Por padrão, são retornados no máximo 100 resultados por consulta. Você pode mudar essa quantidade para até 1.000 usando o parâmetro de tamanho de página.
A seguir
Escolha o tipo de assinatura do tópico.
Crie uma assinatura para seu tópico.
Crie ou modifique um tópico com a CLI gcloud.
Criar ou modificar um tópico com APIs REST