اعلان‌ها برای اقدامات خانه هوشمند

اعلان‌ها به Action smart home شما اجازه می‌دهند از Google Assistant برای برقراری ارتباط با کاربران درباره رویدادها یا تغییرات مهم مرتبط با دستگاه استفاده کند. می‌توانید اعلان‌هایی را برای هشدار به کاربران در مورد رویدادهای به‌موقع دستگاه، به‌عنوان مثال زمانی که شخصی در درب منزل است، یا گزارش در مورد تغییر وضعیت دستگاه درخواستی، مانند زمانی که پیچ قفل در با موفقیت درگیر شده یا گیر کرده است، اجرا کنید.

اکشن smart home شما می‌تواند انواع اعلان‌های زیر را برای کاربران ارسال کند:

  • اعلان‌های پیشگیرانه : به کاربر از رویداد دستگاه smart home بدون هیچ درخواست قبلی از دستگاه‌های خود، مانند زنگ در، هشدار می‌دهد.

  • پاسخ‌های بعدی : تأیید موفقیت یا شکست درخواست فرمان دستگاه، برای مثال هنگام قفل کردن یک در. از این هشدارها برای دستورات دستگاه استفاده کنید که تکمیل آنها زمان بر است. پاسخ‌های پیگیری تنها زمانی پشتیبانی می‌شوند که درخواست‌های فرمان دستگاه از بلندگوهای هوشمند و نمایشگرهای هوشمند ارسال شوند.

Assistant این اعلان‌ها را به‌عنوان اعلان‌هایی روی بلندگوهای هوشمند و نمایشگرهای هوشمند در اختیار کاربران قرار می‌دهد. اعلان های فعال به طور پیش فرض خاموش هستند. کاربران می‌توانند همه اعلان‌های فعال را از Google Home app (GHA) روشن یا خاموش کنند.

رویدادهایی که اعلان‌ها را راه‌اندازی می‌کنند

وقتی رویدادهای دستگاه رخ می‌دهد، Action përmbush شما یک درخواست اعلان به Google ارسال می‌کند. ویژگی‌های دستگاهی که Action smart home شما پشتیبانی می‌کند، تعیین می‌کند که چه نوع رویدادهای اعلان موجود است و داده‌هایی که می‌توانید در آن اعلان‌ها قرار دهید.

ویژگی‌های زیر از اعلان‌های فعال پشتیبانی می‌کنند:

صفت رویدادها
ObjectDetection اشیاء شناسایی شده توسط دستگاه، مانند زمانی که یک چهره شناخته شده در درب تشخیص داده می شود. به عنوان مثال: "آلیس و باب جلوی در هستند."
RunCycle دستگاه یک چرخه را کامل می کند. به عنوان مثال: "چرخه ماشین لباسشویی کامل شده است."
SensorState دستگاه وضعیت حسگر پشتیبانی شده را تشخیص می دهد. به عنوان مثال: "ردیاب دود دود را تشخیص می دهد."

ویژگی‌های زیر از پاسخ‌های بعدی پشتیبانی می‌کنند:

صفت رویدادها
LockUnlock وضعیت تکمیل و تغییر وضعیت پس از اجرای دستور action.devices.commands.LockUnlock دستگاه. به عنوان مثال: "درب ورودی قفل شده است" یا "درب ورودی گیر کرده است."
NetworkControl وضعیت تکمیل و تغییر وضعیت پس از اجرای فرمان action.devices.commands.TestNetworkSpeed ​​دستگاه. به عنوان مثال: "تست سرعت شبکه شما به پایان رسیده است. سرعت دانلود در روتر آفیس در حال حاضر 80.2 کیلوبیت بر ثانیه و سرعت آپلود 9.3 کیلوبیت در ثانیه است."
OpenClose وضعیت تکمیل و تغییر وضعیت پس از اجرای دستور action.devices.commands.OpenClose دستگاه. به عنوان مثال: "درب ورودی باز شد" یا "درب ورودی باز نشد."

همه انواع دستگاه ها از اعلان ها برای ویژگی های قابل اجرا پشتیبانی می کنند.

برای اکشن خانه هوشمند خود اعلان بسازید

در این مراحل اعلان‌ها را به اکشن smart home خود اضافه کنید:

  1. اگر اعلان‌ها از برنامه دستگاه smart home شما فعال است، به Google نشان دهید. اگر کاربران اعلان‌ها را در برنامه شما روشن یا خاموش می‌کنند، یک درخواست SYNC ارسال کنید تا Google را از تغییر دستگاه مطلع کنید.
  2. هنگامی که یک رویداد یا تغییر وضعیت مربوط به دستگاه رخ می دهد که باعث ایجاد اعلان می شود، با تماس با Report State reportStateAndNotification API یک درخواست اعلان ارسال کنید. اگر وضعیت دستگاه تغییر کرد، می‌توانید هر دو حالت و اعلان را در تماس Report State و اعلان ارسال کنید.

بخش های زیر این مراحل را با جزئیات بیشتری پوشش می دهند.

مشخص کنید که آیا اعلان ها در برنامه شما فعال هستند یا خیر

کاربران می توانند با فعال کردن این ویژگی در GHA انتخاب کنند که آیا می خواهند اعلان های پیشگیرانه را دریافت کنند. در برنامه دستگاه smart home خود، همچنین می‌توانید به صورت اختیاری این قابلیت را برای کاربران اضافه کنید که به طور صریح اعلان‌ها را از دستگاه، به عنوان مثال، از تنظیمات برنامه خود تغییر دهند.

با برقراری تماس درخواست SYNC برای به‌روزرسانی داده‌های دستگاه، به Google نشان دهید که اعلان‌ها برای دستگاه شما فعال هستند. هر زمان که کاربران این تنظیم را در برنامه شما تغییر دهند، باید درخواست SYNC مانند این ارسال کنید.

در پاسخ SYNC ، یکی از این به‌روزرسانی‌ها را ارسال کنید:

  • اگر کاربر صراحتاً اعلان‌ها را در برنامه دستگاه شما روشن کرده است، یا اگر گزینه جابجایی را ارائه نمی‌دهید، ویژگی devices.notificationSupportedByAgent را روی true تنظیم کنید.
  • اگر کاربر صراحتاً اعلان‌ها را در برنامه دستگاه شما خاموش کرد، ویژگی devices.notificationSupportedByAgent را روی false تنظیم کنید.

قطعه زیر نمونه ای از نحوه تنظیم پاسخ SYNC را نشان می دهد:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

درخواست‌های اعلان را به Google ارسال کنید

برای فعال کردن اعلان‌ها در Assistant ، اجرای شما یک بار اعلان را از طریق یک تماس Report State و API اعلان به Google Home Graph ارسال می‌کند.

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 devices.reportStateAndNotification برقرار کنید. درخواست JSON شما باید شامل یک eventId باشد که یک شناسه منحصربه‌فرد است که توسط پلتفرم شما برای رویدادی که اعلان را راه‌اندازی می‌کند ایجاد می‌کند. eventId باید یک شناسه تصادفی باشد که هر بار که درخواست اعلان ارسال می کنید متفاوت باشد.

در شی notifications که در تماس API خود ارسال می‌کنید، یک مقدار priority قرار دهید که نحوه ارائه اعلان را مشخص می‌کند. بسته به ویژگی دستگاه، شی notifications شما ممکن است شامل فیلدهای مختلفی باشد.

برای تنظیم بار و فراخوانی API یکی از این مسیرها را دنبال کنید:

ارسال یک محموله اعلان پیشگیرانه

برای فراخوانی 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 برای Report State و اعلان آمده است:
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "ObjectDetection": {
                "priority": 0,
                "detectionTimestamp": 1534875126750,
                "objects": {
                  "named": [
                    "Alice"
                  ],
                  "unclassified": 2
                }
              }
            }
          }
        }
      }
    }
  6. Report State و اعلان 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:reportStateAndNotification"
    

gRPC

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

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

Node.js

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

  1. سرویس google.homegraph را با استفاده از Application Default Credentials راه اندازی کنید.
  2. روش reportStateAndNotification را با ReportStateAndNotificationRequest فراخوانی کنید. با ReportStateAndNotificationResponse یک Promise برمی گرداند.
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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

جاوا

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

  1. HomeGraphApiService را با استفاده از Application Default Credentials راه اندازی کنید.
  2. روش 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 notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
    
ارسال بار پاسخ پیگیری

محموله برای پاسخ پیگیری شامل وضعیت درخواست، کدهای خطا برای خرابی رویدادها، در صورت وجود، و followUpToken معتبر است که در طول درخواست قصد EXECUTE ارائه شده است. followUpToken باید در عرض پنج دقیقه استفاده شود تا معتبر بماند و پاسخ به درخواست اصلی به درستی مرتبط شود.

قطعه زیر نمونه ای از EXECUTE request payload را با فیلد followUpToken نشان می دهد.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

Google از followUpToken استفاده می‌کند تا اعلان را فقط در دستگاهی که کاربر در ابتدا با آن تعامل داشت، ارسال کند و در همه دستگاه‌های کاربر پخش نشود.

برای فراخوانی 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 برای Report State و اعلان آمده است:
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "NetworkControl": {
                "priority": 0,
                "followUpResponse": {
                  "status": "SUCCESS",
                  "followUpToken": "PLACEHOLDER",
                  "networkDownloadSpeedMbps": 23.3,
                  "networkUploadSpeedMbps": 10.2
                }
              }
            }
          }
        }
      }
    }
  6. Report State و اعلان 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:reportStateAndNotification"
    

gRPC

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

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

Node.js

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

  1. سرویس google.homegraph را با استفاده از Application Default Credentials راه اندازی کنید.
  2. روش reportStateAndNotification را با ReportStateAndNotificationRequest فراخوانی کنید. با ReportStateAndNotificationResponse یک Promise برمی گرداند.
const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});
    

جاوا

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

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

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);
    

ورود به سیستم

اعلان‌ها از ثبت رویداد پشتیبانی می‌کنند، همانطور که در گزارش‌های رویداد Access با Cloud Logging مشخص شده است. این گزارش‌ها برای آزمایش و حفظ کیفیت اعلان‌ها در Action شما مفید هستند.

شکل زیر طرح یک ورودی notificationLog است:

اموال توضیحات
requestId شناسه درخواست اعلان
structName نام ساختار اعلان، مانند "ObjectDetection".
status وضعیت اعلان را نشان می دهد.

فیلد status شامل وضعیت های مختلفی است که ممکن است نشان دهنده خطا در بار اعلان باشد. برخی از این موارد ممکن است فقط در Actions در دسترس باشند که برای تولید راه اندازی نشده اند.

وضعیت های مثال عبارتند از:

وضعیت توضیحات
EVENT_ID_MISSING نشان می دهد که قسمت eventId مورد نیاز وجود ندارد.
PRIORITY_MISSING نشان می دهد که یک فیلد priority وجود ندارد.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE نشان می دهد که ویژگی notificationSupportedByAgent دستگاه اعلان ارائه شده در SYNC نادرست است.
NOTIFICATION_ENABLED_BY_USER_FALSE نشان می دهد که کاربر اعلان ها را در دستگاه اعلان در GHA فعال نکرده است. این وضعیت فقط در Actions موجود است که برای تولید راه اندازی نشده اند.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE نشان می دهد که کاربر دستگاه اعلان را به خانه/ساختار اختصاص نداده است. این وضعیت فقط در Actions موجود است که برای تولید راه اندازی نشده اند.

علاوه بر این وضعیت‌های عمومی که می‌توانند برای همه اعلان‌ها اعمال شوند، فیلد status ممکن است در صورت لزوم شامل وضعیت‌های خاص باشد (مانند OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING ).