Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Tutorial: Menginstal Device SDK dan menjalankan aplikasi sampel untuk Device Shadows
Bagian ini menunjukkan bagaimana Anda dapat menginstal perangkat lunak yang diperlukan dan AWS IoT Device SDK untuk Python dan menjalankan `shadow.py` aplikasi sampel untuk mengedit dokumen Shadow dan mengontrol status bayangan.
**Dalam tutorial ini, Anda akan belajar cara:**
+ Gunakan perangkat lunak yang diinstal dan AWS IoT Device SDK untuk Python untuk menjalankan aplikasi sampel.
+ Pelajari cara memasukkan nilai menggunakan aplikasi sampel akan menerbitkan nilai yang diinginkan di AWS IoT konsol.
+ Tinjau aplikasi `shadow.py` sampel dan cara menggunakan protokol MQTT untuk memperbarui status bayangan.
**Sebelum Anda menjalankan tutorial ini:**
Anda harus menyiapkan Akun AWS, mengonfigurasi perangkat Raspberry Pi Anda, dan membuat AWS IoT hal dan kebijakan yang memberikan izin perangkat untuk mempublikasikan dan berlangganan topik yang dicadangkan MQTT dari layanan Device Shadow. Untuk informasi selengkapnya, lihat [Tutorial: Mempersiapkan Raspberry Pi Anda untuk menjalankan aplikasi bayangan](create-resources-shadow.md).
Anda juga harus menginstal Git, Python, dan AWS IoT Device SDK untuk Python. Tutorial ini dibangun di atas konsep yang disajikan dalam tutorial[Connect Raspberry Pi atau perangkat lain](connecting-to-existing-device.md). Jika Anda belum mencoba tutorial itu, kami sarankan Anda mengikuti langkah-langkah yang dijelaskan dalam tutorial itu untuk menginstal file sertifikat dan Device SDK dan kemudian kembali ke tutorial ini untuk menjalankan aplikasi `shadow.py` sampel.
**Topics**
+ [Langkah 1: Jalankan aplikasi sampel shadow.py](#run-sample-application-shadows)
+ [Langkah 2: Tinjau aplikasi contoh SDK Perangkat shadow.py](#review-shadow-sample-code)
+ [Langkah 3: Memecahkan masalah dengan aplikasi sampel `shadow.py`](#shadow-sample-app-troubleshoot)
+ [Langkah 4: Tinjau hasil dan langkah selanjutnya](#sample-app-shadow-review)
Tutorial ini membutuhkan waktu sekitar 20 menit untuk menyelesaikannya.
## Langkah 1: Jalankan aplikasi sampel shadow.py
Sebelum menjalankan aplikasi `shadow.py` sampel, Anda memerlukan informasi berikut selain nama dan lokasi file sertifikat yang Anda instal.
**Nilai parameter aplikasi**
| Parameter | Di mana menemukan nilainya |
| --- | --- |
| your-iot-thing-name | Nama AWS IoT benda yang Anda buat sebelumnya[Langkah 2: Buat sumber daya benda dan lampirkan kebijakan ke benda itu](shadow-provision-cloud.md#create-thing-shadow). Untuk menemukan nilai ini, di [AWS IoT konsol](https://console.aws.amazon.com/iot/home), pilih **Kelola**, lalu pilih **Things**. |
| your-iot-endpoint | *your-iot-endpoint*Nilai memiliki format:`endpoint_id-ats.iot.region.amazonaws.com`, misalnya,`a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com`. Untuk menemukan nilai ini: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/iot/latest/developerguide/lightbulb-shadow-application.html) |
**Instal dan jalankan aplikasi sampel**
1. Arahkan ke direktori aplikasi contoh.
```
cd ~/aws-iot-device-sdk-python-v2/samples/service-clients
```
1. Di jendela baris perintah, ganti *your-iot-endpoint* dan *your-iot-thing-name* seperti yang ditunjukkan dan jalankan perintah ini.
```
python3 shadow.py --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint --thing_name your-iot-thing-name
```
1. Perhatikan bahwa aplikasi sampel:
1. Terhubung ke layanan AWS IoT untuk akun Anda.
1. Berlangganan `Delta` acara dan `Update` dan `Get` tanggapan.
1. Meminta Anda untuk memasukkan nilai yang diinginkan di terminal.
1. Menampilkan output yang mirip dengan berikut ini:
```
Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'...
Connected!
Subscribing to Delta events...
Subscribing to Update responses...
Subscribing to Get responses...
Requesting current shadow state...
Launching thread to read user input...
Finished getting initial shadow state.
Shadow contains reported value 'off'.
Enter desired value:
```
**catatan**
Jika Anda mengalami masalah dalam menjalankan aplikasi `shadow.py` sampel, tinjau[Langkah 3: Memecahkan masalah dengan aplikasi sampel `shadow.py`](#shadow-sample-app-troubleshoot). Untuk mendapatkan informasi tambahan yang mungkin membantu Anda memperbaiki masalah, tambahkan `--verbosity debug` parameter ke baris perintah sehingga aplikasi sampel menampilkan pesan terperinci tentang apa yang dilakukannya.
**Masukkan nilai dan amati pembaruan dalam dokumen Shadow**
Anda dapat memasukkan nilai di terminal untuk menentukan `desired` nilai, yang juga memperbarui `reported` nilai. Katakanlah Anda memasukkan warna `yellow` di terminal. `reported`Nilai juga diperbarui ke warna`yellow`. Berikut ini menunjukkan pesan yang ditampilkan di terminal:
```
Enter desired value:
yellow
Changed local shadow value to 'yellow'.
Updating reported shadow value to 'yellow'...
Update request published.
Finished updating reported shadow value to 'yellow'.
```
Saat Anda mempublikasikan permintaan pembaruan ini, AWS IoT buat bayangan klasik default untuk sumber daya benda. Anda dapat mengamati permintaan pembaruan yang Anda terbitkan ke `reported` dan `desired` nilai di AWS IoT konsol dengan melihat dokumen Shadow untuk sumber daya benda yang Anda buat (misalnya,`My_light_bulb`). Untuk melihat pembaruan dalam dokumen Shadow:
1. Di AWS IoT konsol, pilih **Kelola** dan kemudian pilih **Things**.
1. Dalam daftar hal-hal yang ditampilkan, pilih hal yang Anda buat, pilih **Shadows**, dan kemudian pilih **Classic Shadow**.
Dokumen Shadow akan terlihat mirip dengan berikut ini, menunjukkan `reported` dan `desired` nilai yang disetel ke warna`yellow`. Anda melihat nilai-nilai ini di bagian **Shadow state** dari dokumen.
```
{
"desired": {
"welcome": "aws-iot",
"color": "yellow"
},
"reported": {
"welcome": "aws-iot",
"color": "yellow"
}
}
```
Anda juga melihat bagian **Metadata** yang berisi informasi stempel waktu dan nomor versi permintaan.
Anda dapat menggunakan versi dokumen negara untuk memastikan Anda memperbarui versi terbaru dari dokumen Shadow perangkat. Jika Anda mengirim permintaan pembaruan lain, nomor versi bertambah sebesar 1. Saat Anda menyediakan versi dengan permintaan pembaruan, layanan menolak permintaan dengan kode respons konflik HTTP 409 jika versi dokumen status saat ini tidak cocok dengan versi yang disediakan.
```
{
"metadata": {
"desired": {
"welcome": {
"timestamp": 1620156892
},
"color": {
"timestamp": 1620156893
}
},
"reported": {
"welcome": {
"timestamp": 1620156892
},
"color": {
"timestamp": 1620156893
}
}
},
"version": 10
}
```
Untuk mempelajari lebih lanjut tentang dokumen Shadow dan mengamati perubahan pada informasi negara, lanjutkan ke tutorial berikutnya [Tutorial: Berinteraksi dengan Device Shadow menggunakan aplikasi sampel dan klien pengujian MQTT](interact-lights-device-shadows.md) seperti yang dijelaskan di [Langkah 4: Tinjau hasil dan langkah selanjutnya](#sample-app-shadow-review) bagian tutorial ini. Secara opsional, Anda juga dapat mempelajari tentang kode `shadow.py` sampel dan cara menggunakan protokol MQTT di bagian berikut.
## Langkah 2: Tinjau aplikasi contoh SDK Perangkat shadow.py
Bagian ini mengulas `shadow.py` contoh aplikasi dari **AWS IoT Device SDK v2 untuk Python** yang digunakan dalam tutorial ini. Di sini, kita akan meninjau bagaimana terhubung AWS IoT Core dengan menggunakan MQTT dan MQTT melalui protokol WSS. Pustaka [runtime AWS umum (AWS-CRT)](https://github.com/awslabs/aws-crt-python#aws-crt-python) menyediakan dukungan protokol komunikasi tingkat rendah dan disertakan dengan AWS IoT Device SDK v2 untuk Python.
Sementara tutorial ini menggunakan MQTT dan MQTT melalui WSS, AWS IoT mendukung perangkat yang menerbitkan permintaan HTTPS. Untuk contoh program Python yang mengirim pesan HTTP dari perangkat, lihat [contoh kode HTTPS menggunakan pustaka](http.md#codeexample) Python. `requests`
Untuk informasi tentang bagaimana Anda dapat membuat keputusan berdasarkan informasi tentang protokol mana yang akan digunakan untuk komunikasi perangkat Anda, tinjau[Memilih protokol aplikasi untuk komunikasi perangkat Anda](protocols.md#protocol-selection).
**MQTT**
`shadow.py`Contoh panggilan `mtls_from_path` (ditampilkan di sini) di [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py)untuk membuat koneksi dengan AWS IoT Core dengan menggunakan protokol MQTT. `mtls_from_path`menggunakan sertifikat X.509 dan TLS v1.2 untuk mengautentikasi perangkat. Pustaka AWS-CRT menangani detail tingkat yang lebih rendah dari koneksi itu.
```
mqtt_connection = mqtt_connection_builder.mtls_from_path(
endpoint=args.endpoint,
cert_filepath=args.cert,
pri_key_filepath=args.key,
ca_filepath=args.ca_file,
client_bootstrap=client_bootstrap,
on_connection_interrupted=on_connection_interrupted,
on_connection_resumed=on_connection_resumed,
client_id=args.client_id,
clean_session=False,
keep_alive_secs=6
)
```
+ `endpoint`adalah AWS IoT titik akhir Anda yang Anda lewatkan dari baris perintah dan `client_id` merupakan ID yang secara unik mengidentifikasi perangkat ini di. Wilayah AWS
+ `cert_filepath`,`pri_key_filepath`, dan `ca_filepath` merupakan jalur ke sertifikat perangkat dan file kunci pribadi, dan file CA root.
+ `client_bootstrap`adalah objek runtime umum yang menangani aktivitas komunikasi soket, dan dipakai sebelum panggilan ke. `mqtt_connection_builder.mtls_from_path`
+ `on_connection_interrupted`dan `on_connection_resumed` merupakan fungsi panggilan balik untuk memanggil ketika koneksi perangkat terputus dan dilanjutkan.
+ `clean_session`adalah apakah akan memulai sesi baru yang persisten, atau jika ada, sambungkan kembali ke yang sudah ada. `keep_alive_secs`adalah nilai keep alive, dalam hitungan detik, untuk mengirim `CONNECT` permintaan. Ping akan secara otomatis dikirim pada interval ini. Server mengasumsikan bahwa koneksi terputus jika tidak menerima ping setelah 1,5 kali nilai ini.
`shadow.py`Sampel juga memanggil `websockets_with_default_aws_signing` [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py)untuk membuat koneksi dengan AWS IoT Core menggunakan protokol MQTT melalui WSS. MQTT melalui WSS juga menggunakan parameter yang sama seperti MQTT dan mengambil parameter tambahan ini:
+ `region`adalah Wilayah AWS penandatanganan yang digunakan oleh otentikasi Signature V4, dan `credentials_provider` merupakan AWS kredensyal yang disediakan untuk digunakan untuk otentikasi. Region dilewatkan dari baris perintah, dan `credentials_provider` objek dipakai sesaat sebelum panggilan ke. `mqtt_connection_builder.websockets_with_default_aws_signing`
+ `websocket_proxy_options`adalah opsi proxy HTTP, jika menggunakan host proxy. Dalam aplikasi `shadow.py` sampel, nilai ini dipakai sesaat sebelum panggilan ke. `mqtt_connection_builder.websockets_with_default_aws_signing`
**Berlangganan topik dan acara Shadow**
`shadow.py`Sampel mencoba untuk membuat koneksi dan menunggu untuk terhubung sepenuhnya. Jika tidak terhubung, perintah akan diantrian. Setelah terhubung, sampel berlangganan acara delta dan memperbarui dan mendapatkan pesan, dan menerbitkan pesan dengan tingkat Quality of Service (QoS) 1 (). `mqtt.QoS.AT_LEAST_ONCE`
Saat perangkat berlangganan pesan dengan QoS level 1, broker pesan menyimpan pesan yang dilanggani perangkat hingga dapat dikirim ke perangkat. Broker pesan mengirim ulang pesan hingga menerima `PUBACK` respons dari perangkat.
Untuk informasi lebih lanjut tentang protokol MQTT, lihat dan. [Tinjau protokol MQTT](sdk-tutorials.md#sdk-tutorials-mqtt-review) [MQTT](mqtt.md)
Untuk informasi lebih lanjut tentang bagaimana MQTT, MQTT melalui WSS, sesi persisten, dan level QoS yang digunakan dalam tutorial ini, lihat. [Tinjau aplikasi contoh SDK Perangkat pubsub.py](sdk-tutorials.md#sdk-tutorials-explore-sample)
## Langkah 3: Memecahkan masalah dengan aplikasi sampel `shadow.py`
Saat menjalankan aplikasi `shadow.py` sampel, Anda akan melihat beberapa pesan ditampilkan di terminal dan prompt untuk memasukkan `desired` nilai. Jika program melempar kesalahan, maka untuk men-debug kesalahan, Anda dapat mulai dengan memeriksa apakah Anda menjalankan perintah yang benar untuk sistem Anda.
Dalam beberapa kasus, pesan kesalahan mungkin menunjukkan masalah koneksi dan terlihat mirip dengan: `Host name was invalid for dns resolution` atau`Connection was closed unexpectedly`. Dalam kasus seperti itu, berikut adalah beberapa hal yang dapat Anda periksa:
+
**Periksa alamat titik akhir dalam perintah**
Tinjau `endpoint` argumen dalam perintah yang Anda masukkan untuk menjalankan aplikasi sampel, (misalnya,`a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com`) dan periksa nilai ini di **AWS IoT konsol**.
Untuk memeriksa apakah Anda menggunakan nilai yang benar:
1. Di **AWS IoT konsol**, pilih **Kelola** dan kemudian pilih **Things**.
1. **Pilih hal yang Anda buat untuk aplikasi sampel Anda (misalnya, **my\$1light\$1bulb**) dan kemudian pilih Interact.**
Pada halaman detail hal, titik akhir Anda ditampilkan di bagian **HTTPS**. Anda juga harus melihat pesan yang mengatakan: `This thing already appears to be connected.`
+
**Periksa aktivasi sertifikat**
Sertifikat mengautentikasi perangkat Anda dengan AWS IoT Core.
Untuk memeriksa apakah sertifikat Anda aktif:
1. Di **AWS IoT konsol**, pilih **Kelola** dan kemudian pilih **Things**.
1. **Pilih hal yang Anda buat untuk aplikasi sampel Anda (misalnya, **my\$1light\$1bulb**) dan kemudian pilih Keamanan.**
1. Pilih sertifikat dan kemudian, dari halaman detail sertifikat, pilih Pilih sertifikat dan kemudian, dari halaman detail sertifikat, pilih **Tindakan**.
Jika dalam daftar tarik-turun **Aktifkan** tidak tersedia dan Anda hanya dapat memilih **Nonaktifkan**, sertifikat Anda aktif. Jika tidak, pilih **Aktifkan** dan jalankan kembali program sampel.
Jika program masih tidak berjalan, periksa nama file sertifikat di `certs` folder.
+
**Periksa kebijakan yang dilampirkan pada sumber daya benda**
Sementara sertifikat mengautentikasi perangkat Anda, AWS IoT kebijakan mengizinkan perangkat untuk melakukan AWS IoT operasi, seperti berlangganan atau memublikasikan topik yang dicadangkan MQTT.
Untuk memeriksa apakah kebijakan yang benar terlampir:
1. Temukan sertifikat seperti yang dijelaskan sebelumnya, lalu pilih **Kebijakan**.
1. Pilih kebijakan yang ditampilkan dan periksa apakah kebijakan tersebut menjelaskan`connect`,, `subscribe``receive`, dan `publish` tindakan yang memberikan izin perangkat untuk mempublikasikan dan berlangganan topik yang dicadangkan MQTT.
Untuk kebijakan sampel, lihat[Langkah 1: Buat AWS IoT kebijakan untuk Device Shadow](shadow-provision-cloud.md#create-policy-shadow).
Jika Anda melihat pesan galat yang menunjukkan masalah saat terhubung AWS IoT, itu mungkin karena izin yang Anda gunakan untuk kebijakan tersebut. Jika demikian, kami sarankan Anda memulai dengan kebijakan yang menyediakan akses penuh ke AWS IoT sumber daya dan kemudian menjalankan kembali program sampel. Anda dapat mengedit kebijakan saat ini, atau memilih kebijakan saat ini, pilih **Lepaskan**, lalu buat kebijakan lain yang menyediakan akses penuh dan melampirkannya ke sumber daya Anda. Anda nantinya dapat membatasi kebijakan hanya pada tindakan dan kebijakan yang Anda perlukan untuk menjalankan program.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:*"
],
"Resource": "*"
}
]
}
```
+
**Periksa penginstalan SDK Perangkat**
Jika program masih tidak berjalan, Anda dapat menginstal ulang Device SDK untuk memastikan bahwa instalasi SDK Anda selesai dan benar.
## Langkah 4: Tinjau hasil dan langkah selanjutnya
**Dalam tutorial ini, Anda belajar cara:**
+ Instal perangkat lunak, alat, dan AWS IoT Device SDK yang diperlukan untuk Python.
+ Pahami bagaimana aplikasi sampel,`shadow.py`, menggunakan protokol MQTT untuk mengambil dan memperbarui status bayangan saat ini.
+ Jalankan aplikasi sampel untuk Device Shadows dan amati pembaruan ke dokumen Shadow di AWS IoT konsol. Anda juga belajar memecahkan masalah apa pun dan memperbaiki kesalahan saat menjalankan program.
**Langkah selanjutnya**
Anda sekarang dapat menjalankan aplikasi `shadow.py` sampel dan menggunakan Device Shadows untuk mengontrol status. Anda dapat mengamati pembaruan pada dokumen Shadow di AWS IoT Konsol dan mengamati peristiwa delta yang merespons aplikasi sampel. Dengan menggunakan klien pengujian MQTT, Anda dapat berlangganan topik bayangan yang dipesan dan mengamati pesan yang diterima oleh topik saat menjalankan program sampel. Untuk informasi lebih lanjut tentang cara menjalankan tutorial ini, lihat[Tutorial: Berinteraksi dengan Device Shadow menggunakan aplikasi sampel dan klien pengujian MQTT](interact-lights-device-shadows.md).