يؤدي طلب المزامنة إلى تنفيذ طلب SYNC
لتنفيذ أي من مستخدمي Google
باستخدام أجهزة تتضمن
agentUserId
المحدد المرتبط بها (والذي أرسلته في طلب المزامنة الأصلي). يتيح لك ذلك تحديث أجهزة المستخدمين
بدون إلغاء ربط حساباتهم وإعادة ربطها سيتلقّى جميع المستخدمين المرتبطين
بهذا المعرّف طلب SYNC
.
يجب تقديم طلب "SYNC
":
- إذا أضاف المستخدم جهازًا جديدًا.
- إذا أزال المستخدم جهازًا حاليًا.
- إذا أعاد المستخدم تسمية جهاز حالي.
- إذا استخدمت نوع جهاز جديدًا أو سمة أو ميزة جديدة للجهاز.
البدء
لتنفيذ طلب مزامنة، اتبع الخطوات التالية:
تفعيل 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
{ "agentUserId": "user-123" }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:requestSync"
gRPC
توفّر واجهة برمجة التطبيقات Home Graph API نقطة نهاية gRPC.
- الحصول على تعريف خدمة المخزن المؤقت للبروتوكول لواجهة برمجة تطبيقات Home Graph
- اتّبِع مستندات مطوّري برامج gRPC لإنشاء رموز بديلة للعميل لإحدى اللغات المعتمَدة.
- عليك استدعاء طريقة RequestSync.
Node.js
يوفّر عميل Node.js API من Google عمليات ربط لواجهة برمجة تطبيقات Home Graph.
- ابدأ بإعداد خدمة
google.homegraph
باستخدام بيانات الاعتماد التلقائية للتطبيق. - استدعِ الطريقة
requestSync
باستخدام RequestSyncDevicesRequest. يعرض الحقلPromise
مع الحقل RequestSyncDevicesResponse فارغ.
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.requestSync({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', async: false } });
Java
توفّر مكتبة برامج HomeGraph API للغة Java عمليات ربط لواجهة برمجة تطبيقات Home Graph.
- عليك إعداد
HomeGraphApiService
باستخدام بيانات الاعتماد التلقائية للتطبيق. - يمكنك استدعاء الطريقة
requestSync
باستخدامRequestSyncDevicesRequest
. ويعرض حقل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(); // Request sync. RequestSyncDevicesRequest request = new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false); homegraphService.devices().requestSync(request);
الردود على الأخطاء
قد تتلقى أحد الردود التالية على رسائل الخطأ عند الاتصال بـ "طلب المزامنة". وتكون هذه الاستجابات في شكل رموز حالة HTTP.
400 Bad Request
- تعذّر على الخادم معالجة الطلب الذي أرسله العميل بسبب بنية غير صالحة. تشمل الأسباب الشائعة تنسيق JSON غير صحيح أو استخدامnull
بدلاً من "" لقيمة سلسلة.403 Forbidden
- تعذّر على الخادم معالجة طلبagentUserId
المحدَّد بسبب حدوث خطأ أثناء إعادة تحميل الرمز المميّز. تأكَّد من استجابة نقطة نهاية OAuth بشكل صحيح لإعادة تحميل طلبات الرمز المميّز والتحقّق من حالة ربط حساب المستخدم.404 Not Found
- تعذّر العثور على المورد المطلوب، ولكن قد يكون متاحًا في المستقبل. يعني ذلك عادةً أنّ حساب المستخدم غير مرتبط بحساب Google أو أنّنا تلقّينا رمزagentUserId
غير صالح. تأكَّد من أنّagentUserId
تطابق القيمة المقدّمة في استجابة مزامنة، ومن أنّك تتعامل مع أهداف إلغاء الربط بشكل صحيح.429 Too Many Requests
- تم تجاوز الحد الأقصى لعدد طلبات المزامنة المتزامنة فيagentUserId
المحدد. لا يجوز للمتصل إصدار أكثر من طلب مزامنة متزامن واحد ما لم يتم ضبط علامةasync
على "صحيح".