Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Bekerja dengan payload biner
Untuk menangani payload pesan Anda sebagai data biner mentah (bukan objek JSON), Anda dapat menggunakan operator * untuk merujuknya dalam klausa SELECT.
Dalam topik ini:
Contoh payload biner
Bila Anda menggunakan * untuk merujuk pada payload pesan sebagai data biner mentah, Anda dapat menambahkan data ke aturan. Jika Anda memiliki payload kosong atau JSON, payload yang dihasilkan dapat menambahkan data menggunakan aturan. Berikut ini menunjukkan contoh yang didukung SELECT klausa.
-
Anda dapat menggunakan yang berikut ini
SELECTklausa dengan hanya * untuk payload biner.SELECT * FROM 'topic/subtopic'SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
-
Anda juga dapat menambahkan data dan menggunakan yang berikut ini
SELECTklausa.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 ini
SELECTklausa dengan payload biner.Berikut ini mengacu pada
device_typedalam 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 payload biner sehingga Anda harus mendekodekannya.
-
Beberapa tindakan aturan tidak mendukung input payload biner, seperti Tindakan Lambda, jadi Anda harus memecahkan kode muatan biner. Tindakan aturan Lambda dapat menerima data biner, jika dikodekan base64 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'
Menguraikan muatan pesan protobuf
Buffer Protokol (protobuf)
Di bagian ini:
Prasyarat
-
Pemahaman dasar tentang Buffer Protokol (protobuf)
-
.protoberkasyang menentukan jenis pesan dan dependensi terkait -
Memasang Kompilator Protobuf (protoc)
pada sistem Anda
Buat file deskriptor
Jika Anda sudah memiliki file deskriptor, Anda dapat melewati langkah ini. File deskriptor (.desc) adalah versi kompilasi dari a .proto file, yang merupakan file teks yang mendefinisikan struktur data dan jenis pesan yang akan digunakan dalam serialisasi protobuf. Untuk menghasilkan file deskriptor, Anda harus menentukan .proto arsipkan dan gunakan protoc
-
Buat
.protofile yang menentukan jenis pesan. Sebuah contoh.protofile dapat terlihat seperti berikut:syntax = "proto3"; message Person { optional string name = 1; optional int32 id = 2; optional string email = 3; }Dalam contoh ini
.protofile, Anda menggunakan sintaks proto3 dan menentukan jenis pesanPerson.Persondefinisi pesan menentukan tiga bidang (nama, id, dan email). Untuk informasi lebih lanjut tentang.protoformat pesan file, lihat Panduan Bahasa (proto3). -
Gunakan protoc
kompiler untuk mengkompilasi .protofile dan menghasilkan file deskriptor. Contoh perintah untuk membuat deskriptor (.desc) file dapat berupa sebagai berikut:protoc --descriptor_set_out=<FILENAME>.desc \ --proto_path=<PATH_TO_IMPORTS_DIRECTORY> \ --include_imports \ <PROTO_FILENAME>.protoPerintah contoh ini menghasilkan file deskriptor
<FILENAME>.desc, yang AWS IoT Core Aturan dapat digunakan untuk memecahkan kode muatan protobuf yang sesuai dengan struktur data yang ditentukan di<PROTO_FILENAME>.proto.-
--descriptor_set_outMenentukan nama file deskriptor (
<FILENAME>.desc) yang harus dihasilkan. -
--proto_pathMenentukan lokasi yang diimpor
.protofile yang direferensikan oleh file yang sedang dikompilasi. Anda dapat menentukan bendera beberapa kali jika Anda memiliki beberapa yang diimpor.protofile dengan lokasi yang berbeda. -
--include_importsMenentukan bahwa setiap yang diimpor
.protofile juga harus dikompilasi dan dimasukkan dalam<FILENAME>.descfile deskriptor. -
<PROTO_FILENAME>.protoMenentukan nama
.protofile yang ingin Anda kompilasi.
Untuk informasi lebih lanjut tentang referensi protoc, lihat Referensi API
. -
Unggah file deskriptor ke bucket S3
Setelah Anda membuat file deskriptor Anda <FILENAME>.desc, unggah file deskriptor <FILENAME>.desc ke bucket Amazon S3, menggunakan AWS API, AWS SDK, atau Konsol Manajemen AWS.
Pertimbangan penting
-
Pastikan Anda mengunggah file deskriptor ke bucket Amazon S3 di Akun AWS dalam hal yang sama Wilayah AWS di mana Anda ingin mengonfigurasi Aturan Anda.
Pastikan Anda memberikan AWS IoT Core akses untuk membaca
FileDescriptorSetdari S3. Jika bucket S3 Anda memiliki enkripsi sisi server (SSE) dinonaktifkan atau jika bucket S3 Anda dienkripsi menggunakan Amazon S3-managed kunci (SSE-S3), tidak diperlukan konfigurasi kebijakan tambahan. 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:::<BUCKET NAME>/<FILENAME>.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 melakukan ini 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 di Aturan
Setelah mengunggah file deskriptor ke bucket Amazon S3 Anda, konfigurasikan Aturan yang dapat memecahkan kode format payload pesan protobuf Anda menggunakan decode (nilai, decodingScheme) Fungsi SQL. Tanda tangan fungsi terperinci dan contoh dapat ditemukan di decode (nilai, decodingScheme) Fungsi SQL dari AWS IoT Referensi SQL.
Berikut ini adalah contoh ekspresi SQL menggunakan decode (nilai, decodingScheme) fungsi:
SELECT VALUE decode(*, 'proto', '<BUCKET NAME>', '<FILENAME>.desc', '<PROTO_FILENAME>', '<PROTO_MESSAGE_TYPE>') FROM '<MY_TOPIC>'
Dalam contoh ekspresi ini:
-
Anda menggunakan decode (nilai, decodingScheme) Fungsi SQL untuk memecahkan kode payload pesan biner yang direferensikan oleh
*. Ini bisa berupa payload yang dikodekan protobug biner atau string JSON yang mewakili payload protobuf yang dikodekan base64. -
Payload pesan yang disediakan dikodekan menggunakan
Personjenis pesan didefinisikan dalamPROTO_FILENAME.proto. -
Bucket Amazon S3 bernama
BUCKET NAMEberisiFILENAME.descdihasilkan dariPROTO_FILENAME.proto.
Setelah Anda menyelesaikan konfigurasi, publikasikan pesan ke AWS IoT Core pada topik di mana Aturan berlangganan.
Batasan
AWS IoT Core Aturan mendukung protobuf dengan batasan berikut:
-
Menguraikan muatan pesan protobuf di dalamnya templat substitusi tidak didukung.
-
Saat mendekode muatan pesan protobuf, Anda dapat menggunakan memecahkan kode fungsi SQL dalam satu ekspresi SQL hingga dua kali.
-
Ukuran payload masuk maksimum adalah 128 KiB (1KiB =1024 byte), ukuran payload keluar maksimum adalah 128 KiB, dan ukuran maksimum untuk
FileDescriptorSetobjek yang disimpan dalam bucket Amazon S3 adalah 32 KiB. -
Bucket Amazon S3 dienkripsi dengan SSE-C Enkripsi 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 cadangan saat menjalankan protoc, ini dapat menyebabkan masalah pada tumpukan produksi Anda. Ada beberapa cara untuk mencadangkan file Anda di bucket Amazon S3. Misalnya, Anda bisa gunakan pembuatan versi di bucket S3. Untuk informasi selengkapnya tentang cara membuat cadangan file di bucket Amazon S3, lihat Panduan Pengembang Amazon S3.
-
Konfigurasikan AWS IoT log untuk melihat entri log.
Ini adalah praktik yang baik untuk mengkonfigurasi AWS IoT log sehingga Anda dapat memeriksa AWS IoT log untuk akun Anda di CloudWatch. Ketika kueri SQL aturan memanggil fungsi eksternal, AWS IoT Core Aturan menghasilkan entri log dengan
eventTypedariFunctionExecution, 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 lebih lanjut tentang cara mengkonfigurasi AWS IoT mencatat dan melihat entri log, lihat Konfigurasikan AWS IoT penebangan dan Aturan entri log mesin. -
Perbarui
FileDescriptorSetmenggunakan kunci objek baru dan memperbarui kunci objek di Aturan Anda.Anda dapat memperbarui
FileDescriptorSetdengan mengunggah file deskriptor yang diperbarui ke bucket Amazon S3 Anda. Pembaruan Anda keFileDescriptorSetbisa memakan waktu hingga 15 menit untuk direfleksikan. Untuk menghindari penundaan ini, sebaiknya unggah pembaruanFileDescriptorSetmenggunakan kunci objek baru, dan memperbarui kunci objek di Aturan Anda.