Membuat dan mengelola perintah - AWS IoT Core
Buat sumber daya perintahMengambil informasi tentang perintahDaftar perintah di Akun AWSPerbarui sumber daya perintahMenghentikan atau memulihkan sumber daya perintahHapus sumber daya perintah

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Membuat dan mengelola perintah

Gunakan AWS IoT Device Management Perintah untuk mengonfigurasi tindakan jarak jauh yang dapat digunakan kembali atau mengirim instruksi langsung ke perangkat. Buat dan kelola Perintah dari AWS IoT konsol atau gunakan AWS CLI.

Buat sumber daya perintah

Berikan informasi berikut saat membuat Command:

  • Informasi umum

    Berikan ID Perintah unik untuk mengidentifikasi Perintah saat menjalankannya pada perangkat target. Secara opsional menentukan nama tampilan, deskripsi, dan tag untuk manajemen.

  • Muatan

    Untuk Perintah statis, berikan tindakan perangkat yang menentukan Payload. Tentukan jenis format Payload untuk interpretasi perangkat yang benar.

    Untuk Perintah dinamis, lihat atribut template Payload.

  • Templat muatan

    Untuk Commands dinamis, sediakan PayloadTemplate dengan placeholder dan parameter. Secara opsional menyediakan defaultValue dan kondisi. AWS IoT Device Management Perintah menggantikan placeholder saat runtime. Parameter yang hilang menggunakan defaultValue mereka. Semua nilai harus memenuhi kondisi yang ditentukan.

    Jenis placeholder peka huruf besar/kecil berikut didukung:

    • ${aws:iot:commandexecution::parameter:parameter1}— Sebuah placeholder untuk nilai parameter dengan nama. parameter1

    • ${aws:iot:commandexecution::executionTimeoutSec}— Sebuah placeholder untuk parameter batas waktu eksekusi perintah yang disediakan saat runtime.

Perintah yang dicadangkan Topik menggunakan format berdasarkan jenis format Payload.

  • Untuk application/json atau jenis application/cbor konten, gunakan permintaan ini Topik:

    $aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

  • Untuk jenis konten lain atau format yang tidak ditentukan, gunakan permintaan ini Topik. Format Payload muncul di header pesan MQTT.

    $aws/commands/<devices>/<DeviceID>/executions/+/request

Topik respons Perintah menggunakan json atau cbor memformat apa pun jenis Payload. <PayloadFormat>harus json ataucbor:

$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

Bagian berikut menjelaskan pertimbangan format Payload dan pembuatan Command dari konsol.

Format payload perintah statis

Payload mendukung format apa pun hingga 32 KB. Tentukan jenis format Payload untuk interpretasi perangkat yang aman dan benar.

Tentukan jenis format Payload menggunakan type/subtype format (misalnya, application/json atauapplication/cbor). Default: application/octet-stream. Lihat Jenis MIME umum untuk format yang didukung.

Format payload perintah dinamis

PayloadTemplate harus JSON yang valid dengan setidaknya satu placeholder, hingga 32 KB.

Untuk AwsJsonSubstitution preprocessor, AWS IoT Device Management Command mengirimkan notifikasi dalam format JSON atau CBOR berdasarkan konfigurasi preprocessor.

Cara membuat perintah (konsol)

Untuk membuat Command dari konsol, buka Command Hub dan ikuti langkah-langkah berikut:

  1. Pilih Buat perintah.

  2. Tentukan ID Perintah yang unik.

  3. (Opsional) Tentukan nama tampilan, deskripsi, dan tag.

  4. Unggah file Payload yang berisi tindakan perangkat. Tentukan jenis format Payload untuk interpretasi perangkat yang benar.

  5. (Opsional) Untuk template payload JSON dengan placeholder, parameter diisi sebelumnya dalam tabel sebaris untuk diedit.

  6. (Opsional) Konfigurasikan jenis nilai parameter (wajib), nilai default, dan kondisi.

  7. Pilih Buat perintah.

Gunakan perintah CreateCommandAPI atau create-commandCLI untuk membuat Command.

Muatan perintah

Berikan templat Payload atau payload statis. Muatan Statis dikodekan base64. Untuk templat payload, Payload akhir dihasilkan saat runtime menggunakan nilai parameter. Perangkat memproses Payload dan melakukan tindakan yang ditentukan. Tentukan jenis konten Payload untuk penerimaan perangkat yang benar.

catatan

Muatan tidak dapat dimodifikasi setelah pembuatan Command. Buat Command baru untuk memodifikasi Payload.

Contoh kebijakan IAM

Sebelum Anda menggunakan operasi API ini, pastikan bahwa kebijakan IAM Anda mengizinkan Anda untuk melakukan tindakan ini pada perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan CreateCommand tindakan.

Dalam contoh ini, ganti:

  • regiondengan Anda Wilayah AWS, sepertius-east-1.

  • account-iddengan Akun AWS nomor Anda, seperti123456789012.

  • command-iddengan pengenal unik untuk ID AWS IoT perintah Anda, sepertiLockDoor. Jika Anda ingin mengirim lebih dari satu perintah, Anda dapat menentukan perintah ini di bawah bagian Sumber Daya dalam kebijakan IAM.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:CreateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Contoh pembuatan perintah statis

Contoh berikut menunjukkan bagaimana Anda dapat membuat perintah statis. Tergantung pada aplikasi Anda, ganti:

  • <command-id>dengan pengidentifikasi unik untuk perintah. Misalnya, untuk mengunci pintu rumah Anda, Anda dapat menentukanLockDoor. Kami menyarankan Anda menggunakan UUID. Anda juga dapat menggunakan karakter alfa-numerik, “-”, dan “_”.

  • (Opsional) <display-name> dan<description>, yang merupakan bidang opsional yang dapat Anda gunakan untuk memberikan nama yang ramah dan deskripsi yang bermakna untuk perintah, sepertiLock the doors of my home.

  • namespace, yang dapat Anda gunakan untuk menentukan namespace perintah. Itu pastiAWS-IoT. Untuk informasi tentang penggunaan fitur ini AWS IoT FleetWise, lihat Perintah jarak jauh

  • payloadberisi informasi tentang payload yang ingin Anda gunakan saat menjalankan perintah dan jenis kontennya.

aws iot create-command \ 
    --command-id <command-id> \
    --display-name <display-name> \
    --description <description> \ 
    --namespace AWS-IoT \ 
    --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}'

Menjalankan perintah ini menghasilkan respons yang berisi ID dan ARN (nama sumber daya Amazon) dari perintah tersebut. Misalnya, jika Anda menentukan LockDoor perintah selama pembuatan, berikut ini menunjukkan contoh output menjalankan perintah.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor"
}

Contoh pembuatan perintah dinamis

Contoh berikut menunjukkan bagaimana Anda dapat membuat perintah dinamis. Tergantung pada aplikasi Anda, ganti:

  • <command-id>dengan pengidentifikasi unik untuk perintah. Misalnya, untuk mengatur status daya cahaya, Anda dapat menentukanLight_Power_Status. Kami menyarankan Anda menggunakan UUID. Anda juga dapat menggunakan karakter alfa-numerik, “-”, dan “_”.

  • (Opsional) <display-name> dan<description>, yang merupakan bidang opsional yang dapat Anda gunakan untuk memberikan nama yang ramah dan deskripsi yang bermakna untuk perintah, sepertiTurn a light ON or OFF.

  • namespace, yang dapat Anda gunakan untuk menentukan namespace perintah. Itu pastiAWS-IoT. Untuk informasi tentang penggunaan fitur ini AWS IoT FleetWise, lihat Perintah jarak jauh

  • payloadTemplateberisi template playoad berformat JSON dengan placehodlers.

  • preprocessorberisi konfigurasi untuk preprocessor yang menentukan bagaimana PayloadTemplate harus diproses.

  • mandatoryParameterberisi parameter yang sesuai dengan placeholder di PayloadTemplate, jenisnya, nilai default, dan kondisi.

aws iot create-command \
    --command-id Light_Power_Status \
    --description "Turn a light ON or OFF" \
    --namespace AWS-IoT \
    --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \
    --preprocessor awsJsonSubstitution={outputFormat=JSON} \
    --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]"

Menjalankan perintah ini menghasilkan respons yang berisi ID dan ARN (nama sumber daya Amazon) dari perintah tersebut. Misalnya, jika Anda menentukan Light_Power_Status perintah selama pembuatan, berikut ini menunjukkan contoh output menjalankan perintah.

{
    "commandId": "Light_Power_Status",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status"
}

Mengambil informasi tentang perintah

Setelah Anda membuat perintah, Anda dapat mengambil informasi tentang hal itu dari AWS IoT konsol dan menggunakan. AWS CLI Anda dapat memperoleh informasi berikut.

  • ID perintah, nama sumber daya Amazon (ARN), nama tampilan dan deskripsi apa pun yang Anda tentukan untuk perintah tersebut.

  • Status perintah, yang menunjukkan apakah perintah tersedia untuk dijalankan pada perangkat target, atau apakah perintah itu tidak digunakan lagi atau dihapus.

  • Payload atau payloadTemplate yang Anda berikan.

  • Preprocessor yang Anda berikan.

  • MandatoryParameters yang Anda berikan.

  • Waktu ketika perintah dibuat dan terakhir diperbarui.

Untuk mengambil perintah dari konsol, buka Command Hub AWS IoT konsol dan kemudian pilih perintah yang Anda buat untuk melihat detailnya.

Selain detail perintah, Anda dapat melihat riwayat perintah, yang memberikan informasi tentang eksekusi perintah pada perangkat target. Setelah Anda menjalankan perintah ini pada perangkat, Anda dapat menemukan informasi tentang eksekusi pada tab ini.

Gunakan operasi API bidang kontrol GetCommandHTTP atau get-command AWS CLI perintah untuk mengambil informasi tentang sumber daya perintah. Anda harus sudah membuat perintah menggunakan permintaan CreateCommand API atau create-command CLI.

Contoh kebijakan IAM

Sebelum Anda menggunakan operasi API ini, pastikan bahwa kebijakan IAM Anda mengizinkan Anda untuk melakukan tindakan ini pada perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan GetCommand tindakan.

Dalam contoh ini, ganti:

  • regiondengan Anda Wilayah AWS, sepertius-east-1.

  • account-iddengan Akun AWS nomor Anda, seperti123456789023.

  • command-iddengan pengidentifikasi perintah AWS IoT unik Anda, seperti LockDoor atauLight_Power_Status. Jika Anda ingin mengambil lebih dari satu perintah, Anda dapat menentukan perintah ini di bawah bagian Sumber daya dalam kebijakan IAM.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:GetCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Ambil contoh perintah ()AWS CLI

Contoh berikut menunjukkan cara untuk mengambil informasi tentang perintah menggunakan. get-command AWS CLI Bergantung pada aplikasi Anda, ganti <command-id> dengan pengenal untuk perintah yang ingin Anda ambil informasinya. Anda dapat memperoleh informasi ini dari tanggapan create-command CLI.

aws iot get-command --command-id <command-id>

Menjalankan perintah ini menghasilkan respons yang berisi informasi tentang perintah, payload, dan waktu ketika itu dibuat dan terakhir diperbarui. Ini juga memberikan informasi yang menunjukkan apakah perintah telah usang atau sedang dihapus.

Misalnya, kode berikut menunjukkan respons sampel. 

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:<region>:<account>:command/LockDoor",
    "namespace": "AWS-IoT",
    "payload":{
        "content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=",
        "contentType": "application/json"
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
    "deprecated": false,
    "pendingDeletion": false
}

Daftar perintah di Akun AWS

Setelah Anda membuat perintah, Anda dapat melihat perintah yang telah Anda buat di akun Anda. Dalam daftar, Anda dapat menemukan informasi tentang:

  • ID perintah, dan nama tampilan apa pun yang Anda tentukan untuk perintah.

  • Nama sumber daya Amazon (ARN) dari perintah.

  • Status perintah yang menunjukkan apakah perintah tersedia untuk dijalankan pada perangkat target, atau apakah perintah tersebut tidak digunakan lagi.

    catatan

    Daftar tidak menampilkan yang sedang dihapus dari akun Anda. Jika perintah tertunda penghapusan, Anda masih dapat melihat detail untuk perintah ini menggunakan ID perintah mereka.

  • Waktu ketika perintah dibuat dan terakhir diperbarui.

Di AWS IoT konsol, Anda dapat menemukan daftar perintah yang Anda buat dan detailnya dengan masuk ke Command Hub.

Untuk membuat daftar perintah yang Anda buat, gunakan operasi ListCommandsAPI atau list-commandsCLI.

Contoh kebijakan IAM

Sebelum Anda menggunakan operasi API ini, pastikan bahwa kebijakan IAM Anda mengizinkan Anda untuk melakukan tindakan ini pada perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan ListCommands tindakan.

Dalam contoh ini, ganti:

  • regiondengan Anda Wilayah AWS, sepertius-east-1.

  • account-iddengan Akun AWS nomor Anda, seperti123456789012.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:ListCommands",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/*"
    }
}

Daftar perintah dalam contoh akun Anda

Perintah berikut menunjukkan cara membuat daftar perintah di akun Anda.

aws iot list-commands --namespace "AWS-IoT"

Menjalankan perintah ini menghasilkan respons yang berisi daftar perintah yang Anda buat, waktu ketika perintah dibuat dan kapan terakhir diperbarui. Ini juga menyediakan informasi status perintah, yang menunjukkan apakah perintah telah usang atau tersedia untuk dijalankan pada perangkat target. Untuk informasi selengkapnya tentang status dan alasan status yang berbeda, lihatStatus pelaksanaan perintah.

Perbarui sumber daya perintah

Setelah Anda membuat perintah, Anda dapat memperbarui nama tampilan dan deskripsi perintah.

catatan

Payload untuk perintah tidak dapat diperbarui. Untuk memperbarui informasi ini atau menggunakan payload yang dimodifikasi, Anda harus membuat perintah baru.

Untuk memperbarui perintah dari konsol, buka Command Hub AWS IoT konsol dan lakukan langkah-langkah berikut.

  1. Untuk memperbarui sumber daya perintah yang ada, pilih perintah yang ingin Anda perbarui, lalu di bawah Tindakan, pilih Edit.

  2. Tentukan nama tampilan dan deskripsi yang ingin Anda gunakan, dan pasangan nama-nilai apa pun sebagai tag untuk perintah Anda.

  3. Pilih Edit untuk menyimpan perintah dengan pengaturan baru.

Gunakan operasi API bidang UpdateCommandkontrol atau update-command AWS CLI untuk memperbarui sumber daya perintah. Dengan menggunakan API ini, Anda dapat:

  • Edit nama tampilan dan deskripsi perintah yang Anda buat.

  • Menghentikan sumber daya perintah, atau memulihkan perintah yang sudah tidak digunakan lagi.

Contoh kebijakan IAM

Sebelum Anda menggunakan operasi API ini, pastikan bahwa kebijakan IAM Anda mengizinkan Anda untuk melakukan tindakan ini pada perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan UpdateCommand tindakan.

Dalam contoh ini, ganti:

  • regiondengan Anda Wilayah AWS, sepertius-east-1.

  • account-iddengan Akun AWS nomor Anda, seperti123456789012.

  • command-iddengan pengidentifikasi perintah AWS IoT unik Anda, sepertiLockDoor. Jika Anda ingin mengambil lebih dari satu perintah, Anda dapat menentukan perintah ini di bawah bagian Sumber daya dalam kebijakan IAM.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:UpdateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Perbarui informasi tentang contoh perintah (AWS CLI)

Contoh berikut menunjukkan kepada Anda cara memperbarui informasi tentang perintah menggunakan update-command AWS CLI perintah. Untuk informasi tentang cara menggunakan API ini untuk menghentikan atau memulihkan sumber daya perintah, lihat. Perbarui sumber daya perintah (CLI)

Contoh menunjukkan bagaimana Anda dapat memperbarui nama tampilan dan deskripsi perintah. Bergantung pada aplikasi Anda, ganti <command-id> dengan pengenal untuk perintah yang ingin Anda ambil informasinya.

aws iot update-command \ 
    --command-id <command-id>    
    --displayname <display-name> \
    --description <description>

Menjalankan perintah ini menghasilkan respons yang berisi informasi terbaru tentang perintah dan waktu terakhir diperbarui. Kode berikut menunjukkan permintaan sampel dan respons untuk memperbarui nama tampilan dan deskripsi perintah yang mematikan AC.

aws iot update-command \ 
    --command-id <LockDoor> \ 
    --displayname <Secondary lock door> \
    --description <Locks doors to my home>

Menjalankan perintah ini menghasilkan respons berikut.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
    "displayName": "Secondary lock door",
    "description": "Locks doors to my home",
    "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00"
}

Menghentikan atau memulihkan sumber daya perintah

Setelah Anda membuat perintah, jika tidak lagi ingin melanjutkan menggunakan perintah, Anda dapat menandainya sebagai usang. Saat Anda menghentikan perintah, semua eksekusi perintah yang tertunda akan terus berjalan di perangkat target hingga mencapai status terminal. Setelah perintah tidak digunakan lagi, jika Anda ingin menggunakannya seperti untuk mengirim eksekusi perintah baru ke perangkat target, Anda harus memulihkannya.

catatan

Anda tidak dapat mengedit perintah usang, atau menjalankan eksekusi baru untuk itu. Untuk menjalankan perintah baru pada perangkat, Anda harus mengembalikannya sehingga status perintah berubah menjadi Tersedia.

Untuk informasi tambahan tentang menghentikan dan memulihkan perintah, dan pertimbangan untuk itu, lihat. Menghentikan sumber daya perintah

Hapus sumber daya perintah

Jika Anda tidak lagi ingin menggunakan perintah, Anda dapat menghapusnya secara permanen dari akun Anda. Jika tindakan penghapusan berhasil:

  • Jika perintah tidak digunakan lagi untuk durasi yang lebih lama dari batas waktu maksimum 12 jam, perintah akan segera dihapus.

  • Jika perintah tidak digunakan lagi, atau tidak digunakan lagi untuk durasi yang lebih pendek dari batas waktu maksimum, perintah akan berada dalam status. pending deletion Ini akan dihapus secara otomatis dari akun Anda setelah batas waktu maksimum 12 jam.

catatan

Perintah dapat dihapus bahkan jika ada eksekusi perintah yang tertunda. Perintah akan berada dalam status penghapusan tertunda dan akan dihapus dari akun Anda secara otomatis.

Untuk menghapus perintah dari konsol, buka Command Hub AWS IoT konsol dan lakukan langkah-langkah berikut.

  1. Pilih perintah yang ingin Anda hapus, dan kemudian di bawah Tindakan, pilih Hapus.

  2. Konfirmasikan bahwa Anda ingin menghapus perintah dan kemudian pilih Hapus.

Perintah akan ditandai untuk dihapus dan akan dihapus secara permanen dari akun Anda setelah 12 jam.

Gunakan operasi API bidang kontrol DeleteCommand HTTP atau delete-command AWS CLI perintah untuk menghapus sumber daya perintah. Jika tindakan penghapusan berhasil, Anda akan melihat HTTP statusCode 204 atau 202, dan perintah akan dihapus dari akun Anda secara otomatis setelah durasi batas waktu maksimum 12 jam. Dalam kasus status 204, ini menunjukkan bahwa perintah telah dihapus.

Contoh kebijakan IAM

Sebelum Anda menggunakan operasi API ini, pastikan bahwa kebijakan IAM Anda mengizinkan Anda untuk melakukan tindakan ini pada perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan DeleteCommand tindakan.

Dalam contoh ini, ganti:

  • regiondengan Anda Wilayah AWS, sepertius-east-1.

  • account-iddengan Akun AWS nomor Anda, seperti123456789012.

  • command-iddengan pengidentifikasi perintah AWS IoT unik Anda, sepertiLockDoor. Jika Anda ingin mengambil lebih dari satu perintah, Anda dapat menentukan perintah ini di bawah bagian Sumber daya dalam kebijakan IAM.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:DeleteCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Hapus contoh perintah (AWS CLI)

Contoh berikut menunjukkan cara menghapus perintah menggunakan delete-command AWS CLI perintah. Bergantung pada aplikasi Anda, ganti <command-id> dengan pengenal untuk perintah yang Anda hapus.

aws iot delete-command --command-id <command-id>

Jika permintaan API berhasil, maka perintah menghasilkan kode status 202 atau 204. Anda dapat menggunakan GetCommand API untuk memverifikasi bahwa perintah tidak ada lagi di akun Anda.