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

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

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