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

عندما يتفاعل المستخدمون مع Google Assistant للاستعلام عن الحالة الحالية لجهاز، يتلقّى الإجراء الذي تقدّمه action.devices.QUERY نية تحتوي على قائمة بأرقام تعريف الأجهزة (على النحو المقدَّم في استجابة SYNC). يتلقّى الإجراء الذي توفّره action.devices.EXECUTE 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 intent.

الردود على الحالة

تتضمّن استجابتَي QUERY وEXECUTE حقل status للإبلاغ عن نتيجة الطلب. يمكن أن يقدّم كلّ استجابة حالة إحدى القيمة التالية:

  • SUCCESS: تم إرسال الطلب بنجاح.
  • OFFLINE: الجهاز المستهدَف غير متصل بالإنترنت أو يتعذّر الوصول إليه بأي شكل آخر.
  • EXCEPTIONS: هناك مشكلة أو تنبيه مرتبط بالطلب.
  • ERROR: تعذّر إكمال الطلب بسبب errorCode المقابل.

بالنسبة إلى ERROR وEXCEPTIONS، اطّلِع على معالجة الأخطاء والاستثناءات و الأخطاء والاستثناءات لمزيد من التفاصيل.

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