يشغّل طلب المزامنة طلب تنفيذ SYNC
لأي مستخدم Google
لديه أجهزة مرتبطة
agentUserId
بها (التي أرسلتها
في طلب المزامنة الأصلي). ويسمح لك ذلك بتحديث أجهزة المستخدمين
بدون إلغاء ربط حساباتهم وإعادة ربطها. سيتلقّى كل المستخدمين المرتبطين بهذا المعرّف طلب SYNC
.
يجب تشغيل طلب SYNC
:
- إذا أضاف المستخدم جهازًا جديدًا.
- إذا أزال المستخدم جهازًا حاليًا.
- إذا أعاد المستخدم تسمية جهاز حالي.
- إذا نفّذت نوعًا جديدًا من الأجهزة أو سمة جديدة أو أضفت ميزة جديدة على الجهاز،
البدء
لتنفيذ "مزامنة الطلبات"، اتّبِع الخطوات التالية:
تفعيل Google HomeGraph API
-
في Google Cloud Console، انتقِل إلى صفحة HomeGraph API.
الانتقال إلى صفحة واجهة برمجة التطبيقات HomeGraph - اختَر المشروع الذي يطابق رقم تعريف مشروع smart home.
- انقر على تفعيل.
إنشاء مفتاح لحساب الخدمة
يُرجى اتّباع التعليمات التالية لإنشاء مفتاح حساب خدمة من Google Cloud Console:
-
في Google Cloud Console، انتقِل إلى صفحة إنشاء مفتاح حساب الخدمة.
الانتقال إلى صفحة "إنشاء مفتاح حساب الخدمة" - من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
- في حقل اسم حساب الخدمة، أدخِل اسمًا.
- في حقل رقم تعريف حساب الخدمة، أدخِل رقم تعريف.
من قائمة الأدوار، اختَر حسابات الخدمة > منشئ الرموز المميّزة لحساب الخدمة.
بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.
- انقر على إنشاء. هو ملف JSON يحتوي على عمليات تنزيل المفتاح على جهاز الكمبيوتر.
طلب بيانات من واجهة برمجة التطبيقات
HTTP
توفّر واجهة برمجة التطبيقات Home Graph API نقطة نهاية 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
{ "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 API.
- اتّبِع مستندات مطوِّري برامج gRPC لإنشاء رموز عميل بديلة لإحدى اللغات المعتمَدة.
- يجب استدعاء طريقة RequestSync.
Node.js
يوفّر برنامج Node.js في Google APIs روابط لواجهة برمجة التطبيقات Home Graph API.
- عليك إعداد خدمة
google.homegraph
باستخدام بيانات الاعتماد التلقائية للتطبيق. - يمكنك استدعاء الطريقة
requestSync
باستخدام RequestSyncDeviceRequest. تعرض هذه السياسةPromise
مع RequestSyncDeviceResponse فارغ.
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 API.
- عليك إعداد
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
تتطابق مع القيمة المقدّمة في الاستجابة مزامنة، ومن أنّك تتعامل بشكل صحيح مع أهداف DISCONNECT.429 Too Many Requests
- تم تجاوز الحد الأقصى لعدد طلبات المزامنة المتزامنة للحسابagentUserId
المحدّد. ولا يمكن للمتصل إصدار طلب مزامنة متزامن واحد إلا إذا تم ضبط العلامةasync
على "صحيح".