Gunakan DescribeStream untuk mendapatkan data aliran Dapatkan blok data dari file stream Menangani kesalahan dari AWS IoT MQTT-based pengiriman file

Penggunaan AWS IoT MQTT-based pengiriman file di perangkat

Untuk memulai proses transfer data, perangkat harus menerima kum pulan data awal, yang mencakup ID aliran minimal. Anda dapat menggunakan AWS IoT Lowongan Kerja a untuk menjadwalkan tugas transfer data untuk perangkat Anda dengan menyertakan kumpulan data awal dalam dokumen pekerjaan. Ketika perangkat menerima kumpulan data awal, maka harus memulai interaksi dengan pengiriman AWS IoT MQTT-based file. Untuk bertukar data dengan pengiriman AWS IoT MQTT-based file, perangkat harus:

Gunakan protokol MQTT untuk berlangganan. MQTT-based topik pengiriman file
Kirim permintaan dan kemudian tunggu untuk menerima tanggapan menggunakan pesan MQTT.

Anda dapat secara opsional menyertakan ID file aliran dan versi aliran dalam kumpulan data awal. Mengirim ID file aliran ke perangkat dapat menyederhanakan pemrograman perangkat firmware/software, karena menghilangkan kebutuhan untuk membuat DescribeStream permintaan dari perangkat untuk mendapatkan ID ini. Perangkat dapat menentukan versi streaming dalam GetStream permintaan untuk menerapkan pemeriksaan konsistensi jika aliran telah diperbarui secara tidak terduga.

Gunakan DescribeStream untuk mendapatkan data aliran

AWS IoT MQTT-based pengiriman file menyediakan DescribeStream API untuk mengirim data aliran ke perangkat. Data aliran yang dikembalikan oleh API ini mencakup ID aliran, versi aliran, deskripsi aliran, dan daftar file aliran, yang masing-masing memiliki ID file dan ukuran file dalam byte. Dengan informasi ini, perangkat dapat memilih file arbitrer untuk memulai proses transfer data.

catatan

Anda tidak perlu menggunakan DescribeStream API jika perangkat menerima semua ID file aliran yang diperlukan dalam kumpulan data awal.

Ikuti langkah-langkah ini untuk membuat DescribeStream permintaan.

Berlangganan filter topik “diterima”$aws/things/ThingName/streams/StreamId/description/json.
Berlangganan filter topik “ditolak”$aws/things/ThingName/streams/StreamId/rejected/json.
Publikasikan DescribeStream permintaan dengan mengirim pesan ke$aws/things/ThingName/streams/StreamId/describe/json.
Jika permintaan diterima, perangkat Anda menerima DescribeStream respons pada filter topik “diterima”.
Jika permintaan ditolak, perangkat Anda menerima respons kesalahan pada filter topik “ditolak”.

catatan

Jika Anda mengganti json dengan cbor dalam topik dan filter topik yang ditampilkan, perangkat Anda menerima pesan dalam format CBOR, yang lebih ringkas daripada JSON.

DescribeStream permintaan

Per DescribeStream mintaan tipikal di JSON terlihat seperti contoh berikut.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039"
}

(Opsional) c "" adalah bidang token klien.

Token klien tidak boleh lebih dari 64 byte. Token klien yang lebih panjang dari 64 byte menyebabkan respons kesalahan dan pesan InvalidRequest kesalahan.

DescribeStream tanggapan

Resp DescribeStream ons dalam JSON terlihat seperti contoh berikut.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039",
    "s": 1,
    "d": "This is the description of stream ABC.",
    "r": [
        {
            "f": 0,
            "z": 131072
        },
        {
            "f": 1,
            "z": 51200
        }
    ]
}

“c" adalah bidang token klien. Ini dikembalikan jika diberikan dalam DescribeStream permintaan. Gunakan token klien untuk mengaitkan respons dengan permintaannya.
“s" adalah versi aliran sebagai bilangan bulat. Anda dapat menggunakan versi ini untuk melakukan pemeriksaan konsistensi dengan GetStream permintaan Anda.
“r" berisi daftar file dalam aliran.
- “f" adalah ID file aliran sebagai bilangan bulat.
- “z" adalah ukuran file stream dalam jumlah byte.
“d" berisi deskripsi aliran.

Dapatkan blok data dari file stream

Anda dapat menggunakan GetStream API sehingga perangkat dapat menerima file aliran dalam blok data kecil, sehingga dapat digunakan oleh perangkat yang memiliki kendala dalam memproses ukuran blok besar. Untuk menerima seluruh file data, perangkat mungkin perlu mengirim atau menerima beberapa permintaan dan tanggapan hingga semua blok data diterima dan diproses.

GetStream permintaan

Ikuti langkah-langkah ini untuk membuat GetStream permintaan.

Berlangganan filter topik “diterima”$aws/things/ThingName/streams/StreamId/data/json.
Berlangganan filter topik “ditolak”$aws/things/ThingName/streams/StreamId/rejected/json.
Publikasikan GetStream permintaan ke topik$aws/things/ThingName/streams/StreamId/get/json.
Jika permintaan diterima, perangkat Anda akan menerima satu atau lebih GetStream tanggapan pada filter topik “diterima”. Setiap pesan respons berisi informasi dasar dan muatan data untuk satu blok.
Ulangi langkah 3 dan 4 untuk menerima semua blok data. Anda harus mengulangi langkah-langkah ini jika jumlah data yang diminta lebih besar dari 128 KB. Anda harus memprogram perangkat Anda untuk menggunakan beberapa GetStream permintaan untuk menerima semua data yang diminta.
Jika permintaan ditolak, perangkat Anda akan menerima respons kesalahan pada filter topik “ditolak”.

catatan

Jika Anda mengganti “json” dengan “cbor” di topik dan filter topik yang ditampilkan, perangkat Anda akan menerima pesan dalam format CBOR, yang lebih ringkas daripada JSON.
AWS IoT MQTT-based pengiriman file membatasi ukuran blok hingga 128 KB. Jika Anda membuat permintaan untuk blok yang lebih dari 128 KB, permintaan akan gagal.
Anda dapat membuat permintaan untuk beberapa blok yang ukuran totalnya lebih besar dari 128 KB (misalnya, jika Anda membuat permintaan untuk 5 blok masing-masing 32 KB untuk total 160 KB data). Dalam hal ini, permintaan tidak gagal, tetapi perangkat Anda harus membuat beberapa permintaan untuk menerima semua data yang diminta. Layanan ini akan mengirim blok tambahan saat perangkat Anda membuat permintaan tambahan. Kami menyarankan Anda melanjutkan permintaan baru hanya setelah tanggapan sebelumnya diterima dan diproses dengan benar.
Terlepas dari ukuran total data yang diminta, Anda harus memprogram perangkat Anda untuk memulai percobaan ulang ketika blok tidak diterima, atau tidak diterima dengan benar.

Per GetStream mintaan tipikal di JSON terlihat seperti contoh berikut.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "s": 1,
    "f": 0,
    "l": 4096,
    "o": 2,
    "n": 100,
    "b": "..."
}

[opsional] c "" adalah bidang token klien.

Token klien tidak boleh lebih dari 64 byte. Token klien yang lebih panjang dari 64 byte menyebabkan respons kesalahan dan pesan InvalidRequest kesalahan.
[opsional] s "" adalah bidang versi aliran (bilangan bulat).

MQTT-based pengiriman file menerapkan pemeriksaan konsistensi berdasarkan versi yang diminta ini dan versi streaming terbaru di cloud. Jika versi streaming yang dikirim dari perangkat dalam GetStream permintaan tidak cocok dengan versi streaming terbaru di cloud, layanan mengirimkan respons kesalahan dan pesan VersionMismatch kesalahan. Biasanya, perangkat menerima versi aliran yang diharapkan (terbaru) dalam kumpulan data awal atau dalam respons terhadapDescribeStream.
“f" adalah ID file aliran (bilangan bulat dalam kisaran 0 hingga 255).

ID file aliran diperlukan saat Anda membuat atau memperbarui aliran menggunakan SDK AWS CLI atau. Jika perangkat meminta file aliran dengan ID yang tidak ada, layanan mengirimkan respons kesalahan dan pesan ResourceNotFound kesalahan.
“l" adalah ukuran blok data dalam byte (integer dalam kisaran 256 hingga 131.072).

Lihat Membangun bitmap untuk permintaan GetStream petunjuk tentang cara menggunakan bidang bitmap untuk menentukan bagian mana dari file aliran yang akan dikembalikan dalam GetStream respons. Jika perangkat menentukan ukuran blok yang berada di luar jangkauan, layanan mengirimkan respons kesalahan dan pesan BlockSizeOutOfBounds kesalahan.
[opsional] o "" adalah offset blok dalam file aliran (bilangan bulat dalam kisaran 0 hingga 98,304).

Lihat Membangun bitmap untuk permintaan GetStream petunjuk tentang cara menggunakan bidang bitmap untuk menentukan bagian mana dari file aliran yang akan dikembalikan dalam GetStream respons. Nilai maksimum 98.304 didasarkan pada batas ukuran file aliran 24 MB dan 256 byte untuk ukuran blok minimum. Defaultnya adalah 0 jika tidak ditentukan.
[opsional] "n" adalah jumlah blok yang diminta (bilangan bulat dalam kisaran 0 hingga 98.304).

Bidang “n” menentukan (1) jumlah blok yang diminta, atau (2) ketika bidang bitmap (“b”) digunakan, batas jumlah blok yang akan dikembalikan oleh permintaan bitmap. Penggunaan kedua ini opsional. Jika tidak didefinisikan, defaultnya menjadi 13 DataBlockSize 1072/.
[opsional] b "" adalah bitmap yang mewakili blok yang diminta.

Menggunakan bitmap, perangkat Anda dapat meminta blok yang tidak berurutan, yang membuat penanganan percobaan ulang setelah kesalahan menjadi lebih nyaman. Lihat Membangun bitmap untuk permintaan GetStream petunjuk tentang cara menggunakan bidang bitmap untuk menentukan bagian mana dari file aliran yang akan dikembalikan dalam GetStream respons. Untuk bidang ini, konversi bitmap ke string yang mewakili nilai bitmap dalam notasi heksadesimal. Bitmap harus kurang dari 12.288 byte.

penting

Baik "n" atau b "" harus ditentukan. Jika tidak satu pun dari mereka ditentukan, GetStream permintaan mungkin tidak valid ketika ukuran file kurang dari 131072 byte (128 KB).

GetStream tanggapan

Resp GetStream ons dalam JSON terlihat seperti contoh ini untuk setiap blok data yang diminta.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "f": 0,
    "l": 4096,
    "i": 2,
    "p": "..."
}

“c" adalah bidang token klien. Ini dikembalikan jika diberikan dalam GetStream permintaan. Gunakan token klien untuk mengaitkan respons dengan permintaannya.
“f" adalah ID file aliran tempat payload blok data saat ini berada.
“l" adalah ukuran payload blok data dalam byte.
“i" adalah ID blok data yang terkandung dalam payload. Blok data diberi nomor mulai dari 0.
“p" berisi payload blok data. Bidang ini adalah string, yang mewakili nilai blok data dalam pengkodean Base64.

Membangun bitmap untuk permintaan GetStream

Anda dapat menggunakan bidang bitmap (b) dalam GetStream permintaan untuk mendapatkan blok non-berturut-turut dari file aliran. Ini membantu perangkat dengan kapasitas RAM terbatas menangani masalah pengiriman jaringan. Perangkat hanya dapat meminta blok yang tidak diterima atau tidak diterima dengan benar. Bitmap menentukan blok mana dari file stream yang akan dikembalikan. Untuk setiap bit, yang diatur ke 1 di bitmap, blok yang sesuai dari file stream akan dikembalikan.

Berikut adalah contoh cara menentukan bitmap dan bidang pendukungnya dalam GetStream permintaan. Misalnya, Anda ingin menerima file aliran dalam potongan 256 byte (ukuran blok). Pikirkan setiap blok 256 byte memiliki angka yang menentukan posisinya dalam file, mulai dari 0. Jadi blok 0 adalah blok pertama 256 byte dalam file, blok 1 adalah yang kedua, dan seterusnya. Anda ingin meminta blok 20, 21, 24 dan 43 dari file.

Blokir offset

Karena blok pertama adalah nomor 20, tentukan offset (bidango) sebagai 20 untuk menghemat ruang di bitmap.

Jumlah blok

Untuk memastikan perangkat Anda tidak menerima lebih banyak blok daripada yang dapat ditangani dengan sumber daya memori terbatas, Anda dapat menentukan jumlah blok maksimum yang harus dikembalikan dalam setiap pesan yang dikirim melalui pengiriman MQTT-based file. Perhatikan bahwa nilai ini diabaikan jika bitmap itu sendiri menentukan kurang dari jumlah blok ini, atau jika itu akan membuat ukuran total pesan respons yang dikirim oleh pengiriman MQTT-based file lebih besar dari batas layanan 128 KB per GetStream permintaan.

Blokir bitmap

Bitmap itu sendiri adalah array byte yang tidak ditandatangani yang dinyatakan dalam notasi heksadesimal, dan termasuk dalam GetStream permintaan sebagai representasi string dari angka tersebut. Tetapi untuk membangun string ini, mari kita mulai dengan memikirkan bitmap sebagai urutan bit yang panjang (bilangan biner). Jika bit dalam urutan ini diatur ke 1, blok yang sesuai dari file stream akan dikirim kembali ke perangkat. Sebagai contoh kita, kita ingin menerima blok 20, 21, 24, dan 43, jadi kita harus mengatur bit 20, 21, 24, dan 43 di bitmap kita. Kita dapat menggunakan offset blok untuk menghemat ruang, jadi setelah kita mengurangi offset dari setiap nomor blok, kita ingin mengatur bit 0, 1, 4, dan 23, seperti contoh berikut.


 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1

Mengambil satu byte (8 bit) pada satu waktu, ini secara konvensional ditulis sebagai: “0b00010011", “0b00000000", dan “0b10000000". Bit 0 muncul dalam representasi biner kami di akhir byte pertama, dan bit 23 di awal yang terakhir. Ini bisa membingungkan kecuali Anda tahu konvensi. Byte pertama berisi bit 7-0 (dalam urutan itu), byte kedua berisi bit 15-8, byte ketiga berisi bit 23-16, dan seterusnya. Dalam notasi heksadesimal, ini diubah menjadi “0x130080".

Tip

Anda dapat mengonversi biner standar menjadi notasi heksadesimal. Ambil empat digit biner sekaligus dan ubah ini menjadi ekuivalen heksadesimal mereka. Misalnya, “0001" menjadi “1", “0011" menjadi “3" dan seterusnya.

Blok rincian bitmap untuk membangun string dalam GetStream permintaan.

Menyatukan semua ini, JSON untuk GetStream permintaan kami terlihat seperti berikut.


{
    "c" : "1",       
    "s" : 1,         
    "l" : 256,       
    "f" : 1,         
    "o" : 20,        
    "n" : 32,       
    "b" : "130080"
}

“c" adalah bidang token klien.
“s" adalah versi streaming yang diharapkan.
“l" adalah ukuran payload blok data dalam byte.
“f" adalah ID dari indeks file sumber.
“o" adalah offset blok.
“n" adalah jumlah blok.
“b" adalah bitmap blockID yang hilang mulai dari offset. Nilai ini harus dibasikandikodekan 64.

Menangani kesalahan dari AWS IoT MQTT-based pengiriman file

Respons kesalahan yang dikirim ke perangkat untuk keduanya DescribeStream dan GetStream API berisi token klien, kode kesalahan, dan pesan kesalahan. Respons kesalahan tipikal terlihat seperti contoh berikut.


{
    "o": "BlockSizeOutOfBounds", 
    "m": "The block size is out of bounds", 
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380" 
}

“o" adalah kode kesalahan yang menunjukkan alasan terjadinya kesalahan. Lihat kode kesalahan nanti di bagian ini untuk detail selengkapnya.
“m" adalah pesan kesalahan yang berisi rincian kesalahan.
“c" adalah bidang token klien. Ini dapat dikembalikan jika diberikan dalam DescribeStream permintaan. Anda dapat menggunakan token klien untuk mengaitkan respons dengan permintaannya.

Bidang token klien tidak selalu disertakan dalam respons kesalahan. Ketika token klien yang diberikan dalam permintaan tidak valid atau cacat, itu tidak dikembalikan dalam respons kesalahan.

catatan

Untuk kompatibilitas mundur, bidang dalam respons kesalahan mungkin dalam bentuk yang tidak disingkat. Misalnya, kode kesalahan mungkin ditunjuk oleh bidang “kode” atau “o” dan bidang token klien dapat ditunjuk oleh bidang “ClientToken” atau “c”. Kami menyarankan Anda menggunakan bentuk singkatan yang ditunjukkan di atas.

InvalidTopic: Topik MQTT dari pesan aliran tidak valid.
InvalidJson: Permintaan Stream bukan dokumen JSON yang valid.
InvalidCbor: Permintaan Stream bukan dokumen CBOR yang valid.
InvalidRequest: Permintaan umumnya diidentifikasi sebagai salah format. Untuk informasi selengkapnya, lihat pesan kesalahan.
Tidak sah: Permintaan tidak diizinkan untuk mengakses file data aliran di media penyimpanan, seperti Amazon S3. Untuk informasi selengkapnya, lihat pesan kesalahan.
BlockSizeOutOfBounds: Ukuran blok di luar batas. Lihat bagian "Pen MQTT-based giriman File" di Kuota AWS IoT Core Layanan.
OffsetOutOfBounds: Offset berada di luar batas. Lihat bagian "Pen MQTT-based giriman File" di Kuota AWS IoT Core Layanan.
BlockCountLimitExceeded: Jumlah blok permintaan berada di luar batas. Lihat bagian "Pen MQTT-based giriman File" di Kuota AWS IoT Core Layanan.
BlockBitmapLimitExceeded: Ukuran bitmap permintaan berada di luar batas. Lihat bagian "Pen MQTT-based giriman File" di Kuota AWS IoT Core Layanan.
ResourceNotFound: Aliran yang diminta, file, versi file atau blok tidak ditemukan. Lihat pesan kesalahan untuk detail selengkapnya.
VersionMismatch: Versi streaming dalam permintaan tidak cocok dengan versi streaming di fitur pengiriman MQTT-based file. Ini menunjukkan bahwa data aliran telah dimodifikasi sejak versi streaming awalnya diterima oleh perangkat.
ETagMismatch: S3 ETag dalam streaming tidak cocok dengan ETag versi objek S3 terbaru.
InternalError: Terjadi kesalahan internal dalam pengiriman MQTT-based file.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Mengelola streaming

Contoh kasus penggunaan di FreeRTOS OTA