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

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

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