تحديد البيانات ومزامنتها

بعد إنشاء إجراء smart home، تتمثّل الخطوة التالية في إضافة وظيفة في عملية التنفيذ لمعالجة أهداف المنزل المزوّد بأجهزة ذكية وعرض الاستجابات التي يتعرّف عليها تطبيق Google Assistant.

تحديد هوية المستخدم

يرسل Assistant طلبات إلى تنفيذ إجراء smart home باستخدام رمز الدخول الذي يوفّره خادم OAuth 2.0 في عنوان Authorization.

POST /fulfillment HTTP/1.1
Host: smarthome.example.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

قبل الاستجابة لأي طلبات، يجب أن يتحقّق منطق التنفيذ من صلاحية بيانات اعتماد الرمز المميّز هذه وتحديد حساب المستخدم المرتبط بها. إذا كان رمز الدخول غير صالح، من المفترض أن تعرض عملية التنفيذ خطأ HTTP 401 Unauthorized.

إدراج الأجهزة وإمكاناتها

الأدوات المُقترَحة لهذه المهمة

يرسل Assistant هدف action.devices.SYNC إلى عملية التنفيذ لطلب قائمة بالأجهزة المرتبطة بالمستخدم المعني وإمكاناته. يجب أن تعرض عملية التنفيذ معرّفًا فريدًا لكل مستخدم في الحقل agentUserId في الردّ SYNC. يجب أن يكون هذا المعرّف قيمة غير قابلة للتغيير لتمثيل المستخدم في خدمة السحابة لديك. لا يُنصح بتقديم عناوين بريد إلكتروني أو سمات أخرى استنادًا إلى الإعدادات التي يمكن للمستخدم تغييرها.

يتضمّن الحقل devices في استجابة SYNC جميع الأجهزة التي صرّح المستخدم Assistant بالوصول إليها، والأنواع والسمات التي تتوافق معه، والسمات المطلوبة لضبط سلوك السمة على ذلك الجهاز تحديدًا.

يتمّ تشغيل الغرض من SYNC أثناء ربط الحساب أو عندما يعيد المستخدم مزامنة أجهزته يدويًا. في حال تغيير قائمة المستخدمين للأجهزة أو السمات المتوافقة أو قيم السمات، يمكنك استخدام طلب المزامنة لتشغيل هدف SYNC جديد وإرسال تقرير بالتحديثات إلى Google.

طلب
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.OUTLET",
        "traits": [
          "action.devices.traits.OnOff"
        ],
        "name": {
          "defaultNames": [
            "My Outlet 1234"
          ],
          "name": "Night light",
          "nicknames": [
            "wall plug"
          ]
        },
        "willReportState": false,
        "roomHint": "kitchen",
        "deviceInfo": {
          "manufacturer": "lights-out-inc",
          "model": "hs1234",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        },
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id"
          }
        ],
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      },
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting"
        ],
        "name": {
          "defaultNames": [
            "lights out inc. bulb A19 color hyperglow"
          ],
          "name": "lamp1",
          "nicknames": [
            "reading lamp"
          ]
        },
        "willReportState": false,
        "roomHint": "office",
        "attributes": {
          "colorModel": "rgb",
          "colorTemperatureRange": {
            "temperatureMinK": 2000,
            "temperatureMaxK": 9000
          },
          "commandOnlyColorSetting": false
        },
        "deviceInfo": {
          "manufacturer": "lights out inc.",
          "model": "hg11",
          "hwVersion": "1.2",
          "swVersion": "5.4"
        },
        "customData": {
          "fooValue": 12,
          "barValue": false,
          "bazValue": "bar"
        }
      }
    ]
  }
}
Node.js
const {smarthome} = require('actions-on-google');
const app = smarthome();
// ...
app.onSync((body, headers) => {
  // TODO Get devices for user
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: "1836.15267389",
      devices: [{
        id: "123",
        type: "action.devices.types.OUTLET",
        traits: [
          "action.devices.traits.OnOff"
        ],
        name: {
          defaultNames: ["My Outlet 1234"],
          name: "Night light",
          nicknames: ["wall plug"]
        },
        willReportState: false,
        roomHint: "kitchen",
        deviceInfo: {
          manufacturer: "lights-out-inc",
          model: "hs1234",
          hwVersion: "3.2",
          swVersion: "11.4"
        },
        otherDeviceIds: [{
          deviceId: "local-device-id"
        }],
        customData: {
          fooValue: 74,
          barValue: true,
          bazValue: "foo"
        }
      }, {
        id: "456",
        type: "action.devices.types.LIGHT",
        traits: [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting"
        ],
        name: {
          defaultNames: ["lights out inc. bulb A19 color hyperglow"],
          name: "lamp1",
          nicknames: ["reading lamp"]
        },
        willReportState: false,
        roomHint: "office",
        attributes: {
          colorModel: 'rgb',
          colorTemperatureRange: {
            temperatureMinK: 2000,
            temperatureMaxK: 9000
          },
          commandOnlyColorSetting: false
        },
        deviceInfo: {
          manufacturer: "lights out inc.",
          model: "hg11",
          hwVersion: "1.2",
          swVersion: "5.4"
        },
        customData: {
          fooValue: 12,
          barValue: false,
          bazValue: "bar"
        }
      }]
    }
  };
});
Java
@NotNull
@Override
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> map) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");
  payload.setDevices(
      new Device[] {
        new Device.Builder()
            .setId("123")
            .setType("action.devices.types.OUTLET")
            .addTrait("action.devices.traits.OnOff")
            .setName(
                Collections.singletonList("My Outlet 1234"),
                "Night light",
                Collections.singletonList("Wall plug"))
            .setWillReportState(true)
            .setDeviceInfo("lights-out-inc", "hs1234", "3.2", "11.4")
            .setCustomData(
                new JSONObject()
                    .put("fooValue", 74)
                    .put("barValue", true)
                    .put("bazValue", "foo"))
            .build(),
        new Device.Builder()
            .setId("456")
            .setType("action.devices.types.LIGHT")
            .addTrait("action.devices.traits.OnOff")
            .addTrait("action.devices.traits.Brightness")
            .addTrait("action.devices.traits.ColorTemperature")
            .addTrait("action.devices.traits.ColorSpectrum")
            .setName(
                Collections.singletonList("Lights Out Inc. bulb A19 color hyperglow"),
                "Lamp",
                Collections.singletonList("Reading lamp"))
            .setWillReportState(true)
            .setDeviceInfo("Lights Out Inc.", "hg11", "1.2", "5.4")
            .setCustomData(
                new JSONObject()
                    .put("fooValue", 12)
                    .put("barValue", false)
                    .put("bazValue", "bar"))
            .build(),
      });
  return new SyncResponse(syncRequest.getRequestId(), payload);
}

لمزيد من المعلومات، اطّلِع على المستندات المرجعية للغرض من SYNC.