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

إشعارات بشأن المهام المنزلية الذكية

تتيح الإشعارات لـ smart home اتخاذ إجراء باستخدام Google Assistant للتواصل مع المستخدمين بشأن الأحداث أو التغييرات المهمة ذات الصلة بالأجهزة. يمكنك تنفيذ إشعارات لتنبيه المستخدمين بشأن أحداث الجهاز في الوقت المناسب، مثلاً عندما يكون أحدهم عند الباب أو للإبلاغ عن تغيير في حالة الجهاز المطلوبة، مثلاً عندما يتم تفعيل برغي قفل الباب أو عندما يكون عالِقًا.

يمكن أن يؤدي الإجراء smart home إلى إرسال أنواع الإشعارات التالية إلى المستخدمين:

  • الإشعارات الاستباقية: تنبه المستخدم إلى حدث smart home جهاز بدون أي طلبات سابقة من المستخدمين على أجهزته، مثل جرس الباب.

  • ردود المتابعة: تأكيد لتأكيد أنّ طلب الجهاز قد نجح أو تعذّر، مثلاً عندما يتم قفل أحد الأبواب. يمكنك استخدام هذه التنبيهات لتوجيهات الأجهزة التي تستغرق بعض الوقت لإكمالها. لا تتوفّر ردود المتابعة إلا عندما يتم إرسال طلبات أوامر الجهاز من مكبرات الصوت الذكية والشاشات الذكية.

Assistant يقدّم هذه الإشعارات للمستخدمين من خلال إشعارات على مكبّرات الصوت الذكية والشاشات الذكية. تكون الإشعارات الاستباقية غير مفعّلة تلقائيًا. يمكن للمستخدمين تفعيل كل الإشعارات الاستباقية أو إيقافها من Google Home app (GHA).

الأحداث التي تؤدي إلى ظهور الإشعارات

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

تتوافق السمات التالية مع الإشعارات الاستباقية:

سمة فعاليات
رصد العناصر الأشياء التي يرصدها الجهاز، مثلاً عندما يتم رصد وجه محدَّد عند الباب على سبيل المثال: "منى ويوسف عند الباب الأمامي".
RunCycle الجهاز يُكمل دورة. على سبيل المثال: "انتهت دورة الغسّالة".
SensorState يرصد الجهاز حالة جهاز استشعار متوافقة. على سبيل المثال: "كاشِف الدخان يرصد الدخان".
التحكّم في درجة الحرارة وصول الجهاز إلى درجة الحرارة المطلوبة على سبيل المثال: "تم التدفئة مسبقًا للفرن إلى 350 درجة".
إيقاف جهاز الإنذار يُدخل النظام حالة "منبّه مسبقًا" مع عد تنازلي يبدأ بباب مفتوح.
كاميرا البث لإنشاء رابط إلى البث المباشر للكاميرا بعد رصد الجهاز أو أي حركة.
كشف الحركة "تم رصد حركة في الساعة 12 ظهرًا في 1 تموز (يوليو) 2020".

تتيح السمات التالية ردود المتابعة:

سمة فعاليات
إيقاف جهاز الإنذار بعد اكتمال أمر الجهاز action.devices.commands.ArmDisarm، ستظهر حالة الإضافة والحالة. على سبيل المثال: "تم تفعيل نظام الأمان".
قفل القفل بعد اكتمال أمر الجهاز action.devices.commands.LockUnlock، ستظهر حالة الإضافة والحالة. على سبيل المثال: "تم قفل الباب الأمامي" أو "الباب الأمامي عالِق".
التحكّم في الشبكة بعد اكتمال أمر الجهاز action.devices.commands.TestNetworkSpeed، ستظهر حالة الإضافة والحالة. على سبيل المثال: "انتهى اختبار سرعة الشبكة. إنّ سرعة التنزيل على جهاز توجيه المكتب هي 80.2 كيلوبت في الثانية حاليًا، وسرعة التحميل هي 9.3 كيلوبت في الثانية."
OpenClose بعد اكتمال أمر الجهاز action.devices.commands.OpenClose، ستظهر حالة الإضافة والحالة. على سبيل المثال: "تم فتح الباب الأمامي" أو "تعذّر فتح الباب الأمامي".
بدء الإيقاف بعد اكتمال أمر الجهاز action.devices.commands.StartStop، ستظهر حالة الإضافة والحالة. على سبيل المثال: "تم بدء المكنسة".

توفّر جميع أنواع الأجهزة إشعارات للسمات السارية.

إنشاء إشعارات لإجراءات المنزل الذكية

أضِف إشعارات إلى الإجراء smart home في هذه المراحل:

  1. أشِر إلى Google في حال تفعيل الإشعارات من تطبيق الجهاز smart home. وإذا فعَّل المستخدمون الإشعارات أو أوقفها في تطبيقك، أرسِل طلب SYNC لإعلام Google بتغيير الجهاز.
  2. عند حدوث حدث ذي صلة بالجهاز أو تغيير في الحالة يؤدي إلى ظهور إشعار، يمكنك إرسال طلب إشعار من خلال الاتصال بواجهة برمجة التطبيقات Report State reportStateAndNotification. في حال تغيير حالة الجهاز، يمكنك إرسال الحمولة لكلٍّ من الحالة والإشعار معًا في Report State ومكالمة الإشعار.

تتناول الأقسام التالية هذه الخطوات بمزيد من التفاصيل.

تحديد ما إذا كانت الإشعارات مفعَّلة في تطبيقك

يمكن للمستخدمين اختيار ما إذا كانوا يريدون تلقّي إشعارات استباقية عن طريق تفعيل هذه الميزة في GHA. في التطبيق لجهاز smart home، يمكنك أيضًا اختياريًا إضافة إمكانية إمكانية تبديل الإشعارات من الجهاز بشكل صريح، من إعدادات التطبيق.

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

في الردّ SYNC، أرسِل أحد التعديلات التالية:

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

يعرض المقتطف التالي مثالاً على كيفية ضبط استجابة المزامنة:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

إرسال طلبات إشعارات إلى Google

لتفعيل الإشعارات على Assistant، سيتم إرسال بيانات حمولة الإشعارات إلى Google Home Graph من خلال Report State واستدعاء Notification API.

تفعيل Google HomeGraph API

  1. في Google Cloud Console، انتقِل إلى صفحة HomeGraph API.

    الانتقال إلى صفحة واجهة برمجة التطبيقات HomeGraph
  2. اختَر المشروع الذي يطابق رقم تعريف مشروع smart home.
  3. انقر على تفعيل.

إنشاء مفتاح لحساب الخدمة

يُرجى اتّباع التعليمات التالية لإنشاء مفتاح حساب خدمة من Google Cloud Console:

ملاحظة: تأكّد من استخدام مشروع Google Cloud Platform الصحيح عند تنفيذ هذه الخطوات. هذا هو المشروع الذي يطابق رقم تعريف مشروعك على smart home.
  1. في Google Cloud Console، انتقِل إلى صفحة إنشاء مفتاح حساب الخدمة.

    الانتقال إلى صفحة "إنشاء مفتاح حساب الخدمة"
  2. من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
  3. في حقل اسم حساب الخدمة، أدخِل اسمًا.
  4. في حقل رقم تعريف حساب الخدمة، أدخِل رقم تعريف.
  5. من قائمة الأدوار، اختَر حسابات الخدمة > منشئ الرموز المميّزة لحساب الخدمة.

  6. بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.

  7. انقر على إنشاء. هو ملف JSON يحتوي على عمليات تنزيل المفتاح على جهاز الكمبيوتر.

إرسال الإشعار

يمكنك إجراء طلب الحصول على إشعار باستخدام واجهة برمجة التطبيقات devices.reportStateAndNotification. يجب أن يتضمّن طلب JSON السمة eventId، وهي عبارة عن معرّف فريد يتم إنشاؤه بواسطة النظام الأساسي الخاص بك للحدث الذي يؤدي إلى ظهور الإشعار. يجب أن تكون السمة eventId معرّفًا عشوائيًا يختلف في كل مرة ترسل فيها طلب إشعار.

في العنصر notifications الذي تمرِّره في طلب البيانات من واجهة برمجة التطبيقات، يمكنك تضمين قيمة priority التي تحدّد كيفية عرض الإشعار. قد يتضمن الكائن notifications حقولاً مختلفة حسب سمة الجهاز.

اتّبِع أحد المسارات التالية لضبط الحمولة واستدعاء واجهة برمجة التطبيقات:

إرسال حمولة استباقية للإشعارات

لاستدعاء واجهة برمجة التطبيقات، حدّد خيارًا من إحدى علامات التبويب التالية:

HTTP

توفّر واجهة برمجة التطبيقات Home Graph نقطة نهاية HTTP.

  1. استخدِم ملف JSON لحساب الخدمة الذي تم تنزيله لإنشاء رمز JSON المميّز للويب (JWT). لمزيد من المعلومات، يُرجى الاطّلاع على المصادقة باستخدام حساب خدمة.
  2. يمكنك الحصول على رمز الدخول عبر بروتوكول OAuth 2.0 باستخدام نطاق https://www.googleapis.com/auth/homegraph باستخدام oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. يمكنك إنشاء طلب JSON باستخدام agentUserId. إليك نموذج طلب JSON لـ Report State والإشعار:
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "ObjectDetection": {
                "priority": 0,
                "detectionTimestamp": 1534875126750,
                "objects": {
                  "named": [
                    "Alice"
                  ],
                  "unclassified": 2
                }
              }
            }
          }
        }
      }
    }
    
  6. عليك دمج Report State والرمز JSON الخاص بالإشعارات والرمز المميّز في طلب HTTP POST إلى نقطة نهاية "الرسم البياني للمنزل" من Google. إليك مثال على كيفية تقديم الطلب في سطر الأوامر باستخدام curl:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

توفّر واجهة برمجة التطبيقات Home Graph نقطة نهاية gRPC.

  1. ويمكنك الحصول على تعريف خدمة مخازن البروتوكولات المؤقتة لواجهة برمجة التطبيقات Home Graph.
  2. اتّبِع مستندات مطوِّري برامج gRPC لإنشاء رموز عميل بديلة لإحدى اللغات المعتمَدة.
  3. يجب استدعاء طريقة ReportStateAndNotification.

Node.js

يوفّر عميل Node.js في Google APIs روابط لواجهة برمجة التطبيقات Home Graph.

  1. عليك إعداد خدمة google.homegraph باستخدام بيانات الاعتماد التلقائية للتطبيق.
  2. يمكنك استدعاء الطريقة reportStateAndNotification باستخدام ReportStateAndNotificationRequest. تعرض القيمة Promise مع ReportStateAndNotificationResponse.
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

لغة Java

توفّر مكتبة برامج واجهة برمجة التطبيقات HomeGraph API للغة روابط تؤدي إلى واجهة برمجة التطبيقات Home Graph.

  1. عليك إعداد HomeGraphApiService باستخدام بيانات الاعتماد التلقائية للتطبيق.
  2. يمكنك استدعاء طريقة reportStateAndNotification باستخدام ReportStateAndNotificationRequest. تعرض ReportStateAndNotificationResponse.
// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Build device notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
    
إرسال حمولة ردّ متابعة

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

يعرض المقتطف التالي مثالاً على حمولة طلب EXECUTE مع حقل followUpToken.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

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

لاستدعاء واجهة برمجة التطبيقات، حدّد خيارًا من إحدى علامات التبويب التالية:

HTTP

توفّر واجهة برمجة التطبيقات Home Graph نقطة نهاية HTTP.

  1. استخدِم ملف JSON لحساب الخدمة الذي تم تنزيله لإنشاء رمز JSON المميّز للويب (JWT). لمزيد من المعلومات، يُرجى الاطّلاع على المصادقة باستخدام حساب خدمة.
  2. يمكنك الحصول على رمز الدخول عبر بروتوكول OAuth 2.0 باستخدام نطاق https://www.googleapis.com/auth/homegraph باستخدام oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. يمكنك إنشاء طلب JSON باستخدام agentUserId. إليك نموذج طلب JSON لـ Report State والإشعار:
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "NetworkControl": {
                "priority": 0,
                "followUpResponse": {
                  "status": "SUCCESS",
                  "followUpToken": "PLACEHOLDER",
                  "networkDownloadSpeedMbps": 23.3,
                  "networkUploadSpeedMbps": 10.2
                }
              }
            }
          }
        }
      }
    }
    
  6. عليك دمج Report State والرمز JSON الخاص بالإشعارات والرمز المميّز في طلب HTTP POST إلى نقطة نهاية "الرسم البياني للمنزل" من Google. إليك مثال على كيفية تقديم الطلب في سطر الأوامر باستخدام curl:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

توفّر واجهة برمجة تطبيقات Home Graph نقطة نهاية gRPC.

  1. ويمكنك الحصول على تعريف خدمة مخازن البروتوكولات المؤقتة لواجهة برمجة التطبيقات Home Graph.
  2. اتّبِع مستندات مطوِّري برامج gRPC لإنشاء رموز عميل بديلة لإحدى اللغات المعتمَدة.
  3. يجب استدعاء طريقة ReportStateAndNotification.

Node.js

يوفّر عميل Node.js في Google APIs روابط لواجهة برمجة التطبيقات Home Graph.

  1. عليك إعداد خدمة google.homegraph باستخدام بيانات الاعتماد التلقائية للتطبيق.
  2. يمكنك استدعاء الطريقة reportStateAndNotification باستخدام ReportStateAndNotificationRequest. تعرض القيمة Promise مع ReportStateAndNotificationResponse.
const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});
    

لغة Java

توفّر مكتبة برامج واجهة برمجة التطبيقات HomeGraph API للغة روابط تؤدي إلى واجهة برمجة التطبيقات Home Graph.

  1. إعداد HomeGraphApiService باستخدام بيانات الاعتماد التلقائية للتطبيق
  2. يمكنك استدعاء طريقة reportStateAndNotification باستخدام ReportStateAndNotificationRequest. عرض ReportStateAndNotificationResponse
// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);
    

التسجيل

وتتيح الإشعارات تسجيل الأحداث كما هو موضَّح في سجلّات أحداث الوصول من خلال Cloud Logging. تُعدّ هذه السجلّات مفيدة لاختبار جودة الإشعارات والحفاظ عليها ضمن الإجراء الذي تتخذه.

في ما يلي مخطّط إدخال notificationLog:

الخاصية الوصف
requestId رقم تعريف طلب الإشعار.
structName اسم بنية الإشعار، مثل "ObjectDetection".
status تشير إلى حالة الإشعار.

يتضمّن الحقل status حالات مختلفة قد تشير إلى حدوث أخطاء في حمولة الإشعارات. وقد يكون بعضها متاحًا فقط في المهام التي لم يتم إطلاقها لمرحلة الإنتاج.

تشمل أمثلة الأمثلة ما يلي:

الحالة الوصف
EVENT_ID_MISSING يشير الحقل إلى أنّ حقل eventId المطلوب غير متوفّر.
PRIORITY_MISSING يشير الحقل إلى عدم توفّر الحقل priority.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE تشير إلى أنّ السمة notificationSupportedByAgent الخاصة بالجهاز الذي تم الإبلاغ عنه والمقدَّمة في SYNC هي غير صحيحة.
NOTIFICATION_ENABLED_BY_USER_FALSE يشير إلى أنّ المستخدم لم يفعّل الإشعارات على جهاز الإشعار في GHA. لا تتوفّر هذه الحالة إلا على الإجراءات التي لم يتم إطلاقها لمرحلة الإنتاج.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE يشير إلى أن المستخدم لم يخصص الجهاز المُرسِل لإرسال إشعار إلى المنزل/البنية. لا تتوفّر هذه الحالة إلا على الإجراءات التي لم يتم إطلاقها لمرحلة الإنتاج.

بالإضافة إلى الحالات العامة التي يمكن أن تنطبق على جميع الإشعارات، قد يتضمّن الحقل status أيضًا حالات متعلقة بالسمات حيثما ينطبق ذلك (مثل OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).