View a markdown version of this page

Bekerja dengan payload biner - AWS IoT Core

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.

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 SELECT klausa 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 SELECT klausa.

    • 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 SELECT klausa dengan payload biner.

    • Berikut ini mengacu pada device_type dalam 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) 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 mengirim data dalam ukuran paket kecil dan pada kecepatan yang lebih cepat daripada format pesan lainnya. AWS IoT Core Aturan mendukung protobuf dengan menyediakan decode (nilai, decodingScheme) Fungsi SQL, yang memungkinkan Anda untuk memecahkan kode muatan pesan yang dikodekan protobug ke format JSON dan merutekkannya ke layanan hilir. Bagian ini merinci proses langkah demi langkah untuk mengkonfigurasi decoding protobuf di AWS IoT Core Aturan.

Prasyarat

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 compiler untuk mengkompilasinya.

  1. Buat .proto file yang menentukan jenis pesan. Sebuah contoh .proto file dapat terlihat seperti berikut:

    syntax = "proto3"; message Person { optional string name = 1; optional int32 id = 2; optional string email = 3; }

    Dalam contoh ini .proto file, Anda menggunakan sintaks proto3 dan menentukan jenis pesan Person. Person definisi pesan menentukan tiga bidang (nama, id, dan email). Untuk informasi lebih lanjut tentang .proto format pesan file, lihat Panduan Bahasa (proto3).

  2. Gunakan protoc kompiler untuk mengkompilasi .proto file 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>.proto

    Perintah 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_out

      Menentukan nama file deskriptor (<FILENAME>.desc ) yang harus dihasilkan.

    • --proto_path

      Menentukan lokasi yang diimpor .proto file yang direferensikan oleh file yang sedang dikompilasi. Anda dapat menentukan bendera beberapa kali jika Anda memiliki beberapa yang diimpor .proto file dengan lokasi yang berbeda.

    • --include_imports

      Menentukan bahwa setiap yang diimpor .proto file juga harus dikompilasi dan dimasukkan dalam <FILENAME>.desc file deskriptor.

    • <PROTO_FILENAME>.proto

      Menentukan nama .proto file 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 FileDescriptorSet dari 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 Person jenis pesan didefinisikan dalam PROTO_FILENAME.proto.

  • Bucket Amazon S3 bernama BUCKET NAME berisi FILENAME.desc dihasilkan dari PROTO_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 FileDescriptorSet objek 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 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 lebih lanjut tentang cara mengkonfigurasi AWS IoT mencatat dan melihat entri log, lihat Konfigurasikan AWS IoT penebangan dan Aturan entri log mesin.

  • Perbarui FileDescriptorSet menggunakan kunci objek baru dan memperbarui kunci objek di Aturan Anda.

    Anda dapat memperbarui FileDescriptorSet dengan mengunggah file deskriptor yang diperbarui ke bucket Amazon S3 Anda. Pembaruan Anda ke FileDescriptorSet bisa memakan waktu hingga 15 menit untuk direfleksikan. Untuk menghindari penundaan ini, sebaiknya unggah pembaruan FileDescriptorSet menggunakan kunci objek baru, dan memperbarui kunci objek di Aturan Anda.