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

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