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

כשמשתמשים מקיימים אינטראקציה עם Google Assistant כדי לשלוח שאילתה לגבי המצב הנוכחי של המכשיר, במילוי הבקשה מתקבלת Intent של action.devices.QUERY שמכיל רשימה של מזהי מכשירים (כפי שסופק על ידי התשובה שלכם ל-SYNC). מילוי הבקשה מקבל Intent מסוג action.devices.EXECUTE כשמשתמשים שולחים פקודות אל Assistant כדי לשלוט במכשיר.

טיפול ב-QUERY אובייקטים מסוג Intent

התגובה 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 אובייקטים מסוג Intent

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

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