Este documento mostra como associar esquemas a tópicos do Pub/Sub.
Antes de começar
- Compreenda como funcionam os esquemas do Pub/Sub.
- Crie um esquema.
Funções e autorizações necessárias
Para receber as autorizações de que precisa para associar e gerir esquemas,
peça ao seu administrador que lhe conceda a função IAM de
editor do Pub/Sub (roles/pubsub.editor
)
no seu projeto.
Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.
Esta função predefinida contém as autorizações necessárias para associar e gerir esquemas. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:
Autorizações necessárias
São necessárias as seguintes autorizações para associar e gerir esquemas:
-
Crie um esquema:
pubsub.schemas.create
-
Anexe o esquema ao tópico:
pubsub.schemas.attach
-
Confirme uma revisão do esquema:
pubsub.schemas.commit
-
Elimine um esquema ou uma revisão de esquema:
pubsub.schemas.delete
-
Obtenha um esquema ou revisões de esquemas:
pubsub.schemas.get
-
Esquemas de listas:
pubsub.schemas.list
-
Revisões do esquema da lista:
pubsub.schemas.listRevisions
-
Reverter um esquema:
pubsub.schemas.rollback
-
Valide uma mensagem:
pubsub.schemas.validate
-
Obtenha a Política IAM para um esquema:
pubsub.schemas.getIamPolicy
-
Configure a Política IAM para um esquema:
pubsub.schemas.setIamPolicy
Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.
Pode conceder funções e autorizações a responsáveis, como utilizadores, grupos, domínios ou contas de serviço. Pode criar um esquema num projeto e anexá-lo a um tópico localizado num projeto diferente. Certifique-se de que tem as autorizações necessárias para cada projeto.
Diretrizes para associar um esquema a um tópico
Pode associar um esquema a um tópico quando cria ou edita um tópico. Seguem-se as diretrizes para associar um esquema a um tópico:
Pode associar um esquema a um ou mais tópicos.
Depois de um esquema ser associado a um tópico, todas as mensagens que o tópico recebe dos publicadores têm de seguir esse esquema.
Quando associa um esquema a um tópico, também tem de especificar a codificação das mensagens a publicar como
BINARY
ouJSON
. Se usar JSON com um esquema Avro, preste muita atenção às regras de codificação para uniões.Se um esquema associado a um tópico tiver revisões, as mensagens têm de corresponder à codificação e ser validadas em função de uma revisão dentro do intervalo disponível. Se não forem validados, a publicação da mensagem falha.
As revisões são tentadas por ordem cronológica inversa com base na hora de criação. Para criar uma revisão do esquema, consulte o artigo Confirme uma revisão do esquema.
Lógica de validação para um esquema de mensagens
Quando associa um esquema a um tópico e se o esquema tiver revisões, pode especificar um intervalo de revisões a usar. Se não especificar um intervalo, é usado o intervalo completo para a validação.
Se não especificar uma revisão como Primeira revisão permitida, a revisão existente mais antiga do esquema é usada para validação. Se não especificar uma revisão como Última revisão permitida, é usada a revisão existente mais recente para o esquema.
Vejamos o exemplo do esquema S
associado ao tópico T
.
O esquema S
tem os IDs de revisão A
,B
, C
e D
criados por ordem,
em que A
é a primeira ou a revisão mais antiga. Nenhum dos esquemas é idêntico
entre si ou reversões de um esquema existente.
Se definir apenas o campo First revision allowed como
B
, as mensagens em conformidade apenas com o esquemaA
são rejeitadas, enquanto as mensagens em conformidade com os esquemasB
,C
eD
são aceites.Se definir apenas o campo Última revisão permitida como
C
, as mensagens que estão em conformidade com os esquemasA
,B
eC
são aceites, e as mensagens que estão em conformidade apenas com o esquemaD
são rejeitadas.Se definir ambos os campos First revision allowed como
B
e Last revision allowed comoC
, as mensagens em conformidade com os esquemasB
eC
são aceites.Também pode definir a primeira e a última revisão com o mesmo ID de revisão. Neste caso, só são aceites mensagens em conformidade com essa revisão.
Crie e associe um esquema quando cria um tópico
Pode criar um tópico com um esquema através da Google Cloud consola, da CLI gcloud, da API Pub/Sub ou das bibliotecas cliente do Google Cloud.
Consola
Na Google Cloud consola, aceda à página Tópicos do Pub/Sub.
Clique em Criar tópico.
No campo ID do tópico, introduza um ID para o seu tópico.
Para dar um nome a um tópico, consulte as diretrizes.
Selecione a caixa Usar um esquema.
Mantenha as predefinições para os restantes campos.
Pode criar um esquema ou usar um esquema existente.
Se estiver a criar um esquema, siga estes passos: `
- Em Selecionar um esquema do Pub/Sub, selecione Criar um novo esquema.
A página Criar esquema é apresentada num separador secundário.
Siga os passos em Crie um esquema.
Regresse ao separador Criar tópico e clique em Atualizar.
Pesquise o seu esquema no campo Selecionar um esquema do Pub/Sub.
Selecione a codificação de mensagens como JSON ou Binário.
O esquema que acabou de criar tem um ID de revisão. Pode criar revisões do esquema adicionais, conforme explicado no artigo Confirme uma revisão do esquema.
Se estiver a associar um esquema já criado, siga estes passos:
Em Selecione um esquema do Pub/Sub, selecione um esquema existente.
Selecione a codificação de mensagens como JSON ou Binário.
Opcional: se o esquema selecionado tiver revisões, para Intervalo de revisões, use os menus pendentes para Primeira revisão permitida e Última revisão permitida.
Pode especificar ambos os campos, especificar apenas um ou manter as definições predefinidas com base nos seus requisitos.
Mantenha as predefinições para os restantes campos.
Clique em Criar para guardar o tópico e atribuí-lo ao esquema selecionado.
gcloud
Para criar um tópico atribuído a um esquema criado anteriormente, execute o comando
gcloud pubsub topics create
:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
Onde:
- TOPIC_ID é o ID do tópico que está a criar.
- ENCODING_TYPE é a codificação de mensagens validadas em função do esquema. Tem de definir este valor como
JSON
ouBINARY
. - SCHEMA_ID é o ID de um esquema existente.
- FIRST_REVISION_ID é o ID da revisão mais antiga para validar.
- LAST_REVISION_ID é o ID da revisão mais recente para validação.
Tanto --first-revision-id
como --last-revision-id
são opcionais.
Também pode atribuir um esquema de um Google Cloud projeto diferente:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --schema-project=SCHEMA_PROJECT \ --project=TOPIC_PROJECT
Onde:
- SCHEMA_PROJECT é o ID do projeto do Google Cloud projeto para o esquema.
- TOPIC_PROJECT é o ID do projeto do Google Cloud projeto para o tópico.
REST
Para criar um tópico, use o método projects.topics.create
:
Pedido:
O pedido tem de ser autenticado com um token de acesso no cabeçalho Authorization
. Para obter uma chave de acesso para as
Credenciais padrão da aplicação atuais: gcloud auth application-default print-access-token
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Corpo do pedido:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
Onde:
- PROJECT_ID é o ID do seu projeto.
- TOPIC_ID é o ID do seu tópico.
- SCHEMA_NAME é o nome do esquema com o qual as mensagens publicadas devem ser validadas. O formato é:
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE é a codificação de mensagens validadas de acordo com o esquema. Tem de ser definido como
JSON
ouBINARY
. - FIRST_REVISION_ID é o ID da revisão mais antiga para validar.
- LAST_REVISION_ID é o ID da revisão mais recente para validação.
Tanto firstRevisionId
como lastRevisionId
são opcionais.
Resposta:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
firstRevisionId
e lastRevisionId
são omitidos se não forem fornecidos na solicitação.
C++
Antes de experimentar este exemplo, siga as instruções de configuração do C++ no artigo Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ do Pub/Sub.
C#
Antes de experimentar este exemplo, siga as instruções de configuração do C# em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# do Pub/Sub.
Ir
O exemplo seguinte usa a versão principal da biblioteca de cliente Go Pub/Sub (v2). Se ainda estiver a usar a biblioteca v1, consulte o guia de migração para a v2. Para ver uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Go em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.
Java
Antes de experimentar este exemplo, siga as instruções de configuração do Java no artigo Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.
Node.js
Antes de experimentar este exemplo, siga as instruções de configuração do Node.js em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.
Node.js
Antes de experimentar este exemplo, siga as instruções de configuração do Node.js em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.
PHP
Antes de experimentar este exemplo, siga as instruções de configuração do PHP no artigo Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API PHP Pub/Sub.
Python
Antes de experimentar este exemplo, siga as instruções de configuração do Python em Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.
Ruby
O exemplo seguinte usa a biblioteca cliente Ruby Pub/Sub v3. Se ainda estiver a usar a biblioteca v2, consulte o guia de migração para a v3. Para ver uma lista de exemplos de código do Ruby v2, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Ruby em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Ruby Pub/Sub.
Edite um esquema associado a um tópico
Pode editar um tópico para anexar um esquema, remover um esquema ou atualizar o intervalo de revisões usado para validar mensagens. Em geral, se tiver alterações planeadas para o esquema em utilização, pode consolidar uma nova revisão e atualizar o intervalo de revisões usado para o tópico.
Pode editar um esquema associado a um tópico através da Google Cloud consola, da CLI gcloud, da API Pub/Sub ou das bibliotecas cliente do Google Cloud.
Consola
Na Google Cloud consola, aceda à página Tópicos do Pub/Sub.
Clique no ID do tópico de um tópico.
Na página de detalhes do tópico, clique em Editar.
Pode fazer as seguintes alterações ao esquema.
As alterações podem demorar alguns minutos a entrar em vigor.
Se quiser remover o esquema do tópico, na página Editar tópico, desmarque a caixa de verificação Usar um esquema.
Se quiser alterar o esquema, na secção Esquema, selecione o nome de um esquema.
Atualize os outros campos conforme necessário.
- Se quiser atualizar o intervalo de revisões, em Intervalo de revisões, use os menus pendentes para Primeira revisão permitida e Última revisão permitida.
Pode especificar ambos os campos, especificar apenas um ou manter as definições predefinidas com base nos seus requisitos.
Clique em Atualizar para guardar as alterações.
gcloud
gcloud pubsub topics update TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_NAME \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
Onde:
- TOPIC_ID é o ID do tópico que está a criar.
- ENCODING_TYPE é a codificação de mensagens validadas em função do esquema. Tem de definir este valor como
JSON
ouBINARY
. - SCHEMA_NAME é o nome de um esquema existente.
- FIRST_REVISION_ID é o ID da revisão mais antiga para validar.
- LAST_REVISION_ID é o ID da revisão mais recente para validação.
Tanto --first-revision-id
como --last-revision-id
são opcionais.
REST
Para atualizar um tópico, use o método projects.topics.patch
:
Pedido:
O pedido tem de ser autenticado com um token de acesso no cabeçalho Authorization
. Para obter uma chave de acesso para as
Credenciais padrão da aplicação atuais: gcloud auth application-default print-access-token
.
PATCH https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Corpo do pedido:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" "update_mask": } }
Onde:
- PROJECT_ID é o ID do seu projeto.
- TOPIC_ID é o ID do seu tópico.
- SCHEMA_NAME é o nome do esquema com o qual as mensagens publicadas devem ser validadas. O formato é:
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE é a codificação de mensagens validadas de acordo com o esquema. Tem de ser definido como
JSON
ouBINARY
. - FIRST_REVISION_ID é o ID da revisão mais antiga para validar.
- LAST_REVISION_ID é o ID da revisão mais recente para validação.
Tanto firstRevisionId
como lastRevisionId
são opcionais.
Resposta:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
O firstRevisionId
e o lastRevisionId
não estão definidos após a atualização.
C++
Antes de experimentar este exemplo, siga as instruções de configuração do C++ no artigo Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ do Pub/Sub.
Ir
O exemplo seguinte usa a versão principal da biblioteca de cliente Go Pub/Sub (v2). Se ainda estiver a usar a biblioteca v1, consulte o guia de migração para a v2. Para ver uma lista de exemplos de código da v1, consulte os exemplos de código descontinuados.
Antes de experimentar este exemplo, siga as instruções de configuração do Go em Início rápido: usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go do Pub/Sub.
Java
Antes de experimentar este exemplo, siga as instruções de configuração do Java no artigo Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Java do Pub/Sub.
Python
Antes de experimentar este exemplo, siga as instruções de configuração do Python em Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.
O que se segue?
- Confirme uma revisão do esquema
- Publique mensagens num tópico com um esquema
- Valide uma definição de esquema
- Valide uma mensagem para um esquema