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

כשמשתמשים מקיימים אינטראקציה עם Google Assistant כדי לשאול על המצב הנוכחי של מכשיר, מתקבלת כוונה (intent) של action.devices.QUERY ב-fulfillment, שמכילה רשימה של מזהי מכשירים (כפי שסופקו בתגובה של 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,
        "status": "SUCCESS"
      },
      "456": {
        "on": true,
        "online": true,
        "status": "SUCCESS",
        "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,
          status: "SUCCESS"
        },
        456: {
          on: true,
          online: true,
          status: "SUCCESS",
          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("status", "SUCCESS");
                }
              });
          put(
              "456",
              new HashMap<String, Object>() {
                {
                  put("on", true);
                  put("online", true);
                  put("status", "SUCCESS");
                  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, אפשר לעיין במאמרים טיפול בשגיאות ובחריגות ושגיאות וחריגות.

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