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

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

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