Report State هي ميزة مهمة تسمح للإجراء Home بالإبلاغ بشكل استباقي عن أحدث حالة لجهاز
المستخدم إلى Google Home Graph بدلاً من انتظار إجراء
QUERY
intent.
تُبلِغ Report State Google عن حالات أجهزة المستخدمين
التي تتضمّن السمة agentUserId
المحددة المرتبطة بها (المُرسَلة في طلب
SYNC
الأصلي). عندما تريد خدمة Google Assistant تنفيذ إجراء يتطلّب معرفة الحالة الحالية للجهاز، بإمكانها ببساطة البحث عن معلومات الحالة في Home Graph بدلاً من إصدار intent 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 API من Google عمليات ربط لواجهة برمجة تطبيقات 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.
- عليك إعداد
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
تطابق القيمة المقدّمة في استجابة المزامنة، ومن أنّك تتع��مل مع أغراض إلغاء الربط بشكل صحيح.