Menerapkan AWS. SendCommand operasi

AWS.SendCommandOperasi ini memungkinkan integrasi terkelola untuk AWS IoT Device Management untuk mengirim perintah yang dimulai oleh pengguna akhir melalui pelanggan ke server AWS sumber daya Anda. Server sumber daya Anda dapat mendukung beberapa jenis perangkat, di mana setiap jenis memiliki model responsnya sendiri. Eksekusi perintah adalah proses asinkron di mana integrasi terkelola untuk AWS IoT Device Management mengirimkan permintaan untuk eksekusi perintah dengan `TraceID`, yang akan disertakan konektor Anda dalam respons perintah yang dikirim kembali ke integrasi terkelola melalui `` API. SendConnectorEvent integrasi terkelola untuk AWS IoT Device Management mengharapkan server sumber daya mengembalikan respons yang mengakui bahwa perintah telah diterima, tetapi tidak selalu menunjukkan perintah itu dieksekusi.

Diagram berikut menggambarkan alur eksekusi perintah dengan contoh di mana pengguna akhir mencoba menyalakan lampu rumah mereka:

Alur kerja eksekusi perintah perangkat

1. Pengguna akhir mengirimkan perintah untuk menyalakan lampu menggunakan aplikasi AWS pelanggan.

2. Pelanggan menyampaikan informasi perintah ke integrasi terkelola untuk AWS IoT Device Management dengan informasi perangkat pengguna akhir.

3. Integrasi terkelola menghasilkan “traceID” yang akan digunakan konektor Anda saat mengirim respons perintah kembali ke layanan.

4. integrasi terkelola untuk AWS IoT Device Management mengirimkan permintaan perintah ke konektor Anda, menggunakan antarmuka operasiAWS.SendCommand.

   1. Payload yang ditentukan oleh antarmuka ini terdiri dari pengidentifikasi perangkat, perintah perangkat yang dirumuskan sebagai Matterendpoints/clusters/commands, token akses pengguna akhir, dan parameter lain yang diperlukan.

5. Konektor Anda traceId menyimpan yang akan disertakan dalam respons perintah.

   1. Konektor Anda menerjemahkan permintaan perintah integrasi terkelola ke dalam format server sumber daya yang sesuai.

6. Konektor Anda mendapatkan UserId dari token akses pengguna akhir yang disediakan dan mengaitkannya dengan perintah.

   1. UserIdDapat diambil dari server sumber daya Anda menggunakan panggilan terpisah atau diekstrak dari token akses jika terjadi JWT dan token serupa.

   2. Implementasi tergantung pada server sumber daya dan detail token akses Anda.

7. Konektor Anda memanggil server sumber daya ke lampu pengguna akhir “Aktifkan”.

8. Server sumber daya berinteraksi dengan perangkat.

   1. Konektor menyampaikan ke integrasi terkelola untuk AWS IoT Device Management yang server sumber daya telah mengirimkan perintah, merespons dengan ACK sebagai respons perintah awal yang sinkron.

   2. Integrasi terkelola kemudian menyampaikannya kembali ke aplikasi pelanggan.

9. Setelah perangkat menyalakan lampu, peristiwa perangkat tersebut ditangkap oleh server sumber daya Anda.

10. Server sumber daya Anda mengirimkan peristiwa perangkat ke konektor.

11. Konektor Anda mengubah peristiwa perangkat yang dihasilkan oleh server sumber daya menjadi integrasi terkelola tipe operasi peristiwa DEVICE_COMMAND_RESPONSE.

12. Konektor Anda memanggil SendConnectorEvent API dengan operasi sebagai “DEVICE_COMMAND_RESPONSE”.

    1. Ini melampirkan integrasi yang traceId disediakan oleh terkelola untuk AWS IoT Device Management dalam permintaan awal.

13. Integrasi terkelola memberi tahu pelanggan tentang perubahan status perangkat pengguna akhir.

14. Pelanggan memberi tahu pengguna akhir bahwa lampu perangkat telah menyala.

    catatan

    Konfigurasi server sumber daya Anda menentukan logika untuk menangani permintaan perintah perangkat yang gagal dan pesan respons. Ini termasuk percobaan ulang pesan menggunakan referenceId yang sama untuk perintah.

Persyaratan konektor C2C untuk eksekusi perintah perangkat

Daftar berikut menguraikan persyaratan untuk konektor C2C Anda untuk memfasilitasi eksekusi perintah perangkat yang berhasil.

• Konektor C2C Lambda dapat memproses pesan permintaan AWS.SendCommand operasi dari integrasi terkelola untuk AWS IoT Device Management.

• Konektor C2C Anda harus melacak perintah yang dikirim ke server sumber daya Anda dan memetakannya dengan `traceID` yang sesuai.

• Anda dapat memanggil integrasi terkelola untuk AWS IoT Device Management API layanan melalui SigV4 AWS menggunakan Akun AWS kredensil yang digunakan untuk mendaftarkan konektor C2C.

1. Integrasi terkelola mengirimkan perintah ke konektor (Lihat langkah 4 pada diagram sebelumnya).

   1. /Send-Command
      {
           "header": {
                "auth": {                 
                    "token": "ashriu32yr97feqy7afsaf",  
                    "type": "OAuth2.0"
                }
           },
           "payload": {
                "operationName": "AWS.SendCommand",
                "operationVersion": "1.0",
                "connectorId": "Your-Connector-Id",
                "connectorDeviceId": "Your_Device_Id",
                "traceId": "traceId-3241u78123419",
                "endpoints": [{
                    "id": "1",    
                    "clusters": [{
                        "id": "0x0202",
                        "commands": [{
                            "0xff01": 
                                {
                                    "0x0000": "3”
                        		}
                        }]
                    }]
                }]
           }
        }
      

2. Perintah ACK konektor C2C (Lihat langkah 7 pada diagram sebelumnya di mana konektor mengirimkan ACK ke integrasi terkelola untuk AWS IoT Device Management Service).

   1. {
           "header":{
                "responseCode":200
           },
           "payload":{
                "responseMessage": "Successfully received send-command request for connector 'Your-Connector-Id' and connector-device-id 'Your_Device_Id'" 
           }
        }
      

3. Konektor mengirimkan peristiwa Respons Perintah Perangkat (Lihat langkah 11 pada diagram sebelumnya).

   1. AWS-API: /SendConnectorEvent
      URI: POST /connector-event/{Your-Connector-Id}
      
      {
         "UserId": "End-User-Id",
         "Operation": "DEVICE_COMMAND_RESPONSE",
         "OperationVersion": "1.0",
         "StatusCode": 200,
         "Message": “Example message”,
         "ConnectorDeviceId": "Your_Device_Id",
         "TraceId": "traceId-3241u78123419",
         "MatterEndpoint": {
              "id": "1",    
              "clusters": [{
                  "id": "0x0202",
                  "attributes": [
                      {
                          "0x0000": “3”
                      }
                  ],
                  "commands": [
                      "0xff01": 
                      {
                          "0x0000": "3”
                      }            
       		]
              }]
          }
      }
      

   catatan

   Perubahan status perangkat sebagai akibat dari eksekusi perintah tidak akan tercermin dalam integrasi terkelola untuk AWS IoT Device Management hingga peristiwa DEVICE_COMMAND_RESPONSE yang sesuai telah diterima melalui API. SendConnectorEvent Ini berarti bahwa hingga integrasi terkelola menerima peristiwa dari langkah 3 sebelumnya, terlepas dari apakah respons pemanggilan konektor Anda menunjukkan keberhasilan atau tidak, status perangkat tidak akan diperbarui.

Menafsirkan 'titik akhir' materi yang disertakan dalam AWS. SendCommand permintaan

Integrasi terkelola akan menggunakan kemampuan perangkat yang dilaporkan selama penemuan perangkat untuk menentukan perintah apa yang dapat diterima perangkat. Setiap kemampuan perangkat dimodelkan melalui AWS implementasi Model Data Matter; dengan demikian, semua perintah yang masuk akan diturunkan dari bidang `commands` dalam cluster tertentu. Adalah tanggung jawab konektor Anda untuk mengurai bidang `titik akhir`, menentukan perintah Matter yang sesuai, dan menerjemahkannya sedemikian rupa sehingga perintah yang benar mencapai perangkat. Biasanya, ini berarti menerjemahkan model data Matter ke dalam permintaan API terkait.

Setelah perintah dijalankan, konektor Anda kemudian menentukan `atribut` mana yang ditentukan oleh AWS implementasi Model Data Materi yang telah berubah sebagai hasilnya. Perubahan ini kemudian dilaporkan ke integrasi terkelola untuk AWS IoT Device Management melalui peristiwa API DEVICE_COMMAND_RESPONSE yang dikirim bersama API. SendConnectorEvent

Pertimbangkan bidang `endpoints` yang disertakan dalam contoh payload berikut: AWS.SendCommand

          "endpoints": [{
              "id": "1",    
              "clusters": [{
                  "id": "0x0202",
                  "commands": [{
                      "0xff01": 
                          {
                              "0x0000": "3”
                  		}
                  }]
              }]
          }]

Dari objek ini, konektor dapat menentukan yang berikut:

1. Mengatur informasi endpoint dan cluster:

   1. Atur titik akhir id ke “1".

      catatan

      Jika perangkat mendefinisikan beberapa titik akhir sehingga satu cluster (sepertiOn/Off) can control multiple capabilities (i.e. turn a light on/off as well as turning a strobe on/off), id ini digunakan untuk merutekan perintah ke kemampuan yang benar.

   2. Atur cluster id ke “0x0202" (cluster Kontrol Kipas).

2. Mengatur informasi perintah:

   1. Atur pengidentifikasi perintah ke “0xff01" (Perbarui perintah Status yang ditentukan oleh). AWS

   2. Perbarui pengidentifikasi atribut yang disertakan dengan nilai yang disediakan dalam permintaan.

3. Perbarui atribut:

   1. Setel pengenal atribut ke “0x0000" (FanMode atribut dari Fan Control Cluster).

   2. Atur nilai atribut ke “3" (Kecepatan kipas tinggi).

Integrasi terkelola telah mendefinisikan dua jenis perintah “kustom” yang tidak ditentukan secara ketat oleh AWS implementasi Model Data Materi: Perintah ReadState dan UpdateState . Untuk mendapatkan dan menyetel atribut cluster yang ditentukan Matter, integrasi terkelola akan mengirimkan AWS.SendCommand permintaan konektor Anda dengan perintah yang IDs berkaitan dengan UpdateState (id: 0xff01) atau ReadState (id: 0xff02), dengan parameter atribut yang sesuai yang harus diperbarui atau dibaca. Perintah ini dapat dipanggil untuk jenis perangkat APAPUN untuk atribut yang disetel sebagai bisa berubah (dapat diperbarui) atau dapat diambil (dapat dibaca) dari implementasi Model Data Matter yang sesuai AWS .