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: 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 : 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" } } ] } }