Menggunakan pengiriman AWS IoT file berbasis MQTT di perangkat

Untuk memulai proses transfer data, perangkat harus menerima kumpulan data awal, yang mencakup ID aliran minimal. Anda dapat menggunakan Tugas untuk menjadwalkan tugas transfer data untuk perangkat Anda dengan menyertakan kumpulan data awal dalam dokumen pekerjaan. Ketika perangkat menerima kumpulan data awal, perangkat tersebut kemudian harus memulai interaksi dengan pengiriman file berbasis AWS IoT MQTT. Untuk bertukar data dengan pengiriman file AWS IoT berbasis MQTT, perangkat harus:

• Gunakan protokol MQTT untuk berlangganan. Topik pengiriman file berbasis MQTT

• Kirim permintaan dan kemudian tunggu untuk menerima tanggapan menggunakan pesan MQTT.

Anda dapat secara opsional menyertakan ID file streaming dan versi aliran dalam kumpulan data awal. Mengirim ID file streaming ke perangkat dapat menyederhanakan pemrograman firmware/perangkat lunak perangkat, 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 streaming

AWS IoT Pengiriman file berbasis MQTT 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 Anda menerima semua ID file streaming yang diperlukan dalam kumpulan data awal.

Ikuti langkah-langkah ini untuk membuat DescribeStream permintaan.

1. Berlangganan filter topik “diterima”$aws/things/ThingName/streams/StreamId/description/json.

2. Berlangganan filter topik “ditolak”$aws/things/ThingName/streams/StreamId/rejected/json.

3. Publikasikan DescribeStream permintaan dengan mengirim pesan ke$aws/things/ThingName/streams/StreamId/describe/json.

4. Jika permintaan diterima, perangkat Anda menerima DescribeStream respons pada filter topik “diterima”.

5. Jika permintaan ditolak, perangkat Anda menerima respons kesalahan pada filter topik “ditolak”.

catatan

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

DescribeStream permintaan

DescribeStreamPermintaan khas 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 respon

DescribeStreamRespons di 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 streaming

Anda dapat menggunakan GetStream API sehingga perangkat dapat menerima file streaming 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 sampai semua blok data diterima dan diproses.

GetStream permintaan

Ikuti langkah-langkah ini untuk membuat GetStream permintaan.

1. Berlangganan filter topik “diterima”$aws/things/ThingName/streams/StreamId/data/json.

2. Berlangganan filter topik “ditolak”$aws/things/ThingName/streams/StreamId/rejected/json.

3. Publikasikan GetStream permintaan ke topik$aws/things/ThingName/streams/StreamId/get/json.

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

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

6. Jika permintaan ditolak, perangkat Anda akan menerima respons kesalahan pada filter topik “ditolak”.

catatan

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

• AWS IoT Pengiriman file berbasis MQTT 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 dengan total 160 KB data). Dalam hal ini, permintaan tidak gagal, tetapi perangkat Anda harus membuat beberapa permintaan untuk menerima semua data yang diminta. Layanan akan mengirim blok tambahan saat perangkat Anda membuat permintaan tambahan. Kami menyarankan Anda melanjutkan dengan permintaan baru hanya setelah tanggapan sebelumnya telah 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.

GetStreamPermintaan khas 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).

  Pengiriman file berbasis MQTT 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 akan mengirimkan respons kesalahan dan pesan VersionMismatch kesalahan. Biasanya, perangkat menerima versi aliran yang diharapkan (terbaru) dalam kumpulan data awal atau sebagai respons terhadapDescribeStream.

• “f" adalah ID file aliran (bilangan bulat dalam kisaran 0 hingga 255).

  ID file stream diperlukan saat Anda membuat atau memperbarui aliran menggunakan AWS CLI atau SDK. Jika perangkat meminta file streaming dengan ID yang tidak ada, layanan akan mengirimkan respons kesalahan dan pesan ResourceNotFound kesalahan.

• “l" adalah ukuran blok data dalam byte (bilangan bulat dalam kisaran 256 hingga 131.072).

  Lihat Membangun bitmap untuk permintaan GetStream petunjuk tentang cara menggunakan bidang bitmap untuk menentukan bagian file aliran mana yang akan dikembalikan dalam GetStream respons. Jika perangkat menentukan ukuran blok yang berada di luar jangkauan, layanan akan 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 file aliran mana 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 baik (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 ke 131072/. DataBlockSize

• [opsional] b "" adalah bitmap yang mewakili blok yang diminta.

  Menggunakan bitmap, perangkat Anda dapat meminta blok non-berturut-turut, 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 file aliran mana yang akan dikembalikan GetStream sebagai respons. Untuk bidang ini, ubah bitmap menjadi string yang mewakili nilai bitmap dalam notasi heksadesimal. Bitmap harus kurang dari 12.288 byte.

penting

Entah 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 respon

GetStreamRespons di 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 dari file aliran tempat muatan blok data saat ini berada.

• “l" adalah ukuran payload blok data dalam byte.

• “i" adalah ID dari blok data yang terdapat 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 streaming. Ini membantu perangkat dengan kapasitas RAM terbatas menangani masalah pengiriman jaringan. Perangkat hanya dapat meminta blok-blok yang tidak diterima atau tidak diterima dengan benar. Bitmap menentukan blok file stream mana yang akan dikembalikan. Untuk setiap bit, yang diatur ke 1 di bitmap, blok yang sesuai dari file aliran akan dikembalikan.

Berikut adalah contoh cara menentukan bitmap dan bidang pendukungnya dalam GetStream permintaan. Misalnya, Anda ingin menerima file streaming dalam potongan 256 byte (ukuran blok). Pikirkan setiap blok 256 byte memiliki nomor 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.

Blok offset

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

Jumlah blok

Untuk memastikan bahwa perangkat Anda tidak menerima lebih banyak blok daripada yang dapat ditangani dengan sumber daya memori terbatas, Anda dapat menentukan jumlah maksimum blok yang harus dikembalikan dalam setiap pesan yang dikirim oleh pengiriman file berbasis MQTT. 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 file berbasis MQTT lebih besar dari batas layanan 128 KB per permintaan. GetStream

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 nomor tersebut. Tetapi untuk membangun string ini, mari kita mulai dengan memikirkan bitmap sebagai urutan panjang bit (bilangan biner). Jika sedikit dalam urutan ini diatur ke 1, blok yang sesuai dari file aliran akan dikirim kembali ke perangkat. Sebagai contoh, 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 blok offset 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", “0b000000", 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 dikonversi menjadi “0x130080".

Tip

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

Menyatukan ini semua, 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 berdasarkan64-dikodekan.

Menangani kesalahan dari pengiriman AWS IoT file berbasis MQTT

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 salah bentuk, 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 formulir 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 cacat. Untuk informasi selengkapnya, lihat pesan kesalahan.

Tidak sah

Permintaan tidak diizinkan untuk mengakses file data streaming di media penyimpanan, seperti Amazon S3. Untuk informasi selengkapnya, lihat pesan kesalahan.

BlockSizeOutOfBounds

Ukuran blok di luar batas. Lihat bagian "Pengiriman File Berbasis MQTT" di Service Quotas.AWS IoT Core

OffsetOutOfBounds

Offset di luar batas. Lihat bagian "Pengiriman File Berbasis MQTT" di Service Quotas.AWS IoT Core

BlockCountLimitExceeded

Jumlah blok permintaan berada di luar batas. Lihat bagian "Pengiriman File Berbasis MQTT" di Service Quotas.AWS IoT Core

BlockBitmapLimitExceeded

Ukuran bitmap permintaan di luar batas. Lihat bagian "Pengiriman File Berbasis MQTT" di Service Quotas.AWS IoT Core

ResourceNotFound

Aliran, file, versi file, atau blok yang diminta tidak ditemukan. Lihat pesan kesalahan untuk detail selengkapnya.

VersionMismatch

Versi streaming dalam permintaan tidak cocok dengan versi streaming di fitur pengiriman file berbasis MQTT. Ini menunjukkan bahwa data aliran telah dimodifikasi sejak versi streaming awalnya diterima oleh perangkat.

E TagMismatch

S3 ETag dalam aliran tidak cocok dengan ETag dari versi objek S3 terbaru.

InternalError

Terjadi kesalahan internal dalam pengiriman file berbasis MQTT.