Bekerja dengan muatan biner - AWS IoT Core
Contoh muatan binerDecoding muatan pesan protobuf

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 * untuk merujuknya dalam klausa SELECT.

Contoh muatan biner

Bila Anda menggunakan* 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* 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, 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) 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), 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

Prasyarat

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 jenis pesan yang akan digunakan dalam serialisasi protobuf. Untuk menghasilkan file deskriptor, Anda harus menentukan .proto file dan menggunakan kompiler protoc untuk mengompilasinya.

  1. Buat .proto file yang menentukan jenis pesan. .protoFile 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).

  2. Gunakan kompiler protoc untuk mengkompilasi .proto file dan menghasilkan file deskriptor. Contoh perintah untuk membuat file descriptor (.desc) dapat menjadi 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 dapat digunakan AWS IoT Core Aturan untuk memecahkan kode muatan protobuf yang sesuai dengan struktur data yang ditentukan. <PROTO_FILENAME>.proto

    • --descriptor_set_out

      Menentukan nama file deskriptor (<FILENAME>.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 <FILENAME>.desc deskriptor.

    • <PROTO_FILENAME>.proto

      Menentukan nama .proto file yang ingin Anda kompilasi.

    Untuk informasi selengkapnya tentang referensi protokol, lihat Referensi API.

Unggah file deskriptor ke bucket S3

Setelah membuat file deskriptor<FILENAME>.desc, unggah file deskriptor <FILENAME>.desc ke bucket Amazon S3, menggunakan AWS API, SDK AWS , atau file. AWS Management Console

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:

    JSON
    {
	"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 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). Tanda tangan dan contoh fungsi terperinci dapat ditemukan di fungsi SQL decode (value, decodingScheme) dari referensi SQL.AWS IoT

Berikut ini adalah contoh ekspresi SQL menggunakan fungsi decode (value, decodingScheme):

SELECT VALUE decode(*, 'proto', '<BUCKET NAME>', '<FILENAME>.desc', '<PROTO_FILENAME>', '<PROTO_MESSAGE_TYPE>') FROM '<MY_TOPIC>'

Dalam contoh ekspresi ini:

  • Anda menggunakan fungsi SQL decode (value, decodingScheme) 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 langganan Aturan.

Batasan

AWS IoT Core Aturan mendukung protobuf dengan batasan berikut:

  • Decoding payload pesan protobuf dalam template substitusi tidak didukung.

  • Saat mendekode muatan pesan protobuf, Anda dapat menggunakan fungsi SQL decode dalam satu ekspresi SQL hingga 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. Untuk informasi selengkapnya tentang cara mencadangkan file di bucket Amazon S3, lihat Panduan Pengembang Amazon 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 dariFunctionExecution, 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 dan Aturan.

  • 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.