Implémentez l'AWS. SendCommand opération - Intégrations gérées pour AWS IoT Device Management
Exigences relatives au connecteur C2C pour l'exécution des commandes de l'appareilInterprétation des « points de terminaison » inclus dans AWS. SendCommand demande

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Implémentez l'AWS. SendCommand opération

L'AWS.SendCommandopération permet aux intégrations gérées pour AWS IoT Device Management d'envoyer des commandes initiées par l'utilisateur final via le AWS client à votre serveur de ressources. Votre serveur de ressources peut prendre en charge plusieurs types de périphériques, chaque type ayant son propre modèle de réponse. L'exécution de commandes est un processus asynchrone dans le cadre duquel les intégrations gérées pour AWS IoT Device Management envoient une demande d'exécution de commande avec un « TraceID », que votre connecteur inclura dans une réponse de commande renvoyée aux intégrations gérées via l'API « SendConnectorEvent ». Les intégrations gérées pour AWS IoT Device Management attendent du serveur de ressources qu'il renvoie une réponse confirmant la réception de la commande, mais n'indiquant pas nécessairement que la commande a été exécutée.

Le schéma suivant illustre le flux d'exécution des commandes avec un exemple dans lequel l'utilisateur final essaie d'allumer les lumières de sa maison :

Flux de travail d'exécution des commandes des appareils
Flux de travail d'exécution des commandes des appareils

  1. Un utilisateur final envoie une commande pour allumer une lampe à l'aide de l'application du AWS client.

  2. Le client transmet les informations de commande aux intégrations gérées pour AWS IoT Device Management avec les informations relatives aux appareils de l'utilisateur final.

  3. Les intégrations gérées génèrent un « TraceID » que votre connecteur utilisera pour renvoyer les réponses aux commandes au service.

  4. les intégrations gérées pour AWS IoT Device Management envoient la demande de commande à votre connecteur via l'interface d'AWS.SendCommandexploitation.

    1. La charge utile définie par cette interface comprend l'identifiant de l'appareil, les commandes de l'appareil formulées sous la forme Matterendpoints/clusters/commands, le jeton d'accès de l'utilisateur final et d'autres paramètres requis.

  5. Votre connecteur stocke les éléments traceId à inclure dans la réponse à la commande.

    1. Votre connecteur traduit la demande de commande d'intégrations gérées dans le format approprié de votre serveur de ressources.

  6. Votre connecteur obtient le jeton UserId d'accès fourni à l'utilisateur final et l'associe à la commande.

    1. Ils UserId peuvent être récupérés auprès de votre serveur de ressources à l'aide d'un appel séparé ou extraits du jeton d'accès dans le cas de JWT et de jetons similaires.

    2. La mise en œuvre dépend de votre serveur de ressources et des détails de votre jeton d'accès.

  7. Votre connecteur appelle le serveur de ressources pour qu'il « allume » la lumière de l'utilisateur final.

  8. Le serveur de ressources interagit avec le périphérique.

    1. Le connecteur transmet aux intégrations gérées pour AWS IoT Device Management que le serveur de ressources a délivré la commande, en répondant par un ACK comme réponse de commande synchrone initiale.

    2. Les intégrations gérées le retransmettent ensuite à l'application client.

  9. Une fois que l'appareil a allumé la lumière, cet événement est capturé par votre serveur de ressources.

  10. Votre serveur de ressources envoie l'événement du périphérique au connecteur.

  11. Votre connecteur transforme l'événement de périphérique généré par le serveur de ressources en intégrations gérées, type d'opération d'événement DEVICE_COMMAND_RESPONSE.

  12. Votre connecteur appelle l'SendConnectorEventAPI avec l'opération « DEVICE_COMMAND_RESPONSE ».

    1. Il joint les intégrations traceId fournies par les intégrations gérées pour AWS IoT Device Management dans la demande initiale.

  13. Les intégrations gérées informent le client du changement d'état de l'appareil de l'utilisateur final.

  14. Le client informe l'utilisateur final que le voyant de l'appareil est allumé.

    Note

    La configuration de votre serveur de ressources détermine la logique de gestion des messages de demande de commande et de réponse du périphérique ayant échoué. Cela inclut les tentatives de nouvelle tentative de message utilisant le même ReferenceID pour la commande.

Exigences relatives au connecteur C2C pour l'exécution des commandes de l'appareil

La liste suivante décrit les exigences relatives à votre connecteur C2C afin de faciliter l'exécution réussie des commandes du périphérique.

  • Le connecteur Lambda C2C peut AWS.SendCommand traiter les messages de demande d'opération provenant d'intégrations gérées pour AWS IoT Device Management.

  • Votre connecteur C2C doit suivre les commandes envoyées à votre serveur de ressources et le mapper avec le `TraceID` approprié.

  • Vous pouvez appeler des intégrations gérées pour les API du service AWS IoT Device Management via SigV4 en utilisant les AWS informations d'identification Compte AWS utilisées pour enregistrer le connecteur C2C.

  1. Les intégrations gérées envoient une commande au connecteur (reportez-vous à l'étape 4 du schéma précédent).

    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. Commande ACK du connecteur C2C (reportez-vous à l'étape 7 du schéma précédent où le connecteur envoie l'ACK aux intégrations gérées pour 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. Le connecteur envoie un événement Device Command Response (reportez-vous à l'étape 11 du schéma précédent).

    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”
                }            
 		]
        }]
    }
}
    Note

    Les modifications de l'état de l'appareil résultant de l'exécution d'une commande ne seront pas reflétées dans les intégrations gérées pour AWS IoT Device Management tant que l'événement DEVICE_COMMAND_RESPONSE correspondant n'aura pas été reçu via l'API. SendConnectorEvent Cela signifie que tant que Managed Integrations ne recevra pas l'événement de l'étape 3 précédente, que votre réponse d'appel du connecteur indique un succès ou non, l'état de l'appareil ne sera pas mis à jour.

Interprétation des « points de terminaison » inclus dans AWS. SendCommand demande

Les intégrations gérées utiliseront les fonctionnalités de l'appareil signalées lors de la découverte de l'appareil pour déterminer les commandes qu'un appareil peut accepter. Les capacités de chaque appareil sont modélisées grâce à AWS des implémentations du modèle Matter Data ; ainsi, toutes les commandes entrantes seront dérivées du champ « commandes » d'un cluster donné. Il est de la responsabilité de votre connecteur d'analyser le champ `endpoints`, de déterminer la commande Matter correspondante et de la traduire de telle sorte que la bonne commande atteigne le périphérique. Cela implique généralement de traduire le modèle de données Matter dans les demandes d'API associées.

Une fois la commande exécutée, votre connecteur détermine quels « attributs » définis par les AWS implémentations du Matter Data Model ont changé en conséquence. Ces modifications sont ensuite signalées aux intégrations gérées pour AWS IoT Device Management via les événements API DEVICE_COMMAND_RESPONSE envoyés avec l'API. SendConnectorEvent

Considérez le champ `endpoints` inclus dans l'exemple de charge utile suivant : AWS.SendCommand

          "endpoints": [{
              "id": "1",    
              "clusters": [{
                  "id": "0x0202",
                  "commands": [{
                      "0xff01": 
                          {
                              "0x0000": "3”
                  		}
                  }]
              }]
          }]
À partir de cet objet, le connecteur peut déterminer les éléments suivants :

  1. Définissez les informations du point de terminaison et du cluster :

    1. Réglez le point id de terminaison sur « 1 ».

      Note

      Si un appareil définit plusieurs points de terminaison tels qu'un seul cluster (par exempleOn/Off) can control multiple capabilities (i.e. turn a light on/off as well as turning a strobe on/off), cet identifiant est utilisé pour acheminer la commande vers la fonctionnalité appropriée.

    2. Réglez le cluster id sur « 0x0202 » (cluster de contrôle du ventilateur).

  2. Définissez les informations de commande :

    1. Définissez l'identifiant de commande sur « 0xff01 » (commande Update State définie par). AWS

    2. Mettez à jour les identificateurs d'attributs inclus avec les valeurs fournies dans la demande.

  3. Mettez à jour l'attribut :

    1. Définissez l'identifiant d'attribut sur « 0x0000 » (FanMode attribut du cluster de contrôle des ventilateurs).

    2. Définissez la valeur de l'attribut sur « 3 » (vitesse du ventilateur élevée).

Managed Integrations a défini deux types de commandes « personnalisés » qui ne sont pas strictement définis par AWS les implémentations du modèle de données Matter : les commandes ReadState et UpdateState . Pour obtenir et définir les attributs de cluster définis par Matter, les intégrations gérées enverront à votre connecteur une AWS.SendCommand demande avec une commande IDs relative à UpdateState (id : 0xff01) ou ReadState (id : 0xff02), avec les paramètres correspondants des attributs qui doivent être mis à jour ou lus. Ces commandes peuvent être invoquées pour TOUT type d'appareil pour les attributs définis comme mutables (modifiables) ou récupérables (lisibles) à partir de l' AWS implémentation correspondante du modèle de données de matière.