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

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

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