مرحبًا بك في "مركز مطوّري Google Home"، الوجهة الجديدة لتعلّم كيفية تطوير المهام المنزلية الذكية. ملاحظة: ستواصل إنشاء إجراءات في "وحدة تحكّم المهام".

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

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

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