Memulai dan memantau pelaksanaan perintah

Tentukan perangkat target untuk menerima dan menjalankan Perintah. Gunakan nama Thing untuk perangkat terdaftar atau ID Klien untuk perangkat yang tidak terdaftar. Setelah menerima Payload, perangkat mengeksekusi Perintah dan melakukan tindakan tertentu.

AWS IoT hal

Perangkat target dapat berupa hal-hal yang terdaftar di AWS IoT registri. Hal-hal menyederhanakan pencarian dan manajemen perangkat.

Daftarkan perangkat sebagai Things dari halaman Hubungkan perangkat atau menggunakan CreateThing. Temukan Hal-hal yang ada dari Thing Hub atau menggunakan DescribeThing. Lihat Mengelola hal-hal dengan registri untuk detail pendaftaran.

ID klien

Untuk perangkat yang tidak terdaftar, gunakan ID Klien.

ID Klien adalah pengenal unik yang Anda tetapkan ke perangkat. Ditetapkan dalam protokol MQTT, berisi karakter alfanumerik, garis bawah, atau tanda hubung. Setiap perangkat yang terhubung AWS IoT memerlukan ID Klien yang unik.

ID Klien adalah ID klien MQTT yang digunakan perangkat saat menghubungkan ke AWS IoT Core. AWS IoT menggunakan ID ini untuk mengidentifikasi perangkat dan mengelola koneksi dan langganan.

Batas waktu menentukan durasi (dalam detik) untuk perangkat untuk memberikan hasil Eksekusi.

Setelah membuat Eksekusi, timer dimulai. Jika perangkat offline atau gagal melaporkan hasil dalam batas waktu, waktu Eksekusi habis dengan statusTIMED_OUT.

Default: 10 detik. Maksimal: 12 jam.

Nilai batas waktu dan status eksekusi TIMED_OUT

Baik cloud maupun perangkat dapat melaporkan batas waktu.

Setelah mengirim Perintah, timer dimulai. Jika tidak ada respons perangkat yang tiba dalam batas waktu, cloud menetapkan status Eksekusi ke TIMED_OUT dengan kode $NO_RESPONSE_FROM_DEVICE alasan.

Ini terjadi ketika:

Dalam hal ini, ketika status eksekusi dilaporkan dari cloud, eksekusi perintah adalah non-terminal. TIMED_OUT Perangkat Anda dapat mempublikasikan respons yang mengganti status ke salah satu status terminal:SUCCEEDED,FAILED, atau. REJECTED Eksekusi perintah kemudian menjadi terminal dan tidak menerima pembaruan lebih lanjut.

Perangkat Anda juga dapat memperbarui TIMED_OUT status yang diprakarsai oleh cloud dengan melaporkan bahwa batas waktu terjadi saat menjalankan perintah. Dalam hal ini, status eksekusi perintah tetap diTIMED_OUT, tetapi statusReason objek diperbarui berdasarkan informasi yang dilaporkan oleh perangkat. Eksekusi perintah kemudian menjadi terminal, dan tidak ada pembaruan lebih lanjut yang diterima.

Menggunakan sesi persisten MQTT

Anda dapat mengonfigurasi sesi persisten MQTT untuk digunakan dengan fitur AWS IoT Device Management perintah. Fitur ini sangat berguna dalam kasus-kasus seperti ketika perangkat Anda offline dan Anda ingin memastikan bahwa perangkat masih menerima perintah ketika kembali online sebelum durasi batas waktu, dan melakukan instruksi yang ditentukan.

Secara default, kedaluwarsa sesi persisten MQTT diatur ke 60 menit. Jika batas waktu eksekusi perintah Anda dikonfigurasi ke nilai yang melebihi durasi ini, eksekusi perintah yang berjalan lebih dari 60 menit dapat ditolak oleh broker pesan dan gagal. Untuk menjalankan perintah yang durasinya lebih dari 60 menit, Anda dapat meminta peningkatan waktu kedaluwarsa sesi persisten.

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

Gunakan operasi API bidang data StartCommandExecution HTTP untuk memulai eksekusi perintah. Permintaan dan respons API dikorelasikan oleh ID eksekusi perintah. Setelah perangkat selesai menjalankan perintah, perangkat dapat melaporkan status dan hasil eksekusi ke cloud dengan menerbitkan pesan ke topik respons perintah. Untuk kode respons khusus, kode aplikasi yang Anda miliki dapat memproses pesan respons dan memposting hasilnya ke AWS IoT.

Jika perangkat Anda telah berlangganan topik permintaan perintah, StartCommandExecution API akan menerbitkan pesan payload ke topik tersebut. Payload dapat menggunakan format apa pun pilihan Anda. Untuk informasi selengkapnya, lihat Muatan perintah.

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

Jika format payload bukan JSON atau CBOR, berikut ini menunjukkan format topik permintaan perintah.

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

Contoh kebijakan IAM

Sebelum Anda menggunakan operasi API ini, pastikan kebijakan IAM memberi wewenang kepada Anda untuk melakukan tindakan ini di perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan StartCommandExecution tindakan.

Dalam contoh ini, ganti:

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Untuk melihat daftar kunci kondisi yang didukungStartCommandExecution, lihat K unci Kondisi untuk AWS IoT di Panduan Pengguna IAM.

Dapatkan titik akhir bidang data khusus akun

Sebelum menjalankan perintah API, Anda harus mendapatkan URL titik akhir khusus akun untuk titik akhir. Jika Anda menggunakan titik akhir dual-stack (IPv4 dan IPv6), gunakan. iot:Data-ATS iot:JobsEndpoint hanya untuk IPv4. Misalnya, jika Anda menjalankan perintah ini:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

Ini mengembalikan URL titik akhir khusus akun seperti yang ditunjukkan pada respons sampel di bawah ini.

{
    "endpointAddress":
    "<account-specific-prefix>-ats.iot.<region>.api.com"
}

Mulai contoh eksekusi perintah (AWS CLI)

Contoh berikut menampilkan cara mulai menjalankan perintah menggunakan start-command-execution AWS CLI perintah.

Dalam contoh ini, ganti:

Menjalankan perintah ini mengembalikan ID eksekusi perintah. Anda dapat menggunakan ID ini untuk menanyakan status eksekusi perintah, detail, dan riwayat eksekusi perintah.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

Sebelum Anda menggunakan operasi API ini, pastikan kebijakan IAM Anda mengizinkan perangkat Anda untuk melakukan tindakan ini. Berikut ini menunjukkan contoh kebijakan yang mengizinkan perangkat Anda untuk melakukan tindakan. Untuk contoh kebijakan IAM tambahan yang memungkinkan izin pengguna untuk melakukan tindakan UpdateCommandExecution MQTT, lihat. Hubungkan dan publikasikan contoh kebijakan

Dalam contoh ini, ganti:

Contoh kebijakan IAM untuk ID klien MQTT

Kode berikut menunjukkan contoh kebijakan perangkat saat menggunakan ID klien MQTT.

Contoh kebijakan IAM untuk hal IoT

Kode berikut menunjukkan contoh kebijakan perangkat saat menggunakan AWS IoT sesuatu.

Setelah eksekusi perintah diterima pada topik permintaan, perangkat memproses perintah. Kemudian menggunakan UpdateCommandExecution API untuk memperbarui status dan hasil eksekusi perintah ke topik respons berikut.

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

Dalam contoh ini, <DeviceID> adalah pengidentifikasi unik perangkat target Anda, dan <execution-id> merupakan pengidentifikasi eksekusi perintah pada perangkat target. <PayloadFormat>Bisa berupa JSON atau CBOR.

$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

Perangkat melaporkan pembaruan ke status eksekusi

Perangkat Anda dapat menggunakan API untuk melaporkan salah satu pembaruan status berikut untuk eksekusi perintah. Untuk informasi selengkapnya tentang status ini, lihatStatus pelaksanaan perintah.

Untuk informasi selengkapnya tentang TIMED_OUT status, lihatNilai batas waktu dan status eksekusi TIMED_OUT.

Pertimbangan saat menggunakan UpdateCommandExecution API

Berikut ini adalah beberapa pertimbangan penting saat menggunakan UpdateCommandExecution API.

UpdateCommandExecutionContoh API

Kode berikut menunjukkan contoh bagaimana perangkat Anda dapat menggunakan UpdateCommandExecution API untuk melaporkan status eksekusi, statusReason bidang untuk memberikan informasi tambahan tentang status, dan bidang hasil untuk memberikan informasi tentang hasil eksekusi, seperti persentase baterai mobil dalam kasus ini.

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}

Anda dapat mengambil eksekusi perintah dari konsol menggunakan salah satu metode berikut.

Gunakan operasi API HTTP bidang GetCommandExecution AWS IoT Core kontrol untuk mengambil informasi tentang eksekusi perintah. Anda harus sudah menjalankan perintah ini menggunakan operasi StartCommandExecution API.

Contoh kebijakan IAM

Sebelum Anda menggunakan operasi API ini, pastikan kebijakan IAM memberi wewenang kepada Anda untuk melakukan tindakan ini di perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan GetCommandExecution tindakan.

Dalam contoh ini, ganti:

{
  "Effect": "Allow",
  "Action": [
      "iot:GetCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Ambil contoh eksekusi perintah

Contoh berikut menunjukkan cara mengambil informasi tentang perintah yang dieksekusi menggunakan start-command-execution AWS CLI perintah. Contoh berikut menunjukkan bagaimana Anda dapat mengambil informasi tentang perintah yang dijalankan untuk mematikan mode roda kemudi.

Dalam contoh ini, ganti:

aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <target-arn> \
    --include-result

Menjalankan perintah ini menghasilkan respons yang berisi informasi tentang ARN eksekusi perintah, status eksekusi, dan waktu ketika mulai dieksekusi, dan kapan selesai. Ini juga menyediakan statusReason objek yang berisi informasi tambahan tentang status. Untuk informasi selengkapnya tentang status yang berbeda dan alasan status, lihatStatus pelaksanaan perintah.

Kode berikut menunjukkan respons sampel dari permintaan API.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/myRegisteredThing",
    "status": "SUCCEEDED",
    "statusReason": {
        "reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED",
        "reasonDescription": "SUCCESS"
    },
    "result": {
        "sn": { "s": "ABC-001" },
        "digital": { "b": true }        
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "completedAt": "2024-03-23T00:50:10.095000-07:00"    
}

Anda dapat melihat semua eksekusi perintah dari konsol menggunakan salah satu metode berikut.

Gunakan operasi API HTTP bidang ListCommandExecutions AWS IoT Core kontrol untuk membuat daftar semua eksekusi perintah di akun Anda.

Contoh kebijakan IAM

Sebelum Anda menggunakan operasi API ini, pastikan kebijakan IAM memberi wewenang kepada Anda untuk melakukan tindakan ini di perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan ListCommandExecutions tindakan.

Dalam contoh ini, ganti:

{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

Daftar contoh eksekusi perintah

Contoh berikut menunjukkan kepada Anda cara membuat daftar eksekusi perintah di Anda Akun AWS.

Saat menjalankan perintah, Anda harus menentukan apakah akan memfilter daftar untuk menampilkan hanya eksekusi perintah yang dibuat untuk perangkat tertentu menggunakantargetArn, atau eksekusi untuk perintah tertentu yang ditentukan menggunakan. commandArn

Dalam contoh ini, ganti:

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<after>}' \
--sort-order "ASCENDING"

Menjalankan perintah ini menghasilkan respons yang berisi daftar eksekusi perintah yang Anda buat, dan waktu ketika eksekusi mulai dieksekusi, dan kapan selesai. Ini juga menyediakan informasi status, dan statusReason objek yang berisi informasi tambahan tentang status.

{
    "commandExecutions": [
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "TIMED_OUT",
            "createdAt": "2024-11-24T14:39:25.791000-08:00",
            "startedAt": "2024-11-24T14:39:25.791000-08:00"
        },
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "IN_PROGRESS",
            "createdAt": "2024-11-24T14:05:36.021000-08:00",
            "startedAt": "2024-11-24T14:05:36.021000-08:00"
        }
    ]
}

Untuk informasi selengkapnya tentang status yang berbeda dan alasan status, lihatStatus pelaksanaan perintah.

Sebelum Anda menggunakan operasi API ini, pastikan kebijakan IAM Anda mengizinkan perangkat Anda untuk melakukan tindakan ini. Berikut ini menunjukkan contoh kebijakan yang mengotorisasi perangkat Anda untuk melakukan tindakan tersebut.

Dalam contoh ini, ganti:

{
  "Effect": "Allow",
  "Action": [
      "iot:DeleteCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Contoh berikut menunjukkan cara menghapus perintah menggunakan delete-command AWS CLI perintah. Tergantung pada aplikasi Anda, ganti <execution-id> dengan pengenal untuk eksekusi perintah yang Anda hapus, dan <target-arn> dengan ARN perangkat target Anda.

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

Jika permintaan API berhasil, maka eksekusi perintah menghasilkan kode status 200. Anda dapat menggunakan GetCommandExecution API untuk memverifikasi bahwa eksekusi perintah tidak ada lagi di akun Anda.