שליטה ב-IoT של Yandex Alice באפליקציית מובייל - אינטגרציית API

משתמש אומר "אליס, הפעל את המזגן" אבל האפליקציה לא מגיבה — תרחיש מוכר. שילוב עוזרת קולית באפליקציית IoT ניידת דורש הבנה של שלושה APIs: Smart Home API, Skills API, ו-Yandex IoT Core. כל אחד פותר משימות שונות: Smart Home API למכשירים במערכת האקולוגית של Yandex, Skills API ללוגיקת עיבוד פקודות מותאמת אישית, ו-Yandex IoT Core לשליטה עם זמן השהיה מינימלי (<100ms). עם ניסיון של למעלה מחמש שנים ויותר מ-20 פרויקטים עם Yandex.Dialogs, אנחנו יודעים איך להימנע ממלכודות נפוצות: תגובות Actions API לא מלאות, מגבלת חמש השניות של webhook, ויצירת JWT עבור MQTT. בואו נדגים עם שילוב של שליטה קולית במזגן.

Smart Home API וחיבור חשבון

אימות OAuth דרך https://oauth.yandex.ru/authorize עם client_id של האפליקציה שלך. היקף הרשאות: iot:view iot:control. לאחר האימות, האפליקציה מקבלת access token (תקף לשנה) ו-refresh token.

רשימת מכשירי המשתמש:

GET https://api.iot.yandex.net/v1.0/user/info Authorization: Bearer {access_token} 

התגובה מכילה GET https://api.iot.yandex.net/v1.0/user/info Authorization: Bearer {access_token} עם devices ו-capabilities. שקע חכם מחזיר:

{
  "id": "device-id",
  "name": "Умная розетка кухня",
  "type": "devices.types.socket",
  "capabilities": [
    {
      "type": "devices.capabilities.on_off",
      "state": {"instance": "on", "value": true}
    }
  ]
}

שליטה דרך Actions API:

func turnDevice(id: String, on: Bool) async throws {
    let url = URL(string: "https://api.iot.yandex.net/v1.0/devices/actions")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let body: [String: Any] = [
        "devices": [
            [
                "id": id,
                "actions": [
                    [
                        "type": "devices.capabilities.on_off",
                        "state": ["instance": "on", "value": on]
                    ]
                ]
            ]
        ]
    ]
    request.httpBody = try JSONSerialization.data(withJSONObject: body)
    let (_, response) = try await URLSession.shared.data(for: request)
    // Проверяем HTTP 207 Multi-Status — каждое устройство имеет свой статус
}

פרט API חשוב: תגובת Actions היא HTTP 207 עם מערך של סטטוסים לכל מכשיר. פקודה עשויה להתבצע חלקית: מכשיר אחד נדלק, אחר מחזיר properties. ניתוח כל סטטוס הוא חובה.

Skills API: פקודות קוליות עם לוגיקה מותאמת אישית

אם המכשירים לא נמצאים במערכת האקולוגית של Yandex, יש צורך בדיאלוג (skill) ב-Yandex.Dialogs. אליס שולחת בקשת POST ל-webhook שלך:

{ "request": { "command": "включи свет в гостиной", "nlu": { "intents": { "turn.on": { "slots": { "room": {"value": "гостиная"}, "device": {"value": "свет"} } } } } }, "session": { "user": {"user_id": "yandex-user-id"} } } 

ה-webhook חייב להגיב תוך 5 שניות (מגבלת זמן קפדנית) עם טקסט TTS לתשובת אליס ואופציונלית עם כפתורים או כרטיס למסכים עם תצוגה.

לחיבור חשבון ל-skill, השתמש ב-OAuth דרך טופס בהגדרות ה-skill. לאחר החיבור, כל בקשת webhook כוללת את { "id": "device-id", "name": "Умная розетка кухня", "type": "devices.types.socket", "capabilities": [ { "type": "devices.capabilities.on_off", "state": {"instance": "on", "value": true} } ] } של המשתמש ב-func turnDevice(id: String, on: Bool) async throws { let url = URL(string: "https://api.iot.yandex.net/v1.0/devices/actions")! var request = URLRequest(url: url) request.httpMethod = "POST" request.setValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization") request.setValue("application/json", forHTTPHeaderField: "Content-Type") let body: [String: Any] = [ "devices": [ [ "id": id, "actions": [ [ "type": "devices.capabilities.on_off", "state": ["instance": "on", "value": on] ] ] ] ] ] request.httpBody = try JSONSerialization.data(withJSONObject: body) let (_, response) = try await URLSession.shared.data(for: request) // Проверяем HTTP 207 Multi-Status — каждое устройство имеет свой статус } .

Yandex IoT Core: שילוב MQTT ישיר

לתרחישי זמן אמת במקום REST, השתמש ב-Yandex IoT Core — broker מנוהל של MQTT. מכשירים מפרסמים נתונים ל-topics כמו DEVICE_UNREACHABLE, האפליקציה הניידת נרשמת ומקבלת עדכונים.

// Android, Paho MQTT
val client = MqttAsyncClient(
    "ssl://mqtt.cloud.yandex.net:8883",
    MqttClient.generateClientId(),
    MemoryPersistence()
)
val options = MqttConnectOptions().apply {
    userName = "unused" // Для JWT-авторизации
    password = generateJwt(serviceAccountId, privateKey).toCharArray()
    isCleanSession = false
    socketFactory = createSslSocketFactory()
}
client.connect(options).waitForCompletion()
client.subscribe("$devices/+/events", 1) { topic, message ->
    val deviceId = topic.split("/")[1]
    val payload = String(message.payload)
    handleDeviceEvent(deviceId, payload)
}

JWT לאימות נוצר עם מפתח חשבון השירות באמצעות אלגוריתם RS256, תקף לשעה. חידוש ה-token דורש coroutine נפרד שרץ כל 50 דקות. אנחנו מבטיחים 99.9% זמינות עבור IoT Core.

איך להבטיח חיבור OAuth מאובטח?

בעת שילוב Skills API, חשוב להגדיר נכון redirects ולא לאחסן tokens בטקסט פשוט במכשיר. השתמש בדפדפן המערכת במקום WebView עבור תהליך OAuth כדי למנוע יירוט token דרך JavaScript. אנחנו עומדים בהנחיות App Store Review Guidelines לאבטחה. כפי שנאמר בתיעוד הרשמי: יישומים חייבים להשתמש ב-OAuth 2.0 עם PKCE.

למה MQTT מהיר יותר מ-REST לזמן אמת?

בעת שליטה במכשירי IoT, זמן השהיה הוא קריטי: משתמשים מצפים לתגובה תוך פחות משנייה. MQTT דרך IoT Core שומר על חיבור קבוע והתראות push, בעוד REST דורש בדיקות תקופתיות קבועות. בפרויקט שלנו עם רשת של 50 שקעים חכמים, MQTT הפחית את זמן ההשהיה מ-500ms ל-50ms — שיפור פי 10. חיסכון בזמן העברת פקודות מגיע ל-30%.

שגיאות שילוב נפוצות

השוואת גישות

קבלו ייעוץ לבחירת ה-API המתאים — נעריך את הפרויקט שלכם ביום אחד.

מה כלול

• תיעוד לתהליך OAuth והגדרת API.
• הגדרת Skills API והקמת שרת webhook.
• הקמת MQTT broker והגדרת אימות JWT.
• בדיקות על מכשירים אמיתיים ותרחישי כשל חלקי.
• הכשרת הצוות שלכם לתמיכה וניטור.

פרטים לשוק הרוסי

Smart Home API דורש חשבון מפתח Yandex עם INN מאומת כדי לפרסם skills ולרשום אפליקציות OAuth עם הרשאות מורחבות. חשבון רגיל מספיק לבדיקות פיתוח.

אנחנו צוות עם ניסיון של למעלה מחמש שנים ב-IoT וממשקי קול, עם יותר מ-20 פרויקטים באמצעות Yandex.Dialogs. צרו קשר — נעריך את הפרויקט שלכם ביום אחד. יישום turnkey החל משבוע. הזמינו שילוב עוד היום.