action.devices.SYNC

Cet intent demande la liste des appareils associés à l'utilisateur donné et de leurs fonctionnalités.

Elle se déclenche lors de l'association de comptes ou lorsqu'un utilisateur resynchronise manuellement ses appareils. Votre traitement doit renvoyer les caractéristiques et attributs acceptés pour chaque appareil.

Votre réponse SYNC doit renvoyer tous les appareils associés à l'utilisateur. Cela ne détermine pas si un appareil particulier est accessible. Ce comportement est géré par les réponses QUERY et EXECUTE.

Pour en savoir plus, consultez Identifier et synchroniser.

Format de requête

Champs Type Description
requestId Chaîne

Obligatoire.

ID de la requête.

inputs Array

Obligatoire.

Liste des entrées correspondant à la requête d'intent.

[item, ...] Objet

Type et charge utile associé à la requête d'intent.

intent

Obligatoire.

(Valeur constante: "action.devices.SYNC")

Type de requête d'intent.

Exemples

Requête d'intent SYNC

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}

Format de réponse

Champs Type Description
requestId Chaîne

Obligatoire.

ID de la requête correspondante.

payload Objet

Obligatoire.

Charge utile de la réponse d'intent.

agentUserId Chaîne

Obligatoire.

Reflète l'ID utilisateur unique (et immuable) sur la plate-forme de l'agent. La chaîne est opaque pour Google. Par conséquent, s'il existe une forme immuable et non modifiable du côté de l'agent, utilisez la forme immuable (par exemple, un numéro de compte plutôt que des adresses e-mail).

errorCode Chaîne

Pour les erreurs systématiques lors de la synchronisation

debugString Chaîne

Erreur détaillée qui ne sera jamais présentée aux utilisateurs, mais qui peut être consignée ou utilisée lors du développement.

devices Array

Obligatoire.

Liste des appareils appartenant à l'utilisateur. Zéro ou plusieurs appareils renvoyés (aucun appareil indiquant que l'utilisateur n'a aucun appareil ou les a tous déconnectés)

[item, ...] Objet

Métadonnées de l'appareil.

id Chaîne

Obligatoire.

ID de l'appareil dans le cloud du développeur. Cette valeur doit être propre à l'utilisateur et au développeur. En effet, en cas de partage, nous pouvons utiliser cette information pour supprimer les vues multiples du même appareil. Il doit être immuable et l'Assistant le traitera comme un nouvel appareil en cas de changement.

type Chaîne

Obligatoire.

Type de matériel de l'appareil.

traits Array

Obligatoire.

Liste des caractéristiques de cet appareil. Ce champ définit les commandes, les attributs et les états acceptés par l'appareil.

[item, ...] Chaîne

Nom de la caractéristique acceptée.

name Objet

Obligatoire.

Noms de cet appareil.

defaultNames Array

Liste de noms fournis par le développeur plutôt que par l'utilisateur, souvent les noms des fabricants, les codes SKU, etc.

[item, ...] Chaîne

Nom par défaut de l'appareil.

name Chaîne

Obligatoire.

Nom principal de l'appareil, généralement fourni par l'utilisateur. Il s'agit également du nom que l'Assistant utilisera pour décrire l'appareil dans les réponses.

nicknames Array

Noms supplémentaires fournis par l'utilisateur pour l'appareil.

[item, ...] Chaîne

Pseudo de l'appareil.

willReportState Booléen

Obligatoire.

Indique si les états de cet appareil sont mis à jour par le flux en temps réel. (true pour utiliser le flux en temps réel pour l'état du rapport, et faux pour utiliser le modèle de sondage).

notificationSupportedByAgent Booléen

(Par défaut : false)

Indique si les notifications sont activées pour l'appareil.

roomHint Chaîne

Indique la salle actuelle de l'appareil de la maison de l'utilisateur pour simplifier la configuration.

deviceInfo Objet

Contient des champs décrivant l'appareil à utiliser dans une logique ponctuelle si nécessaire (par exemple, "la version X du micrologiciel Y est endommagée et nécessite un ajustement de la couleur", ou "la faille de sécurité nécessite d'informer tous les utilisateurs du micrologiciel Z").

manufacturer Chaîne

Cette fonctionnalité est particulièrement utile lorsque le développeur sert de hub pour d'autres appareils. Google peut fournir une liste standard de fabricants afin que, par exemple, TP-Link et Smartthings décrivent tous les deux le terme "osram" de la même manière.

model Chaîne

Modèle ou identifiant SKU de l'appareil concerné.

hwVersion Chaîne

Numéro de version attaché au matériel, si disponible.

swVersion Chaîne

Numéro de version spécifique associé au logiciel/logiciel, le cas échéant.

attributes Objet

Alignement avec les attributs par caractéristique décrits dans chaque référence de schéma de caractéristique.

customData Objet

Objet défini par le développeur qui sera associé aux futures requêtes QUERY et EXECUTE, avec un maximum de 512 octets par appareil. Utilisez cet objet pour stocker des informations supplémentaires sur l'appareil dont votre service cloud pourrait avoir besoin, telles que la région globale de l'appareil. Les données de cet objet présentent quelques contraintes: aucune information sensible, y compris, mais sans s'y limiter, des informations permettant d'identifier personnellement l'utilisateur.

otherDeviceIds Array

Liste des autres ID utilisés pour identifier un appareil synchronisé avec le cloud pour l'exécution locale.

[item, ...] Objet

Autre ID de l'appareil.

agentId Chaîne

ID de l'agent. Il s'agit généralement de l'ID du projet dans la console Actions.

deviceId Chaîne

Obligatoire.

ID de l'appareil défini par l'agent. L'ID de l'appareil doit être unique.

Exemples

Réponse d'intent SYNC

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.OUTLET",
        "traits": [
          "action.devices.traits.OnOff"
        ],
        "name": {
          "defaultNames": [
            "My Outlet 1234"
          ],
          "name": "Night light",
          "nicknames": [
            "wall plug"
          ]
        },
        "willReportState": false,
        "roomHint": "kitchen",
        "deviceInfo": {
          "manufacturer": "lights-out-inc",
          "model": "hs1234",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        },
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id"
          }
        ],
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      },
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting"
        ],
        "name": {
          "defaultNames": [
            "lights out inc. bulb A19 color hyperglow"
          ],
          "name": "lamp1",
          "nicknames": [
            "reading lamp"
          ]
        },
        "willReportState": false,
        "roomHint": "office",
        "attributes": {
          "colorModel": "rgb",
          "colorTemperatureRange": {
            "temperatureMinK": 2000,
            "temperatureMaxK": 9000
          },
          "commandOnlyColorSetting": false
        },
        "deviceInfo": {
          "manufacturer": "lights out inc.",
          "model": "hg11",
          "hwVersion": "1.2",
          "swVersion": "5.4"
        },
        "customData": {
          "fooValue": 12,
          "barValue": false,
          "bazValue": "bar"
        }
      }
    ]
  }
}