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

عندما يتفاعل المستخدمون مع 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 intent أو تغيير في الحالة المحلية (مثل قلب مفتاح الإضاءة يدويًا). يؤدي ذلك إلى إبقاء 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، يُرجى الاطّلاع على معالجة الأخطاء والاستثناءات و الأخطاء والاستثناءات لمزيد من التفاصيل.

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