Weryfikacja dodatkowego użytkownika

Dodatkowa weryfikacja użytkownika umożliwia dodanie drugiego poziomu zabezpieczeń do poleceń głosowych. Umożliwia to dodanie dodatkowych zabezpieczeń w przypadku niektórych działań, takich jak wyłączenie kamery monitoringu lub otwarcie drzwi. Dodatkowa weryfikacja użytkownika nie jest powiązana z określoną cechą urządzenia, co pozwala Ci decydować, kiedy Google Assistant ma wysyłać test zabezpieczający. Możesz na przykład zdecydować się na wysłanie prośby o dodatkową weryfikację w przypadku cechy OnOff kamery bezpieczeństwa, ale nie w przypadku cechy OnOff światła. Możesz też Assistant w określonych sytuacjach zgłaszać zastrzeżenia dotyczące tego samego działania. Możesz na przykład poprosić Assistant o wysłanie żądania weryfikacji w celu otwarcia drzwi, jeśli brelok NFC nie znajduje się w pobliżu tych drzwi, ale nie wysyłać żądania, jeśli brelok jest w pobliżu.

Assistant może wysyłać 2 rodzaje żądań weryfikacji: potwierdzenie lub osobisty numer identyfikacyjny (PIN). Spowoduje to dodanie bloku weryfikacji do intencji QUERY i EXECUTE wysyłanych z Assistant z powrotem do działania oraz zaakceptowanie odpowiedzi z błędem challengeNeeded. Assistant odsyła żądanie intencji do Twojej działania z danymi weryfikacyjnymi w bloku weryfikacyjnym. Następnie możesz zweryfikować dane wyzwania, aby sprawdzić, czy użytkownik podał prawidłową odpowiedź zabezpieczającą.

Assistant używa dialogu do wydania wyzwania, ale jeśli używasz Assistant na platformach innych niż głosowe, kod PIN i potwierdzenia są wyświetlane na ekranie.

Kiedy używać dodatkowej weryfikacji użytkownika

Dodatkową weryfikację użytkownika możesz włączyć w przypadku dowolnego typu urządzenia lub cechy. Aby uzyskać certyfikat integracji, musisz jednak wdrożyć dodatkową weryfikację użytkownika w przypadku niektórych typów urządzeń i funkcji, które są szczególnie istotne z punktu widzenia bezpieczeństwa.

Wymagana jest dodatkowa weryfikacja użytkownika za pomocą typu testu pinNeeded w przypadku tych kombinacji cech i typów urządzeń:

  • cecha OnOff, jeśli typ urządzenia to CAMERA;
  • Cechę OpenClose, jeśli typ urządzenia to DOOR, GARAGE, GATE lub WINDOW.
  • LockUnlock podczas odblokowywania.
  • Cechę ArmDisarm podczas rozbrajania lub anulowania rozbrajania.
  • Atrybut Reboot, SoftwareUpdate lub NetworkControl, jeśli typ urządzenia to NETWORK lub ROUTER.

Typ weryfikacji ackNeeded jest wymagany w przypadku cechy TemperatureSetting, jeśli typ urządzenia to AC_UNIT, a integracja jest lokalizacją w Japonii.

Obsługiwane typy wyzwań

Obsługiwane typy testów dodatkowej weryfikacji użytkownika:

  • Brak zadania – żądanie i odpowiedź, które nie korzystają z dodatkowego zadania weryfikacji użytkownika.
  • ackNeeded – dodatkowa weryfikacja użytkownika, która wymaga wyraźnego potwierdzenia (tak lub nie) i może też wykorzystywać stany cech jako informacje zwrotne. Ten typ weryfikacji nie jest zalecany w przypadku urządzeń i cech związanych z bezpieczeństwem.
  • pinNeeded – dodatkowa weryfikacja użytkownika, która wymaga podania osobistego numeru identyfikacyjnego (PIN). Jest to idealne rozwiązanie w przypadku urządzeń i cech związanych z bezpieczeństwem.

Brak wymogów

Ten przykład pokazuje udane żądanie EXECUTE i odpowiedź bez wyzwania związanego z włączeniem świateł.

Użytkownik Włącz światła.
Google Assistant OK, włączam 3 światła.
Prośba
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

Dodatkowe uwierzytelnianie użytkownika, które może korzystać z wielu stanów cechy lub prostego uwierzytelniania potwierdzającego.

Istnieją następujące rodzaje ackNeeded wyzwań:

ackNeeded simple

Ten przykład przedstawia proste żądanie i odpowiedź z ackNeededwyzwaniem przyciemnienia światła oraz potwierdzenie przyciemnienia światła.

Użytkownik Przyciemnij światło w salonie.
Google Assistant Przyciemniam światło w salonie. Na pewno?
Użytkownik Tak.
Google Assistant Przyciemniam światło w salonie.
Prośba 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
          }
        }]
      }]
    }
  }]
}
Odpowiedź 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Prośba 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
          }
        }]
      }]
    }
  }]
}
Odpowiedź 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded ze stanami cech

Dodatkowe uwierzytelnianie potwierdzające użytkownika, które może używać stanów w przypadku cechy. Jeśli na przykład korzystasz z cechy TemperatureSetting, a wartości thermostatMode i thermostatTemperatureSetpoint są ustawione, Assistant może zapytać Czy na pewno chcesz ustawić ogrzewanie klimatyzatora na 28 stopni?

Możesz też uwzględnić w odpowiedzi stan, abyAssistant wykonał określone działanie na podstawie danego żądania.

ackNeeded z atrybutami stanu obsługują te cechy i stany: Wymienienie konkretnej cechy oznacza, że obsługiwane są wszystkie jej stany.

  • ArmDisarm
    • Użyj typu weryfikacji ackNeeded, aby włączyć lub anulować włączenie urządzenia, ale w przypadku funkcji wyłączania i anulowania wyłączania wymagany jest typ weryfikacji pinNeeded.
  • Fill
  • LockUnlock
    • Użyj typu wyzwania ackNeeded, aby zablokować urządzenie, a typu pinNeeded, aby je odblokować.
  • OnOff
    • on
    • W przypadku tej cechy użyj typu wyzwania ackNeeded. Typ weryfikacji pinNeeded jest wymagany, gdy ta cecha jest używana z urządzeniami CAMERA.
  • OpenClose
    • W przypadku tej cechy użyj typu wyzwania ackNeeded. Typ weryfikacji pinNeeded jest wymagany, gdy ta cecha jest używana z urządzeniami DOOR, GARAGE, GATE lub WINDOW.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

Ten przykład pokazuje żądanie i odpowiedź z testem zabezpieczającym ackNeeded, który korzysta ze stanu cechy. Zmienia tryb klimatyzacji na grzanie i ustawia temperaturę na 28 stopni. Następnie Assistant prosi użytkowników o potwierdzenie włączenia ogrzewania i ustawienia temperatury na 28 stopni, ponieważ w odpowiedzi zwrócono stan thermostatTemperatureSetpoint o wartości 28.

Użytkownik Ustaw tryb klimatyzacji na ogrzewanie.
Google Assistant Czy na pewno chcesz ustawić ogrzewanie na klimatyzatorze na 28 stopni?
Użytkownik Tak.
Google Assistant Ustawiam ogrzewanie na klimatyzatorze na 28 stopni.
Prośba 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"
          }
        }]
      }]
    }
  }]
}
Odpowiedź 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Prośba 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
          }
        }]
      }]
    }
  }]
}
Odpowiedź 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

pinNeeded Wyzwanie jest zalecane w przypadku urządzeń zabezpieczających.

Ten przykład pokazuje początkowe żądanie i odpowiedź z pinNeededwyzwaniem. W tym przykładzie zwracana jest odpowiedź z testem pinNeeded, więc Assistant prosi o podanie kodu PIN. W tym momencie użytkownik może podać nieprawidłowy lub prawidłowy kod PIN.

Przykładowe żądanie i odpowiedź w przypadku nieprawidłowego lub prawidłowego kodu PIN:

Użytkownik Otwórz drzwi.
Google Assistant Czy możesz podać kod zabezpieczający?
Prośba
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Błędny kod PIN

Ten przykład pokazuje żądanie i odpowiedź z challengeFailedPinNeeded weryfikacją. Z tego wyzwania należy skorzystać po nieudanym pierwszym wyzwaniu pinNeeded.

Gdy zwracany jest typ challengeFailedPinNeeded,Assistant ponownie prosi o kod zabezpieczający. Jeśli użytkownik wykona zbyt wiele nieudanych prób, możesz zwrócić tooManyFailedAttemptsodpowiedź z błędem. Zobacz Komunikaty o błędach.

Użytkownik 333222
Google Assistant Kod zabezpieczający jest nieprawidłowy. Czy możesz podać kod zabezpieczający?
Prośba
{
  "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"
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

Prawidłowy kod PIN

Ten przykład pokazuje żądanie i odpowiedź dotyczące prawidłowego kodu PIN.

Użytkownik 333444
Google Assistant Otwieram zamek w drzwiach.
Prośba
{
  "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"
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
Użytkownik Przyciemnij światło w salonie.
Google Assistant Czy możesz podać kod zabezpieczający?
Prośba
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Odpowiedzi na błędy

Oto niektóre kody błędów, które mogą być zwracane w odpowiedziach:

  • tooManyFailedAttempts – Przepraszamy, zbyt wiele nieudanych prób. Otwórz aplikację na urządzeniu, aby dokończyć tę czynność.
  • pinIncorrect – Przepraszamy, kod zabezpieczający jest nieprawidłowy.
  • userCancelled – OK

Zobacz pełną listę błędów i wyjątków.