التحقُّق من هوية المستخدم الثانوي

يتيح لك الإجراء الثانوي لإثبات هوية المستخدم إضافة عامل أمان ثانٍ إلى الطلبات الصوتية. يتيح لك ذلك إضافة مستوى أمان إضافي لإجراءات معيّنة، مثل إيقاف كاميرا المراقبة أو فتح باب. لا يرتبط الإجراء الثانوي لإثبات هوية المستخدم بسمة جهاز معيّنة، ما يتيح لك تحديد الحالات التي يجب فيها أن يطلب Google Assistant إثبات الهوية. على سبيل المثال، يمكنك اختيار إصدار تحدٍّ لسمة OnOff لكاميرا المراقبة، ولكن لا يمكنك إصدار تحدٍّ لسمة OnOff لمصباح. يمكنك أيضًا أن تطلب من Assistant إصدار تحديات في مواقف معيّنة للإجراء نفسه. على سبيل المثال، يمكنك طلب أن يصدر Assistant طلب تحدٍّ لفتح باب إذا لم تكن سلسلة مفاتيح NFC قريبة من هذا الباب، ولكن لا يصدر تحدّيًا إذا كانت سلسلة المفاتيح موجودة.

يمكن أن يصدر Assistant نوعَين من الاختبارات: إقرار صريح أو رقم تعريف شخصي (PIN). يؤدي ذلك إلى إضافة مجموعة تحدٍّ إلى طلبات QUERY وEXECUTE المُرسَلة من Assistant إلى الإجراء الخاص بك، ويقبل استجابة خطأ challengeNeeded. بعد ذلك، يرسل Assistant طلب intent إلى الإجراء الخاص بك مع بيانات التحدي في مجموعة التحدي. يمكنك بعد ذلك التحقّق من صحة بيانات الاختبار لتحديد ما إذا كان المستخدم قد قدّم الاستجابة الأمنية الصحيحة.

يستخدم "Assistant" مربّع حوار لإصدار التحدي، ولكن إذا كنت تستخدم "Assistant" على مساحات عرض غير صوتية، يتم إدخال رقم التعريف الشخصي والتأكيدات على الشاشة.

حالات استخدام الإجراء الثانوي لإثبات هوية المستخدم

يمكنك تفعيل الإجراء الثانوي لإثبات هوية المستخدم لأي نوع جهاز أو سمة. ومع ذلك، يجب تنفيذ إجراء ثانوي لإثبات هوية المستخدم لبعض أنواع الأجهزة والسمات الحساسة للأمان من أجل الحصول على اعتماد لعملية الدمج.

يلزم إجراء ثانوي لإثبات هوية المستخدم باستخدام نوع التحدي "pinNeeded" لمجموعات السمات وأنواع الأجهزة التالية:

• السمة OnOff إذا كان نوع الجهاز هو CAMERA
• سمة OpenClose إذا كان نوع الجهاز DOOR أو GARAGE أو GATE أو WINDOW
• سمة LockUnlock عند فتح القفل
• سمة ArmDisarm عند إيقاف الإنذار أو إلغاء إيقافه
• السمة Reboot أو SoftwareUpdate أو NetworkControl إذا كان نوع الجهاز NETWORK أو ROUTER

يجب توفير نوع التحدي "ackNeeded" للسمة "TemperatureSetting" إذا كان نوع الجهاز "AC_UNIT" وكان الموقع الجغرافي لعملية الدمج هو اليابان.

أنواع التحديات المتوافقة

في ما يلي أنواع اختبارات التحقُّق الثانوي من المستخدم المتاحة:

• بدون اختبار: طلب واستجابة لا يستخدمان اختبارًا ثانويًا لإثبات هوية المستخدم
• ‫ackNeeded: إجراء ثانوي لإثبات هوية المستخدم يتطلّب إقرارًا صريحًا (نعم أو لا) ويمكنه أيضًا استخدام حالات السمة كردّ على الإجراء. لا يُنصح باستخدام هذا النوع من التحديات لأجهزة وسمات الأمان.
• pinNeeded: إجراء ثانوي لإثبات هوية المستخدم يتطلّب رقم تعريف شخصي (PIN)، وهو مثالي لأجهزة وسمات الأمان.

ما مِن تحدٍّ

يوضّح هذا المثال طلبًا واستجابة ناجحَين من EXECUTE بدون طلب إثبات الهوية لتشغيل الأضواء.

{
  "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:

• ackNeeded simple
• ackNeeded مع حالات السمات

ackNeeded simple

يعرض هذا المثال طلبًا بسيطًا وردًا يتضمّن تحدّي ackNeeded لخفض الإضاءة وتأكيد خفض الإضاءة.

{
  "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"
      }
    }]
  }
}

{
  "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
          }
        }]
      }]
    }
  }]
}

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

ackNeeded with trait states

مصادقة ثانوية لإقرار المستخدم يمكنها استخدام حالات لسمة معيّنة على سبيل المثال، إذا كنت تستخدم السمة TemperatureSetting وتم ضبط كل من thermostatMode وthermostatTemperatureSetpoint، يمكن أن يسأل Assistant هل تريد ضبط درجة حرارة مكيّف الهواء على 28 درجة؟

يمكنك أيضًا تضمين حالة في الردّ ليتمكّن Assistant من تنفيذ إجراء معيّن استنادًا إلى طلب محدّد.

تتوافق السمات والحالات التالية مع ackNeeded مع حالات السمات. ويشير إدراج سمة معيّنة إلى أنّ جميع حالاتها متوافقة.

• ArmDisarm
• استخدِم نوع التحدي ackNeeded لتفعيل الجهاز أو إلغاء تفعيله، ولكن بالنسبة إلى وظائف إيقاف التفعيل وإلغاء إيقاف التفعيل، يجب استخدام نوع التحدي pinNeeded.
• Fill
• LockUnlock
• استخدِم نوع التحدي ackNeeded لقفل الجهاز ونوع التحدي pinNeeded لفتح القفل.
• OnOff
• on
• استخدِم نوع التحدي ackNeeded لهذه السمة. يجب استخدام نوع التحدي pinNeeded عند استخدام هذه السمة مع أجهزة CAMERA.
• OpenClose
• استخدِم نوع التحدي ackNeeded لهذه السمة. يجب استخدام نوع التحدي pinNeeded عند استخدام هذه السمة مع أجهزة DOOR أو GARAGE أو GATE أو WINDOW.
• Scene
• TemperatureSetting
• thermostatMode
• thermostatTemperatureSetpoint
• thermostatTemperatureSetpointHigh
• thermostatTemperatureSetpointLow

يعرض هذا المثال طلبًا واستجابةً مع تحدّي ackNeeded يستخدم حالة سمة. يغيّر هذا الإجراء وضع مكيّف الهواء إلى التدفئة ويضبط درجة الحرارة على 28 درجة. بعد ذلك، يطلب Assistant من المستخدمين الموافقة على تشغيل التدفئة وضبط درجة الحرارة على 28 درجة لأنّ thermostatTemperatureSetpoint من 28 يتم عرضها كحالة في الردّ.

{
  "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"
      }
    }]
  }
}

{
  "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
          }
        }]
      }]
    }
  }]
}

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

pinNeeded

يُنصح باستخدام تحدّي "pinNeeded" لأجهزة الأمان.

يعرض هذا المثال طلبًا أوليًا واستجابة مع تحدي pinNeeded. يعرض المثال ردًا يتضمّن تحدّي pinNeeded، لذا يطلب 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. يُرجى الاطّلاع على الردود التي تتضمّن أخطاء.

{
  "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"
      }
    }]
  }
}

رقم تعريف شخصي صالح

يعرض هذا المثال الطلب والردّ لرمز PIN صالح.

{
  "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
      }
    }]
  }
}

{
  "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"
      }
    }]
  }
}

الردود التي تتضمّن أخطاء

في ما يلي بعض رموز الخطأ التي يمكن أن تظهر مع ردودك:

• tooManyFailedAttempts - عذرًا، أجريت محاولات كثيرة غير ناجحة. يُرجى الانتقال إلى التطبيق على جهازك لإكمال هذا الإجراء.
• ‫pinIncorrect: عذرًا، رمز الأمان غير صحيح.
• userCancelled - حسنًا

يمكنك الاطّلاع على القائمة الكاملة للأخطاء والاستثناءات.