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 - اختَر المشروع الذي يطابق رقم تعريف مشروع 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. إليك مثال على كيفية تقديم الطلب في سطر الأوامر باستخدام
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 API.
- اتّبِع مستندات مطوِّري برامج 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
توفّر مكتبة برامج HomeGraph API للغة Java روابط إلى Home Graph API.
- عليك إعداد
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
في لوحة البيانات، يمكنك إجراء ما يلي:
- اختيار ملف مفتاح حسابك
- إضافة وكيل المستخدم
وبعد ذلك، انقر على List (القائمة).
جميع أجهزتك مُدرَجة. بعد تعبئة القائمة، يمكنك استخدام الزر إعادة تحميل لتعديل حالات الجهاز. وإذا تغيّرت حالة الجهاز، سيتم تمييز الصف باللون الأخضر.
الردود على الأخطاء
قد تتلقى أحد ردود الأخطاء التالية عند الاتصال Report State. وتكون هذه الردود على شكل رموز حالة HTTP.
400 Bad Request
: تعذّر على الخادم معالجة الطلب الذي أرسله العميل بسبب بنية غير صالحة. من الأسباب الشائعة لتنسيق JSON غير صحيح أو استخدامnull
بدلاً من "" في قيمة السلسلة.404 Not Found
- تعذّر العثور على المورد المطلوب ولكنه قد يكون متاحًا في المستقبل. ويعني ذلك عادةً أنه لا يمكننا العثور على الجهاز المطلوب. قد يعني هذا أيضًا أنّ حساب المستخدم غير مرتبط بخدمة Google أو أننا تلقّيناagentUserId
غير صالح. يُرجى التأكد من أنّagentUserId
يتطابق مع القيمة المقدَّمة في مزامنة، وأنّك تتعامل بشكل صحيح مع DISCONNECT.