כשמשתמשים מקיימים אינטראקציה עם Google Assistant כדי לבצע שאילתה לגבי המצב הנוכחי של מכשיר, מילוי ההזמנה מקבל כוונה (action.devices.QUERY
) שמכילה רשימה של מזהי מכשירים (כפי שסופק על ידי התשובה SYNC
).
מילוי ההזמנה מקבל כוונה להשתמש ב-action.devices.EXECUTE
כשמשתמשים שולחים פקודות אל Assistant כדי לשלוט במכשיר.
צריך לטפל ב-QUERY
כוונות
התשובה שלך ב-QUERY
כוללת קבוצה מלאה של מצבים לכל אחת מהתכונות הנתמכות על ידי המכשירים המבוקשים.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.QUERY", "payload": { "devices": [{ "id": "123", "customData": { "fooValue": 74, "barValue": true, "bazValue": "foo" } }, { "id": "456", "customData": { "fooValue": 12, "barValue": false, "bazValue": "bar" } }] } }] }
JSON
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "123": { "on": true, "online": true }, "456": { "on": true, "online": true, "brightness": 80, "color": { "name": "cerulean", "spectrumRGB": 31655 } } } } }
Node.js
const {smarthome} = require('actions-on-google'); const app = smarthome(); // ... app.onQuery((body, headers) => { // TODO Get device state return { requestId: body.requestId, payload: { devices: { 123: { on: true, online: true }, 456: { on: true, online: true, brightness: 80, color: { name: "cerulean", spectrumRGB: 31655 } } } } }; });
Java
@NotNull @Override public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) { QueryResponse.Payload payload = new QueryResponse.Payload(); payload.setDevices( new HashMap<String, Map<String, Object>>() { { put( "123", new HashMap<String, Object>() { { put("on", true); put("online", true); } }); put( "456", new HashMap<String, Object>() { { put("on", true); put("online", true); put("brightness", 80); put( "color", new HashMap<String, Object>() { { put("name", "cerulean"); put("spectrumRGB", 31655); } }); } }); } }); return new QueryResponse(queryRequest.getRequestId(), payload); }
למידע נוסף, עיינו במסמכי התיעוד של QUERY
לגבי כוונת רכישה.
צריך לטפל ב-EXECUTE
כוונות
בדומה ל-QUERY
, כוונת רכישה אחת יכולה לטרגט כמה מזהי מכשירים. הכוונה אחת (EXECUTE
) יכולה גם להכיל מספר פקודות נפרדות שניתנות לקבוצת מכשירים. לדוגמה, כש-Intent מופעל, ניתן להגדיר גם בהירות וגם צבע בקבוצה של אורות, או להגדיר מספר נורות לצבע אחר. תגובת EXECUTE
צריכה להחזיר את המצב החדש של המכשיר אחרי ההפעלה.
יש להשתמש בקובץ Report State
כשמצב המכשיר של המשתמשים משתנה. לדוגמה, בגלל שינוי בכוונה (EXECUTE
) או שינוי מצב מקומי (כמו היפוך ידני של המתג).
כך Google Home Graph מסונכרן עם שירות הענן.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123", "customData": { "fooValue": 74, "barValue": true, "bazValue": "sheepdip" } }, { "id": "456", "customData": { "fooValue": 36, "barValue": false, "bazValue": "moarsheep" } }], "execution": [{ "command": "action.devices.commands.OnOff", "params": { "on": true } }] }] } }] }
JSON
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "on": true, "online": true } }, { "ids": [ "456" ], "status": "ERROR", "errorCode": "deviceTurnedOff" } ] } }
Node.js
const {smarthome} = require('actions-on-google'); const app = smarthome(); // ... app.onExecute((body, headers) => { // TODO Send command to device return { requestId: body.requestId, payload: { commands: [{ ids: ["123"], status: "SUCCESS", states: { on: true, online: true } }, { ids: ["456"], status: "ERROR", errorCode: "deviceTurnedOff" }] } }; });
Java
@NotNull @Override public ExecuteResponse onExecute( @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) { ExecuteResponse.Payload payload = new ExecuteResponse.Payload(); payload.setCommands( new Commands[] { new Commands( new String[] {"123"}, "SUCCESS", new HashMap<String, Object>() { { put("on", true); put("online", true); } }, null, null), new Commands(new String[] {"456"}, "ERROR", null, "deviceTurnedOff", null) }); return new ExecuteResponse(executeRequest.getRequestId(), payload); }
למידע נוסף, עיינו במסמכי התיעוד של EXECUTE
לגבי כוונת רכישה.
תגובות סטטוס
התגובות QUERY
ו-EXECUTE
כוללות שדה status
לדיווח על התוצאה של הבקשה. כל תשובה לסטטוס יכולה לספק אחד מהערכים הבאים:
SUCCESS
: הבקשה הצליחה.OFFLINE
: מכשיר היעד במצב אופליין או שלא ניתן לגשת אליו.EXCEPTIONS
: יש בעיה או התראה שמשויכת לבקשה.ERROR
: הבקשה נכשלה עםerrorCode
התואם.
לפרטים נוספים על ERROR
וEXCEPTIONS
, תוכלו לקרוא את המאמר טיפול בשגיאות והחרגות ואת המאמר שגיאות וחריגים.