إنّ ميزة Report State هي ميزة مهمّة تسمح لإجراء Home بالإبلاغ بشكل استباقي عن الحالة الأخيرة لجهاز المستخدم إلى Google Home Graph بدلاً من انتظار إجراء QUERY
.
ترسِل ميزة Report State تقارير إلى Google بشأن حالات أجهزة المستخدمين
ذات agentUserId
المحدَّد المرتبط بها (تم إرسالها في طلب
SYNC
الأصلي). عندما يريد Google Assistant اتخاذ إجراء
يتطلب معرفة الحالة الراهنة للجهاز، يمكن ببساطة
الاطّلاع على معلومات الولاية في Home Graph بدلاً من
إصدار نموذج QUERY
للسحابة الإلكترونية التابعة لجهات خارجية قبل إصدار
EXECUTE
الغرض.
بدون استخدام Report State، إذا توفّرت مصابيح من عدة مقدّمي خدمات في غرفة المعيشة، يتطلب الأمر Ok Google، أريد زيادة سطوع غرفة المعيشة حلّ العديد من أهداف QUERY
المرسلة إلى غيوم متعدّدة، بدلاً من البحث ببساطة عن قيم السطوع الحالية بناءً على ما تم الإبلاغ عنه سابقًا. للحصول على أفضل تجربة للمستخدم،
يجب أن يكون لدى Assistant الحالة الراهنة للجهاز،
بدون الحاجة إلى إرسال البيانات ذهابًا وإيابًا إلى الجهاز.
استنادًا إلى السمة SYNC
الأولية لأحد الأجهزة، ترسل الأنظمة الأساسية هدف QUERY
الذي يجمع حالة الجهاز لتعبئة Home Graph.
بعد هذه المرحلة، لا يحفظ Home Graph سوى الحالة المُرسَلة
مع Report State.
عند الاتصال بـ Report State، تأكد من تقديم
بيانات حالة كاملة لسمة معينة. تنص تعديلات Home Graph على أساس كل سمة وتستبدل جميع بيانات هذه السمة عند إجراء طلب Report State. على سبيل المثال، إذا كنت تُبلغ عن الحالة لسمة StartStop، يجب أن تتضمن الحمولة قيم لكل من isRunning
وisPaused
.
البدء
لتنفيذ ميزة Report State، يُرجى اتّباع الخطوات التالية:
تفعيل Google HomeGraph API
-
في Google Cloud Console، انتقِل إلى صفحة HomeGraph API.
الانتقال إلى صفحة HomeGraph API - اختَر المشروع الذي يتطابق مع رقم تعريف مشروع smart home.
- انقر على تفعيل.
إنشاء مفتاح لحساب الخدمة
اتّبِع هذه التعليمات لإنشاء مفتاح حساب خدمة من Google Cloud Console:
-
في Google Cloud Console، انتقِل إلى صفحة إنشاء مفتاح حساب الخدمة.
الانتقال إلى صفحة "إنشاء مفتاح حساب الخدمة" - من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
- في الحقل اسم حساب الخدمة، أدخِل اسمًا.
- في الحقل رقم تعريف حساب الخدمة، أدخِل معرِّفًا.
من قائمة الدور، اختَر حسابات الخدمة > منشئ الرمز المميَّز لحساب الخدمة.
بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.
- انقر على إنشاء. ملف JSON يحتوي على المفتاح الذي يتم تنزيله على جهاز الكمبيوتر.
استدعاء واجهة برمجة التطبيقات
حدِّد خيارًا من علامات التبويب أدناه:
HTTP
توفر Home Graph نقطة نهاية HTTP
- يمكنك استخدام ملف JSON لحساب الخدمة الذي تم تنزيله لإنشاء رمز JSON المميّز للويب (JWT). ولمزيد من المعلومات، يُرجى الاطّلاع على المصادقة باستخدام حساب الخدمة.
- يمكنك الحصول على رمز دخول OAuth 2.0 من خلال
نطاق
https://www.googleapis.com/auth/homegraph
باستخدام oauth2l: - أنشِئ طلب JSON باستخدام
agentUserId
. إليك نموذج طلب JSON لحالة التقرير والإشعار: - يمكنك دمج حالة التقرير والإشعار JSON والرمز المميز في طلب HTTP POST في نقطة نهاية Google Home Graph. في ما يلي مثال على كيفية إنشاء الطلب في سطر الأوامر باستخدام
curl
كاختبار:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
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
- يمكنك الحصول على تعريف خدمة المخازن المؤقتة للبروتوكول لواجهة برمجة التطبيقات Home Graph.
- اتّبِع مستندات المطوِّر الخاصة بـ gRPC لإنشاء رموز برمجية للعميل لإحدى اللغات المعتمَدة.
- عليك استدعاء الإجراء ReportStateAndNotification.
Node.js
يوفر عميل Node.js في Google APIs روابط لواجهة برمجة تطبيقات Home Graph.
- اضبط خدمة
google.homegraph
باستخدام بيانات الاعتماد التلقائية للتطبيق. - عليك استدعاء الإجراء
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', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { states: { "PLACEHOLDER-DEVICE-ID": { on: true } } } } } });
Java
توفّر مكتبة برامج Home Graph API للغة Java روابط لواجهة برمجة التطبيقات Home Graph.
- اضبط
HomeGraphApiService
باستخدام بيانات الاعتماد التلقائية للتطبيق. - عليك استدعاء طريقة
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 state payload. Map<?, ?> states = Map.of("on", true); // Report device state. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states)))); homegraphService.devices().reportStateAndNotification(request); }
حالة تقرير الاختبار
من أجل تجهيز الإجراء للحصول على الاعتماد، من المهم اختبار Report State.
لإجراء ذلك، ننصحك باستخدام أداة عارض Home Graph، وهي تطبيق ويب مستقل لا يتطلب تنزيله أو نشره.
لا تزال لوحة بيانات "Report State" متوفّرة، ولكن تم إيقافها نهائيًا ولم تعد متاحة.
لوحة البيانات الخاصة بحالة التقارير
المتطلبات الأساسية
حتى تتمكّن من اختبار الإجراء، يجب أن يكون لديك مفتاح
حساب الخدمة وagentUserId
. إذا سبق لك الحصول على مفتاح حساب الخدمة وagentUserId
، يُرجى الاطّلاع على نشر Report Stateلوحة بيانات.
نشر لوحة بيانات "حالة التقرير"
بعد الحصول على مفتاح حساب الخدمة و"رقم تعريف المستخدم للوكيل" لمشروعك،
يمكنك تنزيل أحدث إصدار ونشره من
Report State
لوحة البيانات.
بعد تنزيل أحدث إصدار، اتّبِع التعليمات الواردة في ملف README.MD
المدرَج.
بعد نشر لوحة بيانات Report State، يمكنك الوصول إلى لوحة البيانات من عنوان URL التالي (استبدِل your_project_id برقم تعريف المشروع):
http://<your-project-id>.appspot.com
في لوحة البيانات، قم بما يلي:
- اختيار ملف مفتاح حسابك
- إضافة رقم تعريف الوكيل (UserId) الخاص بك
بعد ذلك، انقر على القائمة.
جميع أجهزتك مُدرجة. بعد تعبئة القائمة، يمكنك استخدام الزر إعادة تحميل لتعديل حالات الجهاز. إذا كان هناك تغيير في حالة الجهاز، فسيتم تمييز الصف باللون الأخضر.
الردود على الأخطاء
قد تتلقى أحد ردود الخطأ التالية عند اتصال Report State. تأتي هذه الاستجابات في شكل رموز حالة HTTP.
400 Bad Request
- لم يتمكّن الخادم من معالجة الطلب الذي أرسله العميل بسبب بنية غير صالحة. تشمل الأسباب الشائعة تنسيق JSON غير صحيح أو استخدامnull
بدلاً من "" لقيمة سلسلة.404 Not Found
- تعذّر العثور على المورد المطلوب ولكنه قد يكون متاحًا في المستقبل. يعني ذلك عادةً أنه لا يمكننا العثور على الجهاز المطلوب. قد يعني ذلك أيضًا أنّ حساب المستخدم غير مرتبط بـ Google أو أنّنا تلقّيناagentUserId
غير صالح. تأكَّد من أنّagentUserId
تطابق القيمة المقدّمة في استجابة SYNC، ومن أنك تتعامل بشكل صحيح مع أغراض إلغاء الربط.