שאילתה וביצוע

כשמשתמשים מקיימים אינטראקציה עם Google Assistant כדי לשלוח שאילתה לגבי המצב הנוכחי של מכשיר, המערכת מקבלת action.devices.QUERY כוונה (intent) שמכילה רשימה של מזהי המכשירים (כפי שצוין בתשובה שלכם ל-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 עשויה גם להכיל כמה פקודות נפרדות שניתנות לקבוצה של מכשירים. לדוגמה, כוונת שימוש מופעלת עשויה להגדיר גם את הבהירות וגם את הצבע של קבוצת נורות, או להגדיר כמה נורות עם צבע שונה לכל אחת. התשובה 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, ראו טיפול בשגיאות ובחריגות ושגיאות וחריגות.

הקודם
זיהוי וסנכרון
הבא
ניתוק