Este documento mostra como associar esquemas aos tópicos do Pub/Sub.
Antes de começar
- Entenda como os esquemas do Pub/Sub funcionam.
- Crie um esquema.
Papéis e permissões necessárias
Para ter as permissões necessárias para associar e gerenciar esquemas,
peça ao administrador para conceder a você
Papel do IAM Editor do Pub/Sub (roles/pubsub.editor
) no projeto.
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esse papel predefinido contém as permissões necessárias para associar e gerenciar esquemas. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para associar e gerenciar esquemas:
-
Criar esquema:
pubsub.schemas.create
-
Anexar esquema ao tópico:
pubsub.schemas.attach
-
Confirme uma revisão de esquema:
pubsub.schemas.commit
-
Exclua um esquema ou uma revisão de esquema:
pubsub.schemas.delete
-
Receber um esquema ou revisões de esquema:
pubsub.schemas.get
-
Esquemas de lista:
pubsub.schemas.list
-
Listar revisões de esquema:
pubsub.schemas.listRevisions
-
Fazer o rollback de um esquema:
pubsub.schemas.rollback
-
Validar uma mensagem:
pubsub.schemas.validate
-
Encontre a política do IAM para um esquema:
pubsub.schemas.getIamPolicy
-
Configure a política do IAM para um esquema:
pubsub.schemas.setIamPolicy
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
É possível conceder papéis e permissões a principais, como usuários, grupos, domínios ou contas de serviço. É possível criar um esquema em um projeto anexar a um tópico localizado em um projeto diferente. Verifique se você tem as permissões necessárias para cada projeto.
Diretrizes para associar um esquema a um tópico
É possível associar um esquema a um tópico ao criar ou editar um tópico. Estas são as diretrizes para associar um esquema a um tópico:
É possível associar um esquema a um ou mais tópicos.
Depois que um esquema é associado a um tópico, todas as mensagens que ele recebe dos editores precisam seguir esse esquema.
Ao associar um esquema a um tópico, também é preciso especificar a codificação das mensagens a serem publicadas como
BINARY
ouJSON
. Se você usar JSON com uma 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 precisarão corresponder à codificação e validar em relação a uma revisão dentro do intervalo disponível. Se eles não forem validados, a mensagem não será publicada.
As revisões são tentadas em ordem cronológica inversa com base no horário de criação. Para criar uma revisão de esquema, consulte Fazer a confirmação de uma revisão de esquema.
Lógica de validação para um esquema de mensagens
Ao associar um esquema a um tópico e ele tiver revisões, é possível especificar um subconjunto de revisões para usar. Se você não especificar um intervalo, todo o intervalo será usado na validação.
Se você não especificar uma revisão como Primeira revisão permitida, a revisão mais antiga do esquema será usada para validação. Se você não especificar uma revisão como Última revisão permitida, a revisão mais recente do esquema será usada.
Vamos pegar o exemplo do esquema S
anexado ao tópico T
.
O esquema S
tem os IDs de revisão A
, B
, C
e D
criados em ordem,
em que A
é a primeira ou a revisão mais antiga. Nenhum dos esquemas é idêntico
aos outros, nem são rollbacks de um esquema existente.
Se você definir apenas o campo Primeira revisão permitida como
B
, as mensagens que se conformam apenas ao esquemaA
serão rejeitadas, enquanto as mensagens que se conformam aos esquemasB
,C
eD
serão aceitas.Se você definir apenas o campo Ultima revisão permitida como
C
, as mensagens que estiverem em conformidade com os esquemasA
,B
eC
serão aceitas, e as mensagens que estiverem em conformidade apenas com o esquemaD
serão rejeitadas.Se você definir os dois campos Primeira revisão permitida como
B
e Última revisão permitida comoC
, as mensagens que estiverem em conformidade com os esquemasB
eC
serão aceitas.Também é possível definir a primeira e a última revisão com o mesmo ID. Nesse caso, apenas as mensagens que estão em conformidade com essa revisão são aceitas.
Criar e associar um esquema ao criar um tópico
É possível criar um tópico com um esquema usando o console do Google Cloud, a CLI gcloud, a API Pub/Sub ou as bibliotecas de cliente do Cloud.
Console
No console do Google Cloud, acesse a página Tópicos do Pub/Sub.
Selecione Criar tópico.
No campo ID do tópico, insira um ID para o tópico.
Para nomear um tópico, consulte as diretrizes.
Marque a caixa Usar um esquema.
Mantenha as configurações padrão para os outros campos.
É possível criar um esquema ou usar um existente.
Se você estiver criando um esquema, siga estas etapas: `
- Em Selecionar um esquema do Pub/Sub, escolha Criar um novo esquema.
A página Criar esquema é exibida em uma guia secundária.
Siga as etapas em Criar um esquema.
Volte para a guia Criar tópico e clique em Atualizar.
Pesquise o esquema no campo Selecionar um esquema do Pub/Sub.
Selecione a codificação da mensagem como JSON ou Binário.
O esquema que você acabou de criar tem um ID de revisão. É possível criar revisões de esquema, conforme discutido em Fazer commit de uma revisão de esquema.
Se você estiver associando um esquema já criado, siga estas etapas:
Em Selecionar um esquema do Pub/Sub, escolha um esquema atual.
Selecione a codificação da mensagem como JSON ou Binário.
Opcional: se o esquema selecionado tiver revisões, em Intervalo de revisão, faça o seguinte: Use os menus suspensos Primeira revisão permitida e Última revisão permitida:
Especifique os dois campos, especifique apenas um ou mantenha o padrão com base nos seus requisitos.
Mantenha as configurações padrão para os outros campos.
Clique em Criar para salvar o tópico e atribuí-lo ao esquema selecionado.
gcloud
Para criar um tópico atribuído com um esquema criado anteriormente, execute o
gcloud pubsub topics create
comando:
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 \
Em que:
- TOPIC_ID é o ID do tópico que você está criando.
- ENCODING_TYPE é a codificação de mensagens validadas em relação ao
esquema. Esse valor precisa ser definido como
JSON
ouBINARY
. - SCHEMA_ID é o ID de um esquema existente.
- FIRST_REVISION_ID é o ID da revisão mais antiga para validação.
- LAST_REVISION_ID é o ID da revisão mais recente a ser validada.
Tanto --first-revision-id
quanto --last-revision-id
são opcionais.
Também é possível atribuir um esquema de um projeto diferente 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 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" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
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 de mensagens validadas em relação ao esquema. Ele precisa ser definido como
JSON
ouBINARY
. - FIRST_REVISION_ID é o ID da revisão mais antiga para validação.
- LAST_REVISION_ID é o ID da revisão mais recente a ser validada.
firstRevisionId
e 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" } }
Tanto firstRevisionId
quanto lastRevisionId
serão omitidos se não forem fornecidos
na solicitação.
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.
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.
Editar um esquema associado a um tópico
É possível editar um tópico para anexar ou remover um esquema ou atualizar o intervalo de revisões usado para validar mensagens. Em geral, se há mudanças planejadas para o esquema em uso, é possível confirmar uma nova revisão e atualizar o intervalo de revisões usadas para o tópico.
É possível editar um esquema associado a um tópico usando o console do Google Cloud, a CLI gcloud, a API Pub/Sub, ou as bibliotecas de cliente do Cloud.
Console
No console do Google Cloud, acesse a página Tópicos do Pub/Sub.
Clique no ID do tópico.
Na página de detalhes do tópico, clique em Editar.
É possível fazer as seguintes alterações no esquema.
Pode levar alguns minutos para que as mudanças entrem em vigor.
Se você quiser remover o esquema do tópico, na página Editar tópico, desmarque a caixa de seleção Usar um esquema.
Se você quiser alterar o esquema, na seção Esquema, selecione o nome de um esquema.
Atualize os outros campos conforme necessário.
- Se você quiser atualizar o intervalo de revisões, em Intervalo de revisões, use os menus suspensos para Primeira revisão permitida e Última revisão permitida.
Especifique os dois campos, especifique apenas um ou mantenha o padrão com base nos seus requisitos.
Clique em Atualizar para salvar as mudanças.
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 \
Em que:
- TOPIC_ID é o ID do tópico que você está criando.
- ENCODING_TYPE é a codificação de mensagens validadas em relação ao
esquema. Esse valor precisa ser definido como
JSON
ouBINARY
. - SCHEMA_NAME é o nome de um esquema existente.
- FIRST_REVISION_ID é o ID da revisão mais antiga a ser validada.
- LAST_REVISION_ID é o ID da revisão mais recente a ser validada.
--first-revision-id
e --last-revision-id
são opcionais.
REST
Para atualizar um tema, use projects.topics.patch
.
:
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
.
PATCH 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" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" "update_mask": } }
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 de mensagens validadas em relação ao esquema. Ele precisa ser definido como
JSON
ouBINARY
. - FIRST_REVISION_ID é o ID da revisão mais antiga para validação.
- LAST_REVISION_ID é o ID da revisão mais recente a ser validada.
firstRevisionId
e 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" } }
Tanto firstRevisionId
quanto lastRevisionId
, eles não são definidos após o
atualizar.
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.
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.
0A seguir
- Confirmar uma revisão de esquema
- Publicar mensagens em um tópico com um esquema
- Validar uma definição de esquema
- Validar uma mensagem para um esquema