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

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

מידע נוסף מופיע בחומרי העזר של Intent QUERY.

טיפול ב-EXECUTE כוונות

בדומה ל-QUERY, כוונת רכישה יחידה יכולה לטרגט כמה מזהי מכשירים. אובייקט Intent אחד מסוג 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, אפשר לעיין בטיפול בשגיאות ובחריגים ובשגיאות וחריגים.

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