As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Como trabalhar com cargas úteis binárias
Para tratar a carga da mensagem como dados binários brutos (em vez de um objeto JSON), você pode usar o operador \$1 para fazer referência a ela em uma cláusula SELECT.
**Topics**
+ [
## Exemplos de cargas úteis binárias
](#binary-payloads-examples)
+ [
## Decodificar as cargas úteis da mensagem protobuf
](#binary-payloads-protobuf)
## Exemplos de cargas úteis binárias
Ao usar \$1 para se referir à carga da mensagem como dados binários brutos, você pode adicionar dados à regra. Se você tiver uma carga vazia ou JSON, a carga resultante poderá ter dados adicionados usando a regra. Veja a seguir exemplos de cláusulas `SELECT` compatíveis.
+ Você pode usar as cláusulas `SELECT` a seguir com apenas um \$1 para cargas binárias.
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ Você também pode adicionar dados e usar as cláusulas `SELECT` a seguir.
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ Você também pode usar essas cláusulas `SELECT` com cargas binárias.
+ O seguinte se refere ao `device_type` na cláusula WHERE.
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ Também há suporte para:
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
As ações de regra a seguir não oferecem suporte a cargas binárias, portanto, você deve decodificá-las.
+ Algumas ações de regra não oferecem suporte a entrada de carga útil binária, como a [ação do Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule), então é necessário decodificar cargas úteis binárias. A ação de regra do Lambda poderá receber dados binários se estiverem codificados em base64 e em uma carga útil JSON. É possível fazer isso alterando a regra para a seguinte:
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ A instrução SQL não oferece suporte a string como entrada. Para converter uma entrada de string em JSON, é possível executar o seguinte comando.
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## Decodificar as cargas úteis da mensagem protobuf
[Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers) é um formato de dados de código aberto usado para serializar dados estruturados em um formato binário compacto. É usado para transmitir dados por redes ou armazená-los em arquivos. O Protobuf permite que você envie dados em pacotes pequenos e em uma taxa mais rápida do que outros formatos de mensagens. AWS IoT Core As regras oferecem suporte ao protobuf fornecendo a função SQL [decode (value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64), que permite decodificar cargas de mensagens codificadas por protobuf para o formato JSON e roteá-las para serviços downstream. Esta seção detalha o step-by-step processo para configurar a decodificação do protobuf em Regras. AWS IoT Core
**Topics**
+ [
### Pré-requisitos
](#binary-payloads-protobuf-prerequisites)
+ [
### Criar arquivos descritores
](#binary-payloads-protobuf-descriptor-steps)
+ [
### Upload de arquivos descritores em um bucket do S3
](#binary-payloads-protobuf-s3-steps)
+ [
### Configurar a decodificação do protobuf em Regras
](#binary-payloads-protobuf-steps)
+ [
### Limitações
](#binary-payloads-protobuf-limitations)
+ [
### Práticas recomendadas
](#binary-payloads-protobuf-bestpractices)
### Pré-requisitos
+ Uma compreensão básica dos [Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers)
+ Os [arquivos `.proto`](https://developers.google.com/protocol-buffers/docs/proto3) que definem os tipos de mensagens e dependências relacionadas
+ Instalação do [compilador Protobuf (protoc)](https://github.com/protocolbuffers/protobuf/releases) em seu sistema
### Criar arquivos descritores
Se já tiver arquivos de descrição, você poderá ignorar esta etapa. Um arquivo descritor (`.desc`) é uma versão compilada de um arquivo `.proto`, que é um arquivo de texto que define as estruturas de dados e os tipos de mensagens a serem usados em uma serialização do protobuf. Para gerar um arquivo descritor, você deve definir um arquivo `.proto` e usar o compilador [protoc](https://github.com/protocolbuffers/protobuf/releases) para compilá-lo.
1. Crie arquivos `.proto` que definam os tipos de mensagem. Um exemplo de arquivo `.proto` pode ser o seguinte:
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
Neste exemplo de arquivo `.proto`, você usa a sintaxe proto3 e define o tipo de mensagem `Person`. A definição da mensagem `Person` especifica três campos (nome, ID e e-mail). Para obter mais informações sobre formatos de mensagem de arquivo `.proto`, consulte o [Guia de idiomas (proto3)](https://developers.google.com/protocol-buffers/docs/proto3).
1. Use o compilador [protoc](https://github.com/protocolbuffers/protobuf/releases) para compilar os arquivos `.proto` e gerar um arquivo descritor. Um exemplo de comando para criar um arquivo descritor (`.desc`) pode ser o seguinte:
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
Esse exemplo de comando gera um arquivo descritor`.desc`, que o AWS IoT Core Rules pode usar para decodificar cargas de protobuf que estejam em conformidade com a estrutura de dados definida em. `.proto`
+ `--descriptor_set_out`
Especifica o nome do arquivo descritor (`.desc`) que deve ser gerado.
+ `--proto_path`
Especifica os locais de todos os arquivos `.proto` importados referenciados pelo arquivo que está sendo compilado. Você pode especificar o sinalizador várias vezes se tiver vários arquivos `.proto` importados com locais diferentes.
+ `--include_imports`
Especifica que todos os arquivos `.proto` importados também devem ser compilados e incluídos no arquivo `.desc` descritor.
+ `.proto`
Especifica o nome do arquivo `.proto` que você deseja compilar.
Para obter mais informações sobre a referência protoc, consulte [Referência de API](https://developers.google.com/protocol-buffers/docs/reference/overview).
### Upload de arquivos descritores em um bucket do S3
Depois de criar seus arquivos descritores`.desc`, faça o upload dos arquivos `.desc` descritores em um bucket do Amazon S3 usando AWS a API AWS , o SDK ou o. Console de gerenciamento da AWS
**Considerações importantes**
+ Certifique-se de carregar os arquivos do descritor em um bucket do Amazon S3 no Região da AWS mesmo local em que você pretende configurar Conta da AWS suas regras.
+ Certifique-se de conceder AWS IoT Core acesso para ler o `FileDescriptorSet` do S3. Se o seu bucket do S3 tiver a criptografia do lado do servidor (SSE) desativada ou se o bucket do S3 estiver criptografado usando chaves gerenciadas pelo Amazon S3 (SSE-S3), nenhuma configuração adicional de política será necessária. Isso pode ser feito com o exemplo de política de bucket:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ Se o bucket do S3 for criptografado usando uma AWS Key Management Service chave (SSE-KMS), certifique-se de conceder AWS IoT Core permissão para usar a chave ao acessar o bucket do S3. Você pode fazer isso adicionando esta declaração à sua política de chave:
```
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
### Configurar a decodificação do protobuf em Regras
Depois de fazer o upload dos arquivos do descritor no bucket do Amazon S3, configure uma [regra](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html) que possa decodificar o formato de carga útil da mensagem protobuf usando a função SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64). Uma assinatura de função detalhada e um exemplo podem ser encontrados na função SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) da *referência SQL de AWS IoT *.
Veja a seguir um exemplo de expressão SQL usando a função [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64):
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
Neste exemplo de expressão:
+ Você usa a função SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) para decodificar a carga útil da mensagem binária referenciada por `*`. Isso pode ser uma carga binária codificada por protobuf ou uma string JSON que representa uma carga útil protobuf codificada em base64.
+ A carga útil da mensagem fornecida é codificada usando o tipo de mensagem `Person` definido em `PROTO_FILENAME.proto`.
+ O bucket do Amazon S3 chamado `BUCKET NAME` contém o `FILENAME.desc` gerado de `PROTO_FILENAME.proto`.
Depois de concluir a configuração, publique uma mensagem no tópico AWS IoT Core no qual a Regra está inscrita.
### Limitações
AWS IoT Core As regras oferecem suporte ao protobuf com as seguintes limitações:
+ A decodificação de cargas de mensagens protobuf em [modelos de substituição](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) não é suportada.
+ Ao decodificar cargas de mensagens protobuf, você pode usar a [função decodificar SQL](iot-sql-functions.md#iot-sql-decode-base64) em uma única expressão SQL até duas vezes.
+ O tamanho máximo da carga útil de entrada é 128 KiB (1 KiB = 1024 bytes), o tamanho máximo da carga de saída é 128 KiB e o tamanho máximo de um objeto `FileDescriptorSet` armazenado em um bucket do Amazon S3 é 32 KiB.
+ Não há suporte para buckets do Amazon S3 criptografados com a criptografia SSE-C.
### Práticas recomendadas
Veja a seguir algumas práticas recomendadas e dicas de solução de problemas.
+ Carregue seus arquivos proto no bucket no Amazon S3.
É uma prática recomendada fazer backup de seus arquivos proto caso algo dê errado. Por exemplo, se você modificar incorretamente os arquivos proto sem backups ao executar protoc, isso pode causar problemas em sua pilha de produção. Há várias maneiras de fazer backup de arquivos em um bucket do Amazon S3. Por exemplo, você pode [usar o versionamento em buckets do S3](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html). Para obter mais informações sobre como fazer backup de arquivos em buckets do Amazon S3, consulte o *[Guia do desenvolvedor do Amazon S3](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*.
+ Configure o AWS IoT registro para visualizar as entradas do registro.
É uma boa prática configurar o AWS IoT registro para que você possa verificar AWS IoT os registros da sua conta CloudWatch. Quando a consulta SQL de uma regra chama uma função externa, o AWS IoT Core Rules gera uma entrada de registro com um `eventType` de`FunctionExecution`, que contém o campo de motivo que o ajudará a solucionar falhas. Os possíveis erros incluem um objeto do Amazon S3 não encontrado ou um descritor de arquivo protobuf inválido. Para obter mais informações sobre como configurar o registro de AWS IoT e ver as entradas de log, consulte [Configurar o registro de AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html) e [Entradas de log do mecanismo de regras](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec).
+ Atualize o `FileDescriptorSet` usando uma nova chave de objeto e atualize a chave de objeto em sua regra.
Você pode atualizar o `FileDescriptorSet` fazendo upload de um arquivo de descritor atualizado para o seu bucket do Amazon S3. Suas atualizações do `FileDescriptorSet` podem levar até 15 minutos para serem refletidas. Para evitar esse atraso, é uma prática recomendada carregar seu `FileDescriptorSet` atualizado usando uma nova chave de objeto e atualizar a chave de objeto em sua regra.