Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Bekerja dengan muatan biner
Untuk menangani payload pesan Anda sebagai data biner mentah (bukan objek JSON), Anda dapat menggunakan operator \$1 untuk merujuknya dalam klausa SELECT.
**Topics**
+ [
## Contoh muatan biner
](#binary-payloads-examples)
+ [
## Decoding muatan pesan protobuf
](#binary-payloads-protobuf)
## Contoh muatan biner
Saat Anda menggunakan\$1 untuk merujuk ke payload pesan sebagai data biner mentah, Anda dapat menambahkan data ke aturan. Jika Anda memiliki muatan kosong atau JSON, payload yang dihasilkan dapat memiliki data yang ditambahkan menggunakan aturan. Berikut ini menunjukkan contoh `SELECT` klausa yang didukung.
+ Anda dapat menggunakan `SELECT` klausa berikut hanya dengan\$1 untuk muatan biner.
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ Anda juga dapat menambahkan data dan menggunakan `SELECT` klausa berikut.
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ Anda juga dapat menggunakan `SELECT` klausa ini dengan muatan biner.
+ Berikut ini mengacu `device_type` pada klausa WHERE.
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ Berikut ini juga didukung.
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
Tindakan aturan berikut tidak mendukung muatan biner sehingga Anda harus mendekodekannya.
+ Beberapa tindakan aturan tidak mendukung input payload biner, seperti tindakan [Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule), jadi Anda harus memecahkan kode muatan biner. Tindakan aturan Lambda dapat menerima data biner, jika base64 dikodekan dan dalam muatan JSON. Anda dapat melakukan ini dengan mengubah aturan menjadi berikut.
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ Pernyataan SQL tidak mendukung string sebagai input. Untuk mengonversi input string ke JSON, Anda dapat menjalankan perintah berikut.
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## Decoding muatan pesan protobuf
[Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers) adalah format data sumber terbuka yang digunakan untuk membuat serial data terstruktur dalam bentuk biner yang ringkas. Ini digunakan untuk mentransmisikan data melalui jaringan atau menyimpannya dalam file. Protobuf memungkinkan Anda untuk mengirim data dalam ukuran paket kecil dan pada tingkat yang lebih cepat daripada format pesan lainnya. AWS IoT Core Aturan mendukung protobuf dengan menyediakan fungsi SQL [decode (value, decodingScheme),](iot-sql-functions.md#iot-sql-decode-base64) yang memungkinkan Anda untuk memecahkan kode muatan pesan yang disandikan protobuf ke format JSON dan merutekkannya ke layanan hilir. Bagian ini merinci step-by-step proses untuk mengkonfigurasi decoding protobuf dalam Aturan. AWS IoT Core
**Topics**
+ [
### Prasyarat
](#binary-payloads-protobuf-prerequisites)
+ [
### Buat file deskriptor
](#binary-payloads-protobuf-descriptor-steps)
+ [
### Unggah file deskriptor ke bucket S3
](#binary-payloads-protobuf-s3-steps)
+ [
### Konfigurasikan decoding protobuf dalam Aturan
](#binary-payloads-protobuf-steps)
+ [
### Batasan
](#binary-payloads-protobuf-limitations)
+ [
### Praktik terbaik
](#binary-payloads-protobuf-bestpractices)
### Prasyarat
+ Pemahaman dasar tentang [Protocol Buffer (protobuf](https://developers.google.com/protocol-buffers))
+ [`.proto`File](https://developers.google.com/protocol-buffers/docs/proto3) yang menentukan jenis pesan dan dependensi terkait
+ Menginstal [Protobuf Compiler (protoc](https://github.com/protocolbuffers/protobuf/releases)) pada sistem Anda
### Buat file deskriptor
Jika Anda sudah memiliki file deskriptor, Anda dapat melewati langkah ini. File deskriptor (`.desc`) adalah versi `.proto` file yang dikompilasi, yang merupakan file teks yang mendefinisikan struktur data dan tipe pesan yang akan digunakan dalam serialisasi protobuf. Untuk menghasilkan file deskriptor, Anda harus menentukan `.proto` file dan menggunakan kompiler [protoc](https://github.com/protocolbuffers/protobuf/releases) untuk mengompilasinya.
1. Buat `.proto` file yang menentukan jenis pesan. `.proto`File contoh dapat terlihat seperti berikut:
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
Dalam `.proto` file contoh ini, Anda menggunakan sintaks proto3 dan menentukan jenis pesan. `Person` Definisi `Person` pesan menentukan tiga bidang (nama, id, dan email). Untuk informasi selengkapnya tentang format pesan `.proto` file, lihat [Panduan Bahasa (proto3)](https://developers.google.com/protocol-buffers/docs/proto3).
1. Gunakan kompiler [protoc](https://github.com/protocolbuffers/protobuf/releases) untuk mengkompilasi `.proto` file dan menghasilkan file deskriptor. Contoh perintah untuk membuat file descriptor (`.desc`) dapat menjadi sebagai berikut:
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
Perintah contoh ini menghasilkan file deskriptor`.desc`, yang dapat digunakan AWS IoT Core Aturan untuk memecahkan kode muatan protobuf yang sesuai dengan struktur data yang ditentukan. `.proto`
+ `--descriptor_set_out`
Menentukan nama file deskriptor (`.desc`) yang harus dihasilkan.
+ `--proto_path`
Menentukan lokasi dari setiap `.proto` file impor yang direferensikan oleh file yang sedang dikompilasi. Anda dapat menentukan bendera beberapa kali jika Anda memiliki beberapa `.proto` file yang diimpor dengan lokasi yang berbeda.
+ `--include_imports`
Menentukan bahwa setiap `.proto` file yang diimpor juga harus dikompilasi dan disertakan dalam file `.desc` deskriptor.
+ `.proto`
Menentukan nama `.proto` file yang ingin Anda kompilasi.
Untuk informasi selengkapnya tentang referensi protokol, lihat [Referensi API](https://developers.google.com/protocol-buffers/docs/reference/overview).
### Unggah file deskriptor ke bucket S3
Setelah membuat file deskriptor`.desc`, unggah file deskriptor `.desc` ke bucket Amazon S3, menggunakan AWS API, SDK AWS , atau file. Konsol Manajemen AWS
**Pertimbangan penting**
+ Pastikan Anda mengunggah file deskriptor ke bucket Amazon S3 di Akun AWS tempat yang Wilayah AWS sama dengan tempat Anda ingin mengonfigurasi Aturan.
+ Pastikan Anda memberikan AWS IoT Core akses untuk membaca `FileDescriptorSet` dari S3. Jika bucket S3 Anda menonaktifkan enkripsi sisi server (SSE) atau bucket S3 Anda dienkripsi menggunakan kunci yang dikelola Amazon S3 (SSE-S3), konfigurasi kebijakan tambahan tidak diperlukan. Ini dapat dicapai dengan contoh kebijakan bucket:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ Jika bucket S3 Anda dienkripsi menggunakan AWS Key Management Service kunci (SSE-KMS), pastikan Anda memberikan AWS IoT Core izin untuk menggunakan kunci saat mengakses bucket S3 Anda. Anda dapat melakukannya dengan menambahkan pernyataan ini ke kebijakan utama Anda:
```
{
"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"
}
```
### Konfigurasikan decoding protobuf dalam Aturan
[Setelah mengunggah file deskriptor ke bucket Amazon S3, konfigurasikan Aturan yang dapat memecahkan kode format payload pesan protobuf menggunakan fungsi SQL decode (value, [decodingScheme](iot-sql-functions.md#iot-sql-decode-base64)).](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html) *Tanda tangan dan contoh fungsi terperinci dapat ditemukan di fungsi SQL [decode (value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) dari referensi SQL.AWS IoT *
Berikut ini adalah contoh ekspresi SQL menggunakan fungsi [decode (value, decodingScheme](iot-sql-functions.md#iot-sql-decode-base64)):
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
Dalam contoh ekspresi ini:
+ Anda menggunakan fungsi SQL [decode (value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) untuk memecahkan kode payload pesan biner yang direferensikan oleh. `*` Ini bisa berupa payload berkode protobuf biner atau string JSON yang mewakili payload protobuf yang dikodekan base64.
+ Payload pesan yang disediakan dikodekan menggunakan jenis `Person` pesan yang ditentukan. `PROTO_FILENAME.proto`
+ Bucket Amazon S3 bernama `BUCKET NAME` berisi yang `FILENAME.desc` dihasilkan dari. `PROTO_FILENAME.proto`
Setelah Anda menyelesaikan konfigurasi, publikasikan pesan ke AWS IoT Core topik yang menjadi aturan berlangganan.
### Batasan
AWS IoT Core Aturan mendukung protobuf dengan batasan berikut:
+ Decoding payload pesan protobuf dalam template [substitusi](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) tidak didukung.
+ Saat mendekode muatan pesan protobuf, Anda dapat menggunakan [fungsi SQL decode dalam satu ekspresi SQL hingga](iot-sql-functions.md#iot-sql-decode-base64) dua kali.
+ Ukuran muatan masuk maksimum adalah 128 KiB (1KiB = 1024 byte), ukuran muatan keluar maksimum adalah 128 KiB, dan ukuran maksimum untuk objek yang `FileDescriptorSet` disimpan dalam ember Amazon S3 adalah 32 KiB.
+ Bucket Amazon S3 yang dienkripsi dengan enkripsi SSE-C tidak didukung.
### Praktik terbaik
Berikut adalah beberapa praktik terbaik dan kiat pemecahan masalah.
+ Cadangkan file proto Anda di bucket Amazon S3.
Ini adalah praktik yang baik untuk membuat cadangan file proto Anda jika terjadi kesalahan. Misalnya, jika Anda salah memodifikasi file proto tanpa backup saat menjalankan protoc, ini dapat menyebabkan masalah pada tumpukan produksi Anda. Ada beberapa cara untuk mencadangkan file Anda di bucket Amazon S3. Misalnya, Anda dapat [menggunakan pembuatan versi di bucket S3](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html). Untuk informasi selengkapnya tentang cara mencadangkan file di bucket Amazon S3, lihat Panduan Pengembang *[Amazon](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)* S3.
+ Konfigurasikan AWS IoT logging untuk melihat entri log.
Ini adalah praktik yang baik untuk mengonfigurasi AWS IoT logging sehingga Anda dapat memeriksa AWS IoT log untuk akun Anda CloudWatch. Ketika kueri SQL aturan memanggil fungsi eksternal, AWS IoT Core Aturan menghasilkan entri log dengan `eventType` dari`FunctionExecution`, yang berisi bidang alasan yang akan membantu Anda memecahkan masalah kegagalan. Kemungkinan kesalahan termasuk objek Amazon S3 tidak ditemukan, atau deskriptor file protobuf yang tidak valid. Untuk informasi selengkapnya tentang cara mengonfigurasi AWS IoT logging dan melihat entri log, lihat [Mengkonfigurasi entri log mesin AWS IoT logging](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html) [dan Aturan](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec).
+ Perbarui `FileDescriptorSet` menggunakan kunci objek baru dan perbarui kunci objek di Aturan Anda.
Anda dapat memperbarui `FileDescriptorSet` dengan mengunggah file deskriptor yang diperbarui ke bucket Amazon S3 Anda. Pembaruan Anda `FileDescriptorSet` dapat memakan waktu hingga 15 menit untuk tercermin. Untuk menghindari penundaan ini, adalah praktik yang baik untuk mengunggah pembaruan Anda `FileDescriptorSet` menggunakan kunci objek baru, dan memperbarui kunci objek di Aturan Anda.