Memulai dan memantau pelaksanaan perintah - AWS IoT Core
Mulai eksekusi perintahMemperbarui hasil pelaksanaan perintahAmbil eksekusi perintahMelihat pembaruan perintah menggunakan klien pengujian MQTTDaftar eksekusi perintah di Akun AWSHapus eksekusi perintah

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

Memulai dan memantau pelaksanaan perintah

Setelah membuat Command, mulai Eksekusi pada perangkat target. Perangkat memperbarui hasil dan menerbitkan status ke Topik yang dicadangkan MQTT. Ambil dan pantau status Eksekusi dari akun Anda.

Mulai dan pantau Perintah menggunakan AWS IoT konsol atau AWS CLI.

Mulai eksekusi perintah

penting

Anda bertanggung jawab penuh untuk menerapkan perintah dengan cara yang aman dan sesuai dengan hukum yang berlaku.

Sebelum memulai Eksekusi, pastikan:

  • Anda membuat Command di AWS IoT namespace dengan informasi Payload. Saat memulai Eksekusi, perangkat memproses instruksi Payload dan melakukan tindakan yang ditentukan. Lihat Buat sumber daya perintah untuk Pembuatan perintah.

  • Perangkat Anda berlangganan Topik untuk Perintah yang dicadangkan MQTT. Saat memulai Eksekusi, informasi Payload dipublikasikan ke permintaan MQTT yang dicadangkan ini Topik:

    <devices>dapat berupa klien Things atau MQTT. <DeviceID>adalah nama Thing atau Client ID. <PayloadFormat>Nilai yang didukung: JSON dan CBOR. Untuk informasi selengkapnya, lihat Topik perintah.

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

    Untuk non-JSON/CBOR<PayloadFormat>, gunakan format Topik Perintah ini:

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

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 menjalankan perintah dan melakukan tindakan yang ditentukan.

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 Connect device atau gunakan CreateThing. Temukan Hal yang ada dari Thing Hub atau gunakan 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. Didefinisikan dalam protokol MQTT, ini berisi karakter alfanumerik, garis bawah, atau tanda hubung. Setiap perangkat yang terhubung AWS IoT memerlukan ID Klien yang unik.

catatan

  • Untuk Hal-hal yang terdaftar, ID Klien dapat mencocokkan nama Thing.

  • Saat menargetkan ID Klien tertentu, perangkat harus terhubung AWS IoT menggunakan ID Klien tersebut untuk menerima Payload.

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

Timeout 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, Eksekusi akan habis dengan statusTIMED_OUT.

Default: 10 detik. Maksimal: 12 jam.

Nilai waktu habis dan status TIMED_OUT eksekusi

Cloud dan perangkat dapat melaporkan batas waktu.

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

Ini terjadi ketika:

  • Perangkat offline selama Eksekusi.

  • Perangkat gagal menyelesaikan Eksekusi dalam batas waktu.

  • Perangkat gagal melaporkan status dalam batas waktu.

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 perintah. AWS IoT Device Management 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.

catatan

Untuk memastikan bahwa Anda menggunakan fitur sesi persisten MQTT dengan benar, setel flag Clean Start ke nol. Untuk informasi selengkapnya, lihat Sesi persisten MQTT.

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

  1. Untuk menjalankan perintah yang telah Anda buat, pilih Run command.

  2. Tinjau informasi tentang perintah yang Anda buat, termasuk topik yang dicadangkan MQTT, dan parameter, jika berlaku.

    Untuk perintah dinamis, masukkan nilai parameter atau biarkan dengan default. Untuk parameter yang tidak memiliki nilai default, Anda harus memberikan nilai yang akan dikirim sebagai bagian dari eksekusi ini.

  3. Tentukan perangkat target untuk menerima dan menjalankan Perintah. Perangkat dapat ditentukan sebagai AWS IoT sesuatu jika telah terdaftar AWS IoT, atau menggunakan ID klien jika perangkat Anda belum terdaftar. Untuk informasi selengkapnya, lihat Pertimbangan perangkat target

  4. (Opsional) Konfigurasikan nilai batas waktu untuk perintah yang menentukan durasi yang Anda inginkan untuk menjalankan perintah sebelum waktu habis. Jika perintah Anda perlu berjalan lebih dari 60 menit, Anda mungkin harus meningkatkan waktu kedaluwarsa sesi persisten MQTT. Untuk informasi selengkapnya, lihat Pertimbangan batas waktu eksekusi perintah.

  5. Pilih Jalankan perintah.

Gunakan operasi API bidang data StartCommandExecutionHTTP 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 AWS IoT.

Jika perangkat Anda telah berlangganan topik permintaan perintah, StartCommandExecution API akan memublikasikan pesan payload ke topik tersebut. Muatan 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 bahwa kebijakan IAM Anda mengizinkan Anda untuk melakukan tindakan ini pada perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan StartCommandExecution tindakan.

Dalam contoh ini, ganti:

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

  • account-iddengan Akun AWS nomor Anda, seperti123456789012.

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

  • devicesdengan salah satu thing atau client tergantung pada apakah perangkat Anda telah terdaftar sebagai AWS IoT sesuatu, atau ditentukan sebagai klien MQTT.

  • device-iddengan Anda AWS IoT thing-name atauclient-id.

{
  "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 Kunci Kondisi untuk AWS IoT di Panduan Pengguna IAM.

Dapatkan titik akhir bidang data khusus akun

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

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

Ini mengembalikan URL endpoint khusus akun seperti yang ditunjukkan dalam respons sampel di bawah ini.

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

Mulai contoh eksekusi perintah (AWS CLI)

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

Dalam contoh ini, ganti:

  • <command-arn>dengan ARN untuk perintah yang ingin Anda jalankan. Anda dapat memperoleh informasi ini dari respons perintah create-command CLI. Misalnya, jika Anda menjalankan perintah untuk mengubah mode roda kemudi, gunakanarn:aws:iot:region:account-id:command/SetComfortSteeringMode.

  • <target-arn>dengan Thing ARN untuk perangkat target, yang bisa berupa IoT atau klien MQTT, yang ingin Anda jalankan perintahnya. Misalnya, jika Anda menjalankan perintah untuk perangkat targetmyRegisteredThing, gunakanarn:aws:iot:region:account-id:thing/myRegisteredThing.

  • <endpoint-url>dengan titik akhir khusus akun yang Anda perolehDapatkan titik akhir bidang data khusus akun, diawali oleh. https:// Misalnya, https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com.

  • (Opsional) Anda juga dapat menentukan parameter tambahanexecutionTimeoutSeconds,, saat melakukan operasi StartCommandExecution API. Bidang opsional ini menentukan waktu dalam detik di mana perangkat harus menyelesaikan menjalankan perintah. Secara default, nilainya adalah 10 detik. Ketika status eksekusi perintahCREATED, timer dimulai. Jika hasil eksekusi perintah tidak diterima sebelum timer kedaluwarsa, maka status secara otomatis berubah menjadiTIMED_OUT.

  • aws iot-jobs-data start-command-execution \
    --command-arn <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --execution-timeout-seconds 900

  • (Opsional) Untuk perintah dinamis, tentukan parameter dan nilainya yang akan digunakan untuk substitusi. Anda harus memberikan nilai untuk parameter yang tidak memiliki defaultValue yang ditetapkan pada pembuatan perintah. Jika parameter memiliki defaultValue, nilai parameter yang disediakan di sini diutamakan. Untuk parameter yang memiliki ValueConditions ditetapkan, nilai parameter yang disediakan di sini harus memenuhi kondisi.

    Berdasarkan contoh perintah Light_Power_Status dinamis:

  • aws iot-jobs-data start-command-execution \
    --command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status  \
    --target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \
    --endpoint <endpoint-url> \
    --execution-timeout-seconds 900 \
    --parameters "powerStatus={S=ON}"

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

catatan

Jika perintah telah usang, maka permintaan StartCommandExecution API akan gagal dengan pengecualian validasi. Untuk memperbaiki kesalahan ini, pertama-tama pulihkan perintah menggunakan UpdateCommand API, lalu lakukan StartCommandExecution permintaan.

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

Memperbarui hasil pelaksanaan perintah

Gunakan operasi API bidang data UpdateCommandExecution MQTT untuk memperbarui status atau hasil eksekusi perintah.

catatan

Sebelum Anda menggunakan API ini:

  • Perangkat Anda harus telah membuat koneksi MQTT dan berlangganan topik permintaan perintah dan respons. Untuk informasi selengkapnya, lihat Alur kerja perintah tingkat tinggi.

  • Anda harus sudah menjalankan perintah ini menggunakan operasi StartCommandExecution API.

Sebelum Anda menggunakan operasi API ini, pastikan bahwa kebijakan IAM Anda mengotorisasi 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. Connect dan publikasikan contoh kebijakan

Dalam contoh ini, ganti:

  • Regiondengan Anda AWS Region, sepertius-east-1.

  • AccountIDdengan Akun AWS nomor Anda, seperti123456789012.

  • ThingNamedengan nama AWS IoT barang Anda yang Anda targetkan eksekusi perintah, sepertimyRegisteredThing.

  • commands-request-topicdan commands-response-topic dengan nama-nama permintaan AWS IoT perintah dan topik tanggapan Anda. Untuk informasi selengkapnya, lihat Alur kerja perintah tingkat tinggi.

Contoh kebijakan IAM untuk ID klien MQTT

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

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:Publish",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Receive",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Connect",
      "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
    }
  ]
}

Contoh kebijakan IAM untuk hal IoT

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

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:Publish",
      "Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response"
    },
    {
      "Effect": "Allow",
      "Action": "iot:Receive",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Connect",
      "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
    }
  ]
}

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 pengenal unik perangkat target Anda, dan <execution-id> merupakan pengidentifikasi eksekusi perintah pada perangkat target. <PayloadFormat>Bisa JSON atau CBOR.

catatan

Jika Anda belum mendaftarkan perangkat AWS IoT, Anda dapat menggunakan ID klien sebagai pengenal, bukan nama benda.

$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 ke eksekusi perintah. Untuk informasi lebih lanjut tentang status ini, lihatStatus pelaksanaan perintah.

  • IN_PROGRESS: Ketika perangkat mulai menjalankan perintah, itu dapat memperbarui status keIN_PROGRESS.

  • SUCCEEDED: Ketika perangkat berhasil memproses perintah dan menyelesaikan menjalankannya, perangkat dapat mempublikasikan pesan ke topik respons sebagai. SUCCEEDED

  • FAILED: Jika perangkat gagal menjalankan perintah, perangkat dapat mempublikasikan pesan ke topik respons sebagaiFAILED.

  • REJECTED: Jika perangkat gagal menerima perintah, perangkat dapat mempublikasikan pesan ke topik respons sebagaiREJECTED.

  • TIMED_OUT: Status eksekusi perintah dapat berubah TIMED_OUT karena salah satu alasan berikut.

    • Hasil eksekusi perintah tidak diterima. Hal ini dapat terjadi karena eksekusi tidak selesai dalam durasi yang ditentukan, atau jika perangkat gagal mempublikasikan informasi status ke topik respons.

    • Perangkat melaporkan bahwa waktu habis terjadi ketika mencoba menjalankan perintah.

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

Pertimbangan saat menggunakan API UpdateCommandExecution

Berikut ini adalah beberapa pertimbangan penting saat menggunakan UpdateCommandExecution API.

  • Perangkat Anda dapat menggunakan statusReason objek opsional untuk memberikan informasi tambahan tentang eksekusi. Jika perangkat Anda menyediakan objek ini, reasonCode bidang objek diperlukan, tetapi reasonDescription bidangnya opsional.

  • Ketika perangkat Anda menggunakan statusReason objek, reasonCode harus menggunakan pola [A-Z0-9_-]+ dan tidak melebihi 64 karakter panjangnya. Jika Anda memberikanreasonDescription, pastikan bahwa itu tidak melebihi 1.024 karakter panjangnya. Itu dapat menggunakan karakter apa pun kecuali karakter kontrol seperti baris baru.

  • Perangkat Anda dapat menggunakan result objek opsional untuk memberikan informasi tentang hasil eksekusi perintah, seperti nilai pengembalian panggilan fungsi jarak jauh. Jika Anda memberikanresult, itu harus memerlukan setidaknya satu entri.

  • Di result bidang, Anda menentukan entri sebagai pasangan nilai kunci. Untuk setiap entri, Anda harus menentukan informasi tipe data sebagai string, boolean, atau biner. Tipe data string harus menggunakan kuncis, tipe data boolean menggunakan kuncib, dan tipe data biner harus menggunakan kuncibin. Pastikan bahwa kunci ini huruf kecil.

  • Jika Anda mengalami kesalahan saat menjalankan UpdateCommandExecution API, Anda dapat melihat kesalahan di grup AWSIoTLogsV2 log di Amazon CloudWatch. Untuk informasi tentang mengaktifkan logging dan melihat log, lihatKonfigurasikan AWS IoT logging.

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"
        }
    }
}

Ambil eksekusi perintah

Setelah Anda menjalankan perintah, Anda dapat mengambil informasi tentang eksekusi perintah dari AWS IoT konsol dan menggunakan. AWS CLI Anda dapat memperoleh informasi berikut.

catatan

Untuk mengambil status eksekusi perintah terbaru, perangkat Anda harus mempublikasikan informasi status ke topik respons menggunakan UpdateCommandExecution MQTT API, seperti yang dijelaskan di bawah ini. Sampai perangkat memublikasikan topik ini, GetCommandExecution API akan melaporkan status sebagai CREATED atauTIMED_OUT.

Setiap pelaksanaan perintah yang Anda buat akan memiliki:

  • ID Pelaksanaan, yang merupakan pengidentifikasi unik pelaksanaan perintah.

  • Status pelaksanaan perintah. Ketika Anda menjalankan perintah di perangkat target, pelaksanaan perintah memasuki status CREATED. Kemudian perintah dapat beralih ke status pelaksanaan perintah lain seperti yang dijelaskan di bawah ini.

  • Hasil eksekusi perintah.

  • ID Perintah unik dan perangkat target yang telah dibuatkan pelaksanaan.

  • Tanggal mulai, yang menunjukkan waktu ketika pelaksanaan perintah dibuat.

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

  • Dari halaman Command hub

    Buka halaman Command Hub AWS IoT konsol dan lakukan langkah-langkah ini.

    1. Pilih perintah yang Anda buat eksekusi pada perangkat target.

    2. Di halaman detail perintah, pada tab Riwayat perintah, Anda akan melihat eksekusi yang Anda buat. Pilih eksekusi yang ingin Anda ambil informasinya.

    3. Jika perangkat Anda menggunakan UpdateCommandExecution API untuk memberikan informasi hasil, Anda dapat menemukan informasi ini di tab Hasil di halaman ini.

  • Dari halaman Thing hub

    Jika Anda memilih AWS IoT sesuatu sebagai perangkat target saat menjalankan perintah, Anda dapat melihat detail eksekusi dari halaman Thing hub.

    1. Buka halaman Thing Hub di AWS IoT konsol dan pilih hal yang Anda buat eksekusi perintah.

    2. Di halaman detail hal, pada riwayat Perintah, Anda akan melihat eksekusi yang Anda buat. Pilih eksekusi yang ingin Anda ambil informasinya.

    3. Jika perangkat Anda menggunakan UpdateCommandExecution API untuk memberikan informasi hasil, Anda dapat menemukan informasi ini di tab Hasil di halaman ini.

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 bahwa kebijakan IAM Anda mengizinkan Anda untuk melakukan tindakan ini pada perangkat. Contoh berikut menunjukkan kebijakan IAM yang memungkinkan izin pengguna untuk melakukan GetCommandExecution tindakan.

Dalam contoh ini, ganti:

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

  • account-iddengan Akun AWS nomor Anda, seperti123456789012.

  • command-iddengan pengidentifikasi AWS IoT perintah unik Anda, sepertiLockDoor.

  • devicesdengan salah satu thing atau client tergantung pada apakah perangkat Anda telah terdaftar sebagai AWS IoT sesuatu, atau ditentukan sebagai klien MQTT.

  • device-iddengan Anda AWS IoT thing-name atauclient-id.

{
  "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 kepada Anda bagaimana untuk mengambil informasi tentang perintah yang dijalankan 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:

  • <execution-id>dengan pengidentifikasi untuk eksekusi perintah yang ingin Anda ambil informasinya.

  • <target-arn>dengan Amazon Resource Number (ARN) perangkat yang Anda targetkan eksekusi. Anda dapat memperoleh informasi ini dari respons perintah start-command-execution CLI.

  • Secara opsional, jika perangkat Anda menggunakan UpdateCommandExection API untuk memberikan hasil eksekusi, Anda dapat menentukan apakah akan menyertakan hasil eksekusi perintah dalam respons GetCommandExecution API menggunakan GetCommandExecution API.

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 dari eksekusi perintah, status eksekusi, dan waktu ketika mulai mengeksekusi, dan ketika selesai. Ini juga menyediakan statusReason objek yang berisi informasi tambahan tentang status. Untuk informasi selengkapnya tentang status dan alasan status yang berbeda, lihatStatus pelaksanaan perintah.

Kode berikut menunjukkan respons sampel dari permintaan API.

catatan

completedAtBidang dalam respons eksekusi sesuai dengan waktu ketika perangkat melaporkan status terminal ke cloud. Dalam hal TIMED_OUT status, bidang ini akan disetel hanya ketika perangkat melaporkan waktu habis. Ketika TIMED_OUT status diatur oleh cloud, TIMED_OUT status tidak diperbarui. Untuk informasi lebih lanjut tentang perilaku time out, lihatPertimbangan batas waktu eksekusi perintah.

{
    "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"    
}

Melihat pembaruan perintah menggunakan klien pengujian MQTT

Anda dapat menggunakan klien pengujian MQTT untuk melihat pertukaran pesan melalui MQTT saat menggunakan fitur perintah. Setelah perangkat Anda membuat koneksi MQTT dengan AWS IoT, Anda dapat membuat perintah, menentukan payload, dan kemudian menjalankannya di perangkat. Saat Anda menjalankan perintah, jika perangkat Anda berlangganan topik permintaan cadangan MQTT untuk perintah, ia akan melihat pesan payload yang dipublikasikan ke topik ini.

Perangkat kemudian menerima instruksi muatan dan melakukan operasi yang ditentukan pada AWS IoT perangkat. Kemudian menggunakan UpdateCommandExecution API untuk mempublikasikan hasil eksekusi perintah dan informasi status ke topik respons cadangan MQTT untuk perintah. AWS IoT Device Management mendengarkan pembaruan tentang topik respons dan menyimpan informasi yang diperbarui dan menerbitkan log ke dan AWS CloudTrail Amazon. CloudWatch Anda kemudian dapat mengambil informasi eksekusi perintah terbaru dari konsol atau dengan menggunakan GetCommandExecution API.

Langkah-langkah berikut menunjukkan cara menggunakan klien pengujian MQTT untuk mengamati pesan.

  1. Buka klien pengujian MQTT di konsol. AWS IoT

  2. Pada tab Berlangganan, masukkan topik berikut lalu pilih Berlangganan, di mana <thingId> nama perangkat yang telah Anda daftarkan AWS IoT.

    catatan

    Anda dapat menemukan nama benda untuk perangkat Anda dari halaman Thing Hub AWS IoT konsol. Jika Anda belum mendaftarkan perangkat sebagai sesuatu, Anda dapat mendaftarkan perangkat saat menyambungkan ke AWS IoT dari halaman Connect device.

    $aws/commands/things/<thingId>/executions/+/request

  3. (Opsional) Pada tab Berlangganan, Anda juga dapat memasukkan topik berikut dan memilih Berlangganan.

    $aws/commands/things/+/executions/+/response/accepted/json
$aws/commands/things/+/executions/+/response/rejected/json

  4. Saat Anda memulai eksekusi perintah, payload pesan akan dikirim ke perangkat menggunakan topik permintaan yang telah dilanggani perangkat,. $aws/commands/things/<thingId>/executions/+/request Di klien pengujian MQTT, Anda akan melihat payload perintah yang berisi instruksi untuk perangkat untuk memproses perintah.

  5. Setelah perangkat mulai menjalankan perintah, perangkat dapat mempublikasikan pembaruan status ke topik respons cadangan MQTT berikut untuk perintah.

    $aws/commands/<devices>/<device-id>/executions/<executionId>/response/json

    Misalnya, pertimbangkan perintah yang Anda jalankan untuk menyalakan AC mobil Anda untuk mengurangi suhu ke nilai yang diinginkan. JSON berikut menunjukkan contoh pesan bahwa kendaraan dipublikasikan ke topik respons yang menunjukkan bahwa ia gagal menjalankan perintah.

    {
  "deviceId": "My_Car",
  "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
  "status": "FAILED",
  "statusReason": {
    "reasonCode": "CAR_LOW_ON_BATTERY",
    "reasonDescription": "Car battery is lower than 5 percent"
  }
}

    Dalam hal ini, Anda dapat mengisi baterai mobil Anda dan kemudian menjalankan perintah lagi.

Daftar eksekusi perintah di Akun AWS

Setelah Anda menjalankan perintah, Anda dapat mengambil informasi tentang eksekusi perintah dari AWS IoT konsol dan menggunakan. AWS CLI Anda dapat memperoleh informasi berikut.

  • ID Pelaksanaan, yang merupakan pengidentifikasi unik pelaksanaan perintah.

  • Status pelaksanaan perintah. Ketika Anda menjalankan perintah di perangkat target, pelaksanaan perintah memasuki status CREATED. Kemudian perintah dapat beralih ke status pelaksanaan perintah lain seperti yang dijelaskan di bawah ini.

  • ID Perintah unik dan perangkat target yang telah dibuatkan pelaksanaan.

  • Tanggal mulai, yang menunjukkan waktu ketika pelaksanaan perintah dibuat.

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

  • Dari halaman Command hub

    Buka halaman Command Hub AWS IoT konsol dan lakukan langkah-langkah ini.

    1. Pilih perintah yang Anda buat eksekusi pada perangkat target.

    2. Di halaman detail perintah, buka tab Riwayat perintah, dan Anda akan melihat daftar eksekusi yang Anda buat.

  • Dari halaman Thing hub

    Jika Anda memilih AWS IoT sesuatu sebagai perangkat target saat menjalankan perintah, dan membuat beberapa eksekusi perintah untuk satu perangkat, Anda dapat melihat eksekusi perangkat dari halaman Thing hub.

    1. Buka halaman Thing Hub di AWS IoT konsol dan pilih hal yang Anda buat eksekusi.

    2. Di halaman detail hal, pada riwayat Perintah, Anda akan melihat daftar eksekusi yang Anda buat untuk perangkat.

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

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 ListCommandExecutions tindakan.

Dalam contoh ini, ganti:

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

  • account-iddengan Akun AWS nomor Anda, seperti123456789012.

  • command-iddengan pengidentifikasi AWS IoT perintah unik Anda, sepertiLockDoor.

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

Contoh eksekusi perintah daftar

Contoh berikut menunjukkan kepada Anda cara membuat daftar eksekusi perintah di file 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 perintah. commandArn

Dalam contoh ini, ganti:

  • <target-arn>dengan Amazon Resource Number (ARN) perangkat yang Anda targetkan eksekusi, seperti. arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f

  • <target-arn>dengan Amazon Resource Number (ARN) perangkat yang Anda targetkan eksekusi, seperti. arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f

  • <after>dengan waktu setelah itu Anda ingin membuat daftar eksekusi yang dibuat, misalnya,2024-11-01T03:00.

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 dijalankan, dan ketika 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 dan alasan status yang berbeda, lihatStatus pelaksanaan perintah.

Hapus eksekusi perintah

Jika Anda tidak lagi ingin menggunakan eksekusi perintah, Anda dapat menghapusnya secara permanen dari akun Anda.

catatan

  • Eksekusi perintah dapat dihapus hanya jika telah memasuki status terminal, sepertiSUCCEEDED,FAILED, atauREJECTED.

  • Operasi ini dapat dilakukan hanya dengan menggunakan AWS IoT Core API atau AWS CLI. Ini tidak tersedia dari konsol.

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

Dalam contoh ini, ganti:

  • Regiondengan Anda AWS Region, sepertius-east-1.

  • AccountIDdengan Akun AWS nomor Anda, seperti123456789012.

  • CommandIDdengan pengidentifikasi perintah yang ingin Anda hapus eksekusi.

  • devicesdengan salah satu thing atau client tergantung pada apakah perangkat Anda telah terdaftar sebagai AWS IoT sesuatu, atau ditentukan sebagai klien MQTT.

  • device-iddengan Anda AWS IoT thing-name atauclient-id.

{
  "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. Bergantung 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.