ברוכים הבאים למרכז המפתחים של Google Home. זהו היעד החדש ללימוד פיתוח פעולות לבית חכם. הערה:תצטרכו להמשיך ליצור פעולות במסוף הפעולות.

דף זה תורגם על ידי Cloud Translation API.

אימות משתמש משני

אימות המשתמש המשני מאפשר להוסיף אבטחה מצד שני לפקודות קוליות. כך תוכלו להוסיף שכבת אבטחה לפעולות מסוימות, כמו כיבוי מצלמת אבטחה או פתיחת דלת. אימות המשתמש המשני לא קשור לתכונה ספציפית של המכשיר, וכך אתם יכולים להחליט מתי להציג אתגר ל-Google Assistant. לדוגמה, אפשר לבחור אם ליצור אתגר למאפיין OnOff במצלמת אבטחה, אבל לא לסמן אתגר למאפיין OnOff לגבי אור. במצבים מסוימים, אפשר גם להפעיל אתגרים על ידי Assistant עבור אותה פעולה. לדוגמה, אפשר לבקש מ-Assistant לשלוח בקשת אתגר כדי לפתוח דלת אם מפתח ה-NFC לא נמצא בקרבת הדלת, אבל לא ליצור אתגר אם המפתח הפיזי נמצא.

יש שני סוגים של אתגרים ב-Assistant – אישור מפורש או מספר זיהוי אישי (PIN). הפעולה הזו גורמת להוספה של חסימת אתגר לאובייקטים מסוג QUERY ול-EXECUTE שנשלחים מ-Assistant בחזרה לפעולה שלך, ומקבלת תשובה מהודעת השגיאה challengeNeeded. לאחר מכן Assistant שולח בחזרה את בקשת ה-Intent לפעולה שלכם, עם נתוני האתגר שבבלוק האתגר. לאחר מכן תוכלו לאמת את נתוני האתגר כדי לקבוע אם המשתמש נתן את תגובת האבטחה הנכונה.

ב-Assistant נעשה שימוש בתיבת דו-שיח כדי לבצע את האתגר, אבל אם משתמשים ב-Assistant בפלטפורמות ללא קול, קוד האימות והאישורים מתבצעים במסך.

סוגי מכשירים נתמכים

האפשרות לאימות משתמש משני נתמכת בכל סוגי המכשירים.

סוגי traits נתמכים במכשירים

יש תמיכה באימות משני של משתמשים בכל תכונות המכשיר.

סוגי אתגרים נתמכים

אלה הסוגים הנתמכים של אימות משתמש משני:

NoChallenge: בקשה ותגובה שלא משתמשים באתגר לאימות משתמש משני.
ackNeeded – אימות משני של משתמש שדורש אישור מפורש (כן או לא) ואפשר גם להשתמש במצבים של trait כמשוב מהתשובה. סוג האתגר הזה לא מומלץ לשימוש במכשירים ובתכונות אבטחה.
pinNeeded – אימות משני של משתמש שדורש מספר זיהוי אישי (PIN), שהוא אידיאלי למכשירי אבטחה ולתכונות.

ללא אתגר

בדוגמה הזו מוצגת בקשה ותגובה של EXECUTE שבוצעו בהצלחה, ללא אתגר להדלקת התאורה.

משתמש	מדליקים את האורות.
Google Assistant	בסדר, נדלק 3 נורות.

בקשה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.OnOff",
          "params": {
            "on": true
          }
        }]
      }]
    }
  }]
}

תשובה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

אימות אישור משני של משתמש שיכול להשתמש במספר מצבים עבור תכונה או אימות פשוט.

קיימים הסוגים הבאים של אתגרים מסוג ackNeeded:

ackנדרש פשוט
ackנדרש עם מצבי trait

נדרש פשוטה

בדוגמה הזו מוצגת בקשה ותגובה פשוטות עם אתגר ackNeeded לעמעום אור, והאישור לעמעום האור.

משתמש	עמעום התאורה בסלון.
Google Assistant	עמעום התאורה של הסלון. להמשיך?
משתמש	כן.
Google Assistant	עמעום התאורה של הסלון.

בקשה 1

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}

תשובה ראשונה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

בקשה 2

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}

תשובה 2

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackנדרש עם מצבי trait

אימות משני של אישור משתמש שיכול להשתמש במצבים עבור תכונה. לדוגמה, אם משתמשים בתכונה TemperatureSetting ומוגדרות גם thermostatMode וגם thermostatTemperatureSetpoint, Assistant יכולה לשאול את השאלה האם אתה בטוח שברצונך להגדיר את החימום במזגן ל-28 מעלות?

אפשר גם לכלול מצב בתגובה כדי ש-Assistant יבצע פעולה ספציפית על סמך בקשה נתונה.

התכונות והמצבים הבאים תומכים ב-ackNeeded עם מצבי trait. פירוט של תכונה ספציפית מציין שכל המצבים שלה נתמכים.

ArmDisarm

currentArmLevel
currentStatusReport

Fill
LockUnlock
OnOff

on

OpenClose
Scene
TemperatureSetting

thermostatMode
thermostatTemperatureSetpoint
thermostatTemperatureSetpointHigh
thermostatTemperatureSetpointLow

בדוגמה הזו מוצגת בקשה ותשובה עם אתגר ackNeeded עם מצב trait. היא משנה את מצב המזגן לחום ויוצרת את הטמפרטורה ל-28 מעלות. לאחר מכן, Assistant מבקשים מהמשתמשים אישור להפעיל את החימום ולהגדיר את הטמפרטורה ל-28 מעלות, כי thermostatTemperatureSetpoint של 28 מוחזר כמצב בתגובה.

משתמש	הגדרת מצב AC לחימום.
Google Assistant	בחרת להגדיר את החימום במזגן ל-28 מעלות. להמשיך?
משתמש	כן.
Google Assistantnt	הגדרת החימום במזגן ל-28 מעלות.

בקשה 1

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          }
        }]
      }]
    }
  }]
}

תשובה ראשונה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

בקשה 2

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}

תשובה 2

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

מומלץ להפעיל את האתגר pinNeeded למכשירי אבטחה.

בדוגמה הזו מוצגת בקשה ותגובה ראשוניות עם אתגר של pinNeeded. בדוגמה מופיעה תשובה עם אתגר מסוג pinNeeded, לכן Assistant מבקשת את ה-PIN. בשלב הזה, המשתמש יכול לספק קוד אימות שגוי או חוקי.

בקשה ותשובה לדוגמה עבור קוד אימות שגוי או חוקי:

קוד אימות שגוי
קוד אימות חוקי

משתמש	מבטלים את נעילת הדלת.
Google Assistant	אפשר לקבל את קוד האבטחה שלך?

בקשה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          }
        }]
      }]
    }
  }]
}

תשובה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

קוד האימות שגוי

בדוגמה הזו מוצגת הבקשה והתשובה עם אתגר של challengeFailedPinNeeded. כדאי להשתמש באתגר הזה אחרי שהאתגר הראשוני pinNeeded נכשל.

כשמוחזר סוג challengeFailedPinNeeded, Assistant מבקש שוב את קוד האבטחה. אם המשתמש מבצע יותר מדי ניסיונות כושלים, תוכלו להחזיר את הודעת השגיאה tooManyFailedAttempts. מידע נוסף זמין בקטע תגובות לשגיאה.

משתמש	333222
Google Assistant	מצטערים, קוד האבטחה שגוי. אפשר לקבל את קוד האבטחה שלך?

בקשה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333222"
          }
        }]
      }]
    }
  }]
}

תשובה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

קוד אימות חוקי

בדוגמה הזו מוצגות הבקשה והתשובה של קוד אימות חוקי.

משתמש	333444
Google Assistant	ביטול הנעילה של הדלת מתבצע.

בקשה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333444"
          }
        }]
      }]
    }
  }]
}

תשובה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}

משתמש	עמעום התאורה בסלון.
Google Assistant	אפשר לקבל את קוד האבטחה שלך?

בקשה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}

תשובה

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

תשובות לשגיאות

לפניכם כמה קודי שגיאה שניתן להחזיר בתשובות:

challengeFailedNotSetup - לפעולה הזו נדרש קוד אבטחה, אבל הוא לא הוגדר באפליקציה של המכשיר.
tooManyFailedAttempts - מצטערים, ניסיונות כושלים רבים מדי. עברו לאפליקציה של המכשיר כדי להשלים את הפעולה הזו.
pinIncorrect - מצטערים, קוד האבטחה שגוי.
userCancelled – אישור

כדאי לעיין ברשימה המלאה של שגיאות וחריגים.