Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Konsep dan status perintah
Gunakan AWS IoT Perintah untuk mengirim instruksi dari cloud ke perangkat yang terhubung. Untuk menggunakan fitur ini:
1. Buat perintah dengan muatan yang berisi konfigurasi yang diperlukan untuk berjalan di perangkat.
1. Tentukan perangkat target yang akan menerima muatan dan melakukan tindakan.
1. Jalankan perintah pada perangkat target dan ambil informasi status. Untuk memecahkan masalah, lihat CloudWatch log.
Untuk informasi selengkapnya tentang alur kerja ini, lihat[Alur kerja perintah tingkat tinggi](iot-remote-command-workflow.md).
**Topics**
+ [Perintah konsep kunci](#iot-command-concepts)
+ [Status perintah](#iot-command-states)
+ [Status pelaksanaan perintah](#iot-command-execution-status)
## Perintah konsep kunci
Konsep kunci berikut membantu Anda memahami fitur Perintah. Ketentuan digunakan secara konsisten di seluruh dokumentasi ini:
+ *Command* - Template yang dapat digunakan kembali yang mendefinisikan instruksi perangkat
+ *Eksekusi* - Sebuah instance dari perintah yang berjalan pada perangkat
+ *Nama benda* - Pengidentifikasi untuk perangkat yang terdaftar di registri IoT
+ *ID Klien* - Pengidentifikasi MQTT untuk perangkat yang tidak terdaftar
+ *Payload* - Data instruksi yang dikirim ke perangkat
+ *Topik* - Saluran MQTT untuk komunikasi perintah
**Commands**
Perintah adalah instruksi yang dikirim dari cloud ke perangkat IoT Anda sebagai pesan MQTT. Setelah menerima muatan, perangkat memproses instruksi dan mengambil tindakan yang sesuai, seperti memodifikasi pengaturan konfigurasi, mentransmisikan pembacaan sensor, atau mengunggah log. Perangkat kemudian mengembalikan hasil ke cloud, memungkinkan pemantauan dan kontrol jarak jauh.
**Namespace**
Saat membuat perintah, tentukan namespace-nya. Untuk AWS IoT Device Management perintah, gunakan `AWS-IoT` namespace default dan berikan payload atau payloadTemplate. Untuk AWS IoT FleetWise perintah, gunakan `AWS-IoT-FleetWise` namespace. Untuk informasi selengkapnya, lihat [Perintah jarak jauh](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) di *Panduan AWS IoT FleetWise Pengembang*.
**Muatan**
Saat membuat perintah, berikan muatan statis yang menentukan tindakan yang harus dilakukan perangkat. Muatan dapat menggunakan format apa pun yang didukung. Untuk memastikan perangkat menafsirkan muatan dengan benar, sebaiknya tentukan jenis format payload. Perangkat yang menggunakan MQTT5 protokol dapat mengikuti standar MQTT untuk mengidentifikasi format. Indikator format untuk JSON atau CBOR tersedia dalam topik permintaan perintah.
**Templat muatan**
Template payload mendefinisikan payload perintah dengan placeholder yang menghasilkan muatan berbeda saat runtime berdasarkan nilai parameter yang Anda berikan. Misalnya, alih-alih membuat muatan terpisah untuk nilai suhu yang berbeda, buat satu templat dengan placeholder suhu dan tentukan nilainya selama eksekusi. Ini menghilangkan pemeliharaan beberapa muatan serupa.
**Perangkat target**
Untuk menjalankan perintah, tentukan perangkat target menggunakan nama benda (untuk perangkat yang terdaftar AWS IoT) atau ID klien MQTT (untuk perangkat yang tidak terdaftar). ID klien adalah pengidentifikasi unik yang didefinisikan dalam [MQTT](mqtt.md) protokol yang digunakan untuk menghubungkan perangkat ke AWS IoT. Lihat perinciannya di [Pertimbangan perangkat target](iot-remote-command-execution-start-monitor.md#iot-command-execution-target).
**Topik perintah**
Sebelum menjalankan perintah, perangkat harus berlangganan topik permintaan perintah. Saat Anda menjalankan perintah, muatan dikirim ke perangkat pada topik ini. Setelah eksekusi, perangkat mempublikasikan hasil dan status ke topik respons perintah. Untuk informasi selengkapnya, lihat [Topik perintah](reserved-topics.md#reserved-topics-commands).
**Eksekusi perintah**
Eksekusi adalah contoh dari perintah yang berjalan pada perangkat target. Saat Anda memulai eksekusi, payload dikirimkan ke perangkat dan ID eksekusi unik dihasilkan. Perangkat menjalankan perintah dan melaporkan kemajuan ke AWS IoT. Logika sisi perangkat menentukan perilaku eksekusi dan pelaporan status ke topik yang dicadangkan.
### Kondisi nilai parameter
Saat membuat perintah dengan templat payload, tentukan kondisi nilai untuk memvalidasi nilai parameter sebelum eksekusi. Kondisi nilai memastikan parameter memenuhi persyaratan, mencegah eksekusi yang tidak valid.
**Operator yang didukung berdasarkan [CommandParameterValue](https://docs.aws.amazon.com//iot/latest/apireference/API_CommandParameterValue.html)jenis**
**Jenis numerik (INTEGER, LONG, DOUBLE, UNSIGNEDLONG)**
+ `EQUALS`- Nilai harus sama dengan angka yang ditentukan
+ `NOT_EQUALS`- Nilai tidak boleh sama dengan angka yang ditentukan
+ `GREATER_THAN`- Nilai harus lebih besar dari angka yang ditentukan
+ `GREATER_THAN_EQUALS`- Nilai harus lebih besar dari atau sama dengan angka yang ditentukan
+ `LESS_THAN`- Nilai harus kurang dari angka yang ditentukan
+ `LESS_THAN_EQUALS`- Nilai harus kurang dari atau sama dengan angka yang ditentukan
+ `IN_RANGE`- Nilai harus dalam kisaran yang ditentukan (inklusif)
+ `NOT_IN_RANGE`- Nilai harus berada di luar rentang yang ditentukan (inklusif)
+ `IN_SET`- Nilai harus cocok dengan salah satu angka yang ditentukan
+ `NOT_IN_SET`- Nilai tidak boleh cocok dengan nomor yang ditentukan
**Jenis string (STRING)**
+ `EQUALS`- Nilai harus sama dengan string yang ditentukan
+ `NOT_EQUALS`- Nilai tidak harus sama dengan string yang ditentukan
+ `IN_SET`- Nilai harus cocok dengan salah satu string yang ditentukan
+ `NOT_IN_SET`- Nilai tidak boleh cocok dengan string yang ditentukan
**Jenis Boolean**
+ Kondisi nilai tidak didukung
**Tipe biner**
+ Kondisi nilai tidak didukung
**Contoh: Perintah kontrol suhu**
```
{
"commandId": "SetTemperature",
"namespace": "AWS-IoT",
"payloadTemplate": "{\"temperature\": \"${aws:iot:commandexecution::parameter:temperature}\"}",
"parameters": [
{
"name": "temperature",
"type": "INTEGER",
"valueConditions": [
{
"comparisonOperator": "IN_RANGE",
"operand": {
"numberRange": {
"min": "60",
"max": "80"
}
}
}
]
}
]
}
```
Dalam contoh ini, `temperature` parameter harus antara 60 dan 80 (inklusif). Permintaan eksekusi dengan nilai di luar rentang ini gagal validasi.
**catatan**
[Kondisi nilai dievaluasi saat pemanggilan API. StartCommandExecution ](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartCommandExecution.html) Validasi yang gagal mengembalikan kesalahan dan mencegah pembuatan eksekusi.
### Prioritas dan evaluasi nilai parameter
Saat memulai eksekusi perintah dengan templat payload, nilai parameter diselesaikan menggunakan prioritas berikut:
1. **Parameter permintaan eksekusi** - Nilai yang disediakan dalam `StartCommandExecution` permintaan mengambil prioritas tertinggi
1. **Nilai default perintah** - Jika parameter tidak disediakan dalam permintaan eksekusi, parameter `defaultValue` digunakan
1. **Tidak ada nilai** - Jika tidak ada yang disediakan, eksekusi gagal sebagai parameter yang diperlukan untuk menghasilkan permintaan eksekusi
Kondisi nilai dievaluasi pada nilai parameter akhir yang diturunkan di atas pada prioritas dan sebelum pembuatan eksekusi. Jika validasi gagal, permintaan eksekusi mengembalikan kesalahan.
**Contoh: SetTemperature perintah dengan `defaultValue`**
```
{
"parameters": [
{
"name": "temperature",
"type": "INTEGER",
"defaultValue": {"I": 72},
"valueConditions": [
{
"comparisonOperator": "IN_RANGE",
"operand": {"numberRange": {"min": "60", "max": "80"}}
}
]
}
]
}
```
Saat memulai eksekusi:
+ Jika Anda memberikan `"temperature": {"I": 75}` dalam permintaan, 75 digunakan
+ Jika Anda menghilangkan parameter suhu, nilai default 72 digunakan
+ Kedua nilai divalidasi terhadap kondisi rentang [60,80]
## Status perintah
*Perintah dalam Anda Akun AWS dapat berada di salah satu dari tiga status: *Tersedia*, Usang, atau *Penghapusan tertunda*.*
**Available**
Setelah pembuatan berhasil, perintah berada dalam status Tersedia dan dapat dieksekusi pada perangkat.
**Usang**
Tandai perintah untuk penghentian saat tidak lagi diperlukan. Perintah yang tidak digunakan lagi tidak dapat memulai eksekusi baru, tetapi eksekusi yang tertunda terus selesai. Untuk mengaktifkan eksekusi baru, kembalikan perintah ke status Tersedia.
**Penghapusan yang tertunda**
Ketika Anda menandai perintah untuk penghapusan, itu dihapus secara otomatis jika tidak digunakan lagi lebih lama dari batas waktu maksimum (default: 12 jam). Tindakan ini bersifat permanen. Jika tidak digunakan lagi atau tidak digunakan lagi kurang dari batas waktu, perintah memasuki status penghapusan Tertunda dan dihapus setelah batas waktu berakhir.
## Status pelaksanaan perintah
Saat Anda memulai eksekusi pada perangkat target, ia memasuki `CREATED` status dan dapat bertransisi ke status lain berdasarkan laporan perangkat. Anda dapat mengambil informasi status dan melacak eksekusi.
**catatan**
Anda dapat menjalankan beberapa perintah secara bersamaan di perangkat. Gunakan kontrol konkurensi untuk membatasi eksekusi per perangkat dan mencegah kelebihan beban. Untuk eksekusi bersamaan maksimum per perangkat, lihat [AWS IoT Device Management perintah](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits) kuota.
Tabel berikut menunjukkan status eksekusi dan transisinya berdasarkan progres eksekusi.
**Status eksekusi perintah dan sumber**
| Status pelaksanaan perintah | Diprakarsai oleh perangkat/cloud? | Eksekusi terminal? | Transisi status yang diizinkan |
| --- | --- | --- | --- |
| CREATED | Cloud | Tidak | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/iot-remote-command-concepts.html) |
| IN\$1PROGRESS | Perangkat | Tidak | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/iot-remote-command-concepts.html) |
| TIMED\$1OUT | Perangkat dan cloud | Tidak | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/iot-remote-command-concepts.html) |
| SUCCEEDED | Perangkat | Ya | Tidak berlaku |
| FAILED | Perangkat | Ya | Tidak berlaku |
| REJECTED | Perangkat | Ya | Tidak berlaku |
Perangkat dapat mempublikasikan status dan pembaruan hasil kapan saja menggunakan perintah yang dicadangkan topik MQTT. Untuk memberikan konteks tambahan, perangkat dapat menggunakan `reasonCode` dan `reasonDescription` bidang dalam `statusReason` objek.
Diagram berikut menunjukkan transisi status eksekusi.
![\[Gambar yang menunjukkan bagaimana transisi status eksekusi perintah antara berbagai status.\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/images/command-execution-status-transitions.png)
**catatan**
Ketika AWS IoT mendeteksi tidak ada respons perangkat dalam periode batas waktu, itu ditetapkan `TIMED_OUT` sebagai status sementara yang memungkinkan percobaan ulang dan perubahan status. Jika perangkat Anda melaporkan secara eksplisit`TIMED_OUT`, ini menjadi status terminal tanpa transisi lebih lanjut. Untuk informasi selengkapnya, lihat [Eksekusi perintah non-terminal](#iot-command-execution-status-nonterminal).
Bagian berikut menjelaskan eksekusi terminal dan non-terminal dan statusnya.
**Topics**
+ [Eksekusi perintah non-terminal](#iot-command-execution-status-nonterminal)
+ [Eksekusi perintah terminal](#iot-command-execution-status-terminal)
### Eksekusi perintah non-terminal
Eksekusi adalah non-terminal jika dapat menerima pembaruan dari perangkat. *Eksekusi non-terminal dianggap Aktif.* Status berikut adalah non-terminal:
+
**CREATED**
Saat Anda memulai eksekusi dari AWS IoT konsol atau menggunakan `StartCommandExecution` API, permintaan yang berhasil mengubah status menjadi`CREATED`. Dari status ini, eksekusi dapat beralih ke status non-terminal atau terminal lainnya.
+
**IN\$1PROGRESS**
Setelah menerima muatan, perangkat dapat mulai menjalankan instruksi dan melakukan tindakan yang ditentukan. Saat mengeksekusi, perangkat dapat mempublikasikan tanggapan terhadap topik respons perintah dan memperbarui status ke`IN_PROGRESS`. Dari`IN_PROGRESS`, eksekusi dapat bertransisi ke status terminal atau non-terminal kecuali. `CREATED`
**catatan**
`UpdateCommandExecution`API dapat dipanggil beberapa kali dengan `IN_PROGRESS` status. Tentukan detail eksekusi tambahan menggunakan `statusReason` objek.
+
**TIMED\$1OUT**
Baik cloud dan perangkat dapat memicu status ini. Eksekusi dalam `CREATED` atau `IN_PROGRESS` status dapat berubah menjadi karena `TIMED_OUT` alasan berikut:
+ Setelah mengirim perintah, timer dimulai. Jika perangkat tidak merespons dalam durasi yang ditentukan, cloud akan mengubah statusnya`TIMED_OUT`. Dalam hal ini, eksekusi non-terminal.
+ Perangkat dapat mengganti status ke status terminal apa pun atau melaporkan batas waktu dan menyetel status ke. `TIMED_OUT` Dalam hal ini, status tetap ada`TIMED_OUT`, tetapi bidang `StatusReason` objek berubah berdasarkan informasi perangkat. Eksekusi menjadi terminal.
Untuk informasi selengkapnya, lihat [Nilai waktu habis dan status `TIMED_OUT` eksekusi](iot-remote-command-execution-start-monitor.md#iot-command-execution-timeout-status).
### Eksekusi perintah terminal
Eksekusi menjadi terminal ketika tidak lagi menerima pembaruan dari perangkat. Status berikut adalah terminal. Eksekusi dapat bertransisi ke status terminal dari status non-terminal apa pun:`CREATED`,, `IN_PROGRESS` atau. `TIMED_OUT`
+
**SUCCEEDED**
Jika perangkat berhasil menyelesaikan eksekusi, perangkat dapat mempublikasikan respons terhadap topik respons perintah dan memperbarui status ke`SUCCEEDED`.
+
**FAILED**
Ketika perangkat gagal menyelesaikan eksekusi, perangkat dapat mempublikasikan respons terhadap topik respons perintah dan memperbarui status ke`FAILED`. Gunakan `reasonCode` dan `reasonDescription` bidang di `statusReason` objek, atau CloudWatch log, untuk memecahkan masalah kegagalan.
+
**MENOLAK**
Ketika perangkat menerima permintaan yang tidak valid atau tidak kompatibel, perangkat dapat memanggil API dengan status. `UpdateCommandExecution` `REJECTED` Gunakan `reasonDescription` bidang `reasonCode` dan di `statusReason` objek, atau CloudWatch log, untuk memecahkan masalah.