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

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

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