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

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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

عندما يتفاعل المستخدمون مع Google Assistant to query the current state of a device, your fulfillment receives an action.devices.QUERY intent containing a list of device IDs (as provided by your SYNC response). Your fulfillment receives an action.devices.EXECUTE intent when users send commands to Assistant to control your device.

معالجة أهداف 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
          }
        }
      }
    }
  };
});
جافا
@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);
}

لمزيد من المعلومات، اطّلع على الوثائق المرجعية لأغراض intent في QUERY.

معالجة أهداف EXECUTE

على غرار QUERY، يمكن لهدف واحد استهداف أرقام تعريف متعددة للأجهزة. قد يحتوي هدف EXECUTE واحد أيضًا على عدة أوامر مختلفة يتم منحها لمجموعة من الأجهزة. على سبيل المثال، قد يكون هدف intent هو ضبط السطوع واللون على مجموعة من المصابيح، أو تعيين أضواء متعددة على لون مختلف. من المفترض أن يعرض ردك EXECUTE الحالة الجديدة للجهاز بعد التنفيذ.

استخدِم Report State عندما تتغير حالة جهاز المستخدمين. على سبيل المثال، بسبب نية EXECUTE أو تغيير محلي (مثل قلب مفتاح إضاءة يدويًا). يؤدي هذا إلى الاحتفاظ Google Home Graph synchronized with your cloud service.

طلب
{
    "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"
      }]
    }
  };
});
جافا
@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، يُرجى الاطّلاع على التعامل مع الأخطاء والاستثناءات و الأخطاء والاستثناءات للحصول على مزيد من التفاصيل.