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

عندما يتفاعل المستخدمون مع 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.

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

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

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

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

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