طلب البحث والتنفيذ

عندما يتفاعل المستخدمون مع 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,
        "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، اطّلِع على التعامل مع الأخطاء والاستثناءات و الأخطاء والاستثناءات لمزيد من التفاصيل.

السابق
تحديد البيانات ومزامنتها
التالي
قطع الاتصال