درخواست همگام سازی

درخواست همگام‌سازی برای هر کاربر Google با دستگاه‌هایی که agentUserId مشخص شده مرتبط با آن‌ها (که شما در درخواست SYNC اصلی ارسال کرده‌اید) یک درخواست SYNC را برای انجام شما آغاز می‌کند. این به شما امکان می‌دهد دستگاه‌های کاربران را بدون لغو پیوند و پیوند مجدد حساب آن‌ها به‌روزرسانی کنید. همه کاربرانی که به این شناسه پیوند داده شده اند یک درخواست SYNC دریافت خواهند کرد.

شما باید یک درخواست SYNC را راه اندازی کنید:

  • اگر کاربر دستگاه جدیدی اضافه کند.
  • اگر کاربر دستگاه موجود را حذف کند.
  • اگر کاربر یک دستگاه موجود را تغییر نام دهد.
  • اگر نوع، ویژگی یا ویژگی دستگاه جدیدی را اضافه کنید.

شروع کنید

برای اجرای Request Sync، مراحل زیر را دنبال کنید:

Google HomeGraph API را فعال کنید

  1. در Google Cloud Console ، به صفحه HomeGraph API بروید.

    به صفحه HomeGraph API بروید
  2. پروژه ای را انتخاب کنید که با شناسه پروژه smart home شما مطابقت دارد.
  3. روی ENABLE کلیک کنید.

یک کلید حساب سرویس ایجاد کنید

برای ایجاد یک کلید حساب سرویس از Google Cloud Console این دستورالعمل ها را دنبال کنید:

توجه : هنگام انجام این مراحل، مطمئن شوید که از پروژه GCP صحیح استفاده می کنید. این پروژه ای است که با شناسه پروژه smart home شما مطابقت دارد.
  1. در Google Cloud Console ، به صفحه کلید ایجاد حساب سرویس بروید.

    به صفحه Create Service Account Key بروید
  2. از لیست حساب سرویس ، حساب سرویس جدید را انتخاب کنید.
  3. در قسمت نام حساب سرویس ، یک نام وارد کنید.
  4. در قسمت شناسه حساب سرویس ، یک شناسه وارد کنید.
  5. از فهرست نقش ، حساب‌های خدمات > ایجاد کننده رمز حساب حساب را انتخاب کنید.

  6. برای نوع کلید ، گزینه JSON را انتخاب کنید.

  7. روی ایجاد کلیک کنید. یک فایل JSON که حاوی دانلودهای کلید شما در رایانه شما است.

با API تماس بگیرید

HTTP

Home Graph API یک نقطه پایانی HTTP ارائه می دهد

  1. از فایل JSON حساب سرویس دانلود شده برای ایجاد یک رمز وب JSON (JWT) استفاده کنید. برای اطلاعات بیشتر، احراز هویت با استفاده از حساب سرویس را ببینید.
  2. یک نشانه دسترسی OAuth 2.0 را با https://www.googleapis.com/auth/homegraph با استفاده از oauth2l دریافت کنید:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. درخواست JSON را با agentUserId ایجاد کنید. در اینجا یک نمونه درخواست JSON برای درخواست همگام سازی آمده است:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Request Sync JSON و نشانه موجود در درخواست HTTP POST خود را با نقطه پایانی Google Home Graph ترکیب کنید. در اینجا مثالی از نحوه ایجاد درخواست در خط فرمان با استفاده از curl به عنوان آزمایش آورده شده است:
  7. 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 را ارائه می دهد

  1. تعریف سرویس بافرهای پروتکل را برای Home Graph API دریافت کنید.
  2. مستندات توسعه‌دهنده gRPC را دنبال کنید تا برای یکی از زبان‌های پشتیبانی‌شده، خرد کلاینت ایجاد کنید.
  3. روش RequestSync را فراخوانی کنید.

Node.js

Google APIs Node.js Client اتصالاتی را برای Home Graph API فراهم می کند.

  1. سرویس google.homegraph را با استفاده از Application Default Credentials راه اندازی کنید.
  2. روش 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
  }
});
    

جاوا

HomeGraph API Client Library برای جاوا اتصالاتی را برای Home Graph API فراهم می کند.

  1. HomeGraphApiService با استفاده از Application Default Credentials راه اندازی کنید.
  2. روش 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 با مقدار ارائه شده در پاسخ SYNC شما مطابقت دارد و به درستی مقاصد DISCONNECT را مدیریت می کنید.
  • 429 Too Many Requests - از حداکثر تعداد درخواست های همگام سازی همزمان برای agentUserId داده شده بیشتر شده است. تماس‌گیرنده می‌تواند فقط یک درخواست همگام‌سازی همزمان صادر کند، مگر اینکه پرچم async روی درست تنظیم شود.