Da definição aos bytes
O Protobuf, abreviação de Protocol Buffers, é um mecanismo de serialização que converte mensagens estruturadas em bytes e permite reconstruí-las depois. Você descreve os campos em um arquivo .proto e pode gerar código para ler e escrever as mensagens em linguagens compatíveis.
Cada campo recebe um número que o identifica no formato binário. A mensagem também carrega informações sobre como seus valores estão codificados, mas os nomes e os tipos declarados vêm da definição. Por isso, o receptor precisa conhecer a definição correspondente para interpretar o conteúdo como a aplicação espera. O arquivo .proto não acompanha automaticamente cada mensagem.
Um campo numerado no relatório
Esta definição didática declara uma mensagem com um campo de texto chamado titulo e atribui a ele o número 1:
syntax = "proto3";
message Relatorio { string titulo = 1;}Ao serializar o texto "Vendas de novembro" nesse campo, o Protobuf usa o número 1 para identificá-lo nos bytes. O decodificador usa a definição de Relatorio para associar o conteúdo ao título, embora o nome titulo não esteja escrito na mensagem binária.
Uma integração que apenas encaminha esse relatório deve preservar os bytes recebidos. Interpretar a resposta binária como texto e gravá-la novamente pode alterar o conteúdo. Caracteres ilegíveis no editor de texto são esperados nesse formato e não demonstram uma falha na transferência.
Compatibilidade entre versões
Uma versão nova precisa preservar o significado dos números já usados. Ao remover o campo titulo, você deve reservar o número 1 com uma declaração reserved na definição. Reutilizar esse número para outro campo pode causar uma leitura incorreta de mensagens antigas.
O formato permite algumas alterações compatíveis, como a adição de campos, sob as condições descritas no guia oficial. Isso não torna toda mudança compatível. Compare as definições dos dois serviços e teste a leitura entre as versões que precisam se comunicar.
Dúvidas frequentes
Perguntas frequentes sobre protobuf
- Uma mensagem Protobuf é um documento JSON?
- O formato binário e o JSON são representações diferentes. O Protobuf tem um mapeamento chamado ProtoJSON, mas a conversão exige um serializador apropriado. Ler os bytes como texto não produz JSON.
- A mensagem binária inclui os nomes dos campos?
- Os campos são identificados por números no formato binário. A definição da mensagem associa cada número ao nome e ao tipo declarado. Essa definição precisa estar disponível ao decodificador.
- Posso reutilizar o número de um campo removido?
- A documentação orienta reservar esse número com reserved. Reutilizá-lo pode fazer uma mensagem antiga ser interpretada com outro significado ou causar erro de leitura.
Para continuar
Recursos relacionados
Documentação
Protobuf: evolução das definições
Detalha quais alterações preservam a leitura binária e por que números de campos removidos precisam ser reservados.
Abrir recursoAplicação na formação
n8n Experts
Uma integração precisa reconhecer o formato da resposta para preservar e interpretar corretamente o conteúdo recebido.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.