Report State ميزة مهمة تسمح
للإجراء Home بالإبلاغ بشكل استباقي عن أحدث حالة
لجهاز المستخدم حتى
Google Home Graph
rather than waiting for a
QUERY
intent.
تُبلِغ Report State Google عن حالات أجهزة المستخدمين مع agentUserId
المحدّدة المرتبطة بها (تم إرسالها في طلب SYNC
الأصلي). الوقت المناسب
Google Assistant
wants to take an action
that requires understanding the current state of a device, it can simply look
up the state information in the
Home Graph instead
of issuing a QUERY
intent to various third-party clouds prior to issuing the
EXECUTE
intent.
بدون استخدام
Report State، مع الأخذ في الاعتبار المصابيح من عدّة مزوّدين في غرفة المعيشة، يتطلّب الأمر Ok Google, Brighting my المعيشة في غرفة النوم حلّ عدة أغراض من QUERY
تم إرسالها إلى عدّة سحب، بدلاً من البحث عن قيم السطوع الحالية بناءً على ما تم الإبلاغ عنه سابقًا. لتحقيق أفضل تجربة للمستخدم،
يحتاج Assistant إلى معرفة الحالة الحالية للجهاز،
بدون الحاجة إلى الذهاب ذهابًا وإيابًا إلى الجهاز.
بعد SYNC
الأوليّ للجهاز، تُرسل المنصة النظام QUERY
intent
الذي يجمع حالة الجهاز لتعبئة
Home Graph.
بعد هذه النقطة،
لن يخزِّن Home Graph إلا الولاية التي يتم إرسالها مع
Report State.
عند استدعاء
Report State، احرص على تقديم
بيانات حالة كاملة لسمة معينة.
تحدّث الدالة Home Graph الحالات
على أساس كل سمة وتحلّ محلّ كل البيانات لهذه السمة عند إجراء
طلب Report State. على سبيل المثال، إذا كنت تبلّغ عن
السمة StartStop، يجب أن تتضمّن الحمولة القيم لكل من isRunning
وisPaused
.
البدء
لتطبيق Report State، اتبع الخطوات التالية:
تفعيل Google HomeGraph API
-
في Google Cloud Console , go to the HomeGraph API page.
الانتقال إلى صفحة واجهة برمجة التطبيقات HomeGraph - اختَر المشروع الذي يتطابق مع smart home project ID.
- انقر على تفعيل.
إنشاء مفتاح حساب خدمة
اتبع هذه التعليمات لإنشاء مفتاح حساب خدمة من 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.
- الحصول على تعريف خدمة مخازن البروتوكول المؤقت لواجهة برمجة تطبيقات الرسم البياني الرئيسي.
- اتّبِع وثائق مطوّر برامج 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 للغة جافا روابط إلى واجهة برمجة تطبيقات 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
على لوحة البيانات، يمكنك إجراء ما يلي:
- اختيار ملف مفتاح الحساب
- إضافة رقم تعريف وكيل المستخدم
وبعد ذلك، انقر على قائمة.
تم إدراج جميع أجهزتك. بعد ملء القائمة، يمكنك استخدام الزر تحديث لتحديث حالات الجهاز. إذا كان هناك تغيير في حالة الجهاز، فسيتم تمييز الصف باللون الأخضر.
إجابات الأخطاء
قد تتلقّى أحد ردود الأخطاء التالية عند الاتصال بالرقم Report State. تأتي هذه الاستجابات في شكل رموز حالة HTTP.
400 Bad Request
- تعذر على الخادم معالجة الطلب الذي أرسله البرنامج بسبب بنية غير صالحة. وتشمل الأسباب الشائعة تلف ملف JSON أو استخدامnull
بدلاً من "" في قيمة سلسلة.404 Not Found
- تعذر العثور على المورد المطلوب ولكنه قد يكون متاحًا في المستقبل. يعني هذا عادةً أنه لا يمكننا العثور على الجهاز المطلوب. وقد يعني هذا أيضًا أن حساب المستخدم غير مرتبط بـ Google أو أننا تلقيناagentUserId
غير صالح. تأكَّد من أنّagentUserId
يتطابق مع القيمة المقدّمة في استجابة مزامنة، ومن أنّك تتولّى معالجة نوايا إلغاء الربط بشكل صحيح.