Witamy w Google Home Developer Center – nowym miejscu, gdzie możesz dowiedzieć się, jak tworzyć inteligentne działania domowe. Uwaga: nadal będziesz tworzyć działania w konsoli Actions.

Weryfikacja dodatkowego użytkownika

Dzięki dodatkowej weryfikacji użytkownika możesz korzystać z zabezpieczeń dwuskładnikowych do poleceń głosowych. To dodatkowe zabezpieczenie 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 określić, kiedy Google Assistant ma otrzymać wyzwanie. Możesz na przykład rozpocząć wyzwanie dla atrybutu OnOff w przypadku kamery monitoringu, ale nie podjąć wyzwania dla ceny OnOff w przypadku lampy. W określonych sytuacjach możesz też mieć Assistant problemów związanych z tym samym działaniem. Na przykład możesz poprosić Assistant o wysłanie prośby o otwarcie drzwi, jeśli pilot NFC nie znajduje się w pobliżu tych drzwi, ale nie stanowi problemu, jeśli jest dostępny.

Assistant może wysyłać dwa rodzaje wyzwań – jednoznaczne potwierdzenie lub osobisty numer identyfikacyjny (PIN). Spowoduje to dodanie bloku zabezpieczającego do intencji QUERY i EXECUTE wysłanych z intencji Assistant do działania oraz przyjęcie odpowiedzi na błąd challengeNeeded. Następnie Assistant wysyła żądanie intencji do działania wraz z danymi wyzwania w bloku wyzwania. Możesz wtedy zweryfikować dane wyzwania, aby określić, czy użytkownik udzielił prawidłowej odpowiedzi zabezpieczającej.

Assistant używa okna do wyzwania, ale jeśli używasz Assistant na platformach innych niż Google, kod PIN i potwierdzenia są przeprowadzane na ekranie.

Obsługiwane typy urządzeń

Weryfikacja dodatkowego użytkownika jest obsługiwana na wszystkich typach urządzeń.

Obsługiwane cechy urządzenia

Weryfikacja dodatkowego użytkownika jest obsługiwana w przypadku wszystkich cech urządzenia.

Obsługiwane typy wyzwań

Oto obsługiwane typy dodatkowej weryfikacji użytkownika:

  • Brak testu zabezpieczającego – żądanie i odpowiedź, które nie korzystają z dodatkowego wyzwania weryfikacji użytkownika.
  • ackRequireded – dodatkowa weryfikacja użytkownika, która wymaga wyraźnego potwierdzenia (tak lub nie) i może używać stanów cech jako odpowiedzi. Ten typ wyzwania nie jest zalecany w przypadku urządzeń zabezpieczających.
  • pinNeeded – dodatkowa weryfikacja użytkownika, która wymaga osobistego numeru identyfikacyjnego (PIN), co jest idealnym rozwiązaniem w przypadku urządzeń zabezpieczających i cech.

Brak wyzwań

Ten przykład pokazuje udane żądanie EXECUTE i odpowiedź bez próby włączenia świateł.

Użytkownik Włącz światło.
Google Assistant OK, włączam 3 światła.
Żądanie
{
  "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
      }
    }]
  }
}

Akceptacja

Dodatkowe uwierzytelnianie, które może wykorzystywać wiele stanów jako cechę lub proste uwierzytelnianie potwierdzenia.

Dostępne są następujące typy testów zabezpieczających ackNeeded:

prosty

Ten przykład pokazuje proste żądanie i odpowiedź z wyzwaniem ackNeeded przyciemnienia światła i potwierdzeniem 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 statusem cech

Dodatkowe uwierzytelnianie użytkowników, które może używać stanów dla cechy. Jeśli na przykład używasz właściwości TemperatureSetting i ustawisz opcje thermostatMode oraz thermostatTemperatureSetpoint, Assistant może zapytać Czy na pewno chcesz ustawić ogrzewanie klimatyzacji na 28 stopni?

Możesz też dodać stan do odpowiedzi, aby Assistant wykonał określone działanie na podstawie danego żądania.

Poniższe cechy i stany obsługują ackNeeded ze stanami cech. Wyświetlanie listy określonych cech wskazuje, że obsługiwane są wszystkie zawarte w nim stany.

Ten przykład pokazuje żądanie i odpowiedź z wyzwaniem ackNeeded, które używa stanu cechy. Przełącza tryb klimatyzacji na ogrzewanie i ustawia temperaturę na 28 stopni. Następnie Assistant prosi użytkowników o potwierdzenie włączenia ogrzewania i ustalenia temperatury na 28 stopni, ponieważ w odpowiedzi jako stan zwracany jest parametr thermostatTemperatureSetpoint (28).

Użytkownik Przełącz tryb ogrzewania na klimatyzację.
Google Assistant Czy na pewno chcesz nagrzewać klimatyzację na 28 stopni?
Użytkownik Tak.
Google Assistant Ustawiam ogrzewanie na klimatyzację 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
      }
    }]
  }
}

Potrzebna

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

Ten przykład pokazuje wstępne żądanie i odpowiedź z wyzwaniem pinNeeded. Przykład zwraca odpowiedź z wyzwaniem pinNeeded, więc Assistant prosi o przypięcie. Na tym etapie użytkownik może podać prawidłowy kod PIN.

Przykładowe żądanie i odpowiedź w związku z nieprawidłowym lub prawidłowym kodem PIN:

Użytkownik Odblokuj drzwi.
Google Assistant Czy mogę dostać kod zabezpieczający?
Żądanie
{
  "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 wyzwaniem challengeFailedPinNeeded. Tego wyzwania należy używać po nieudanym wyzwaniu pinNeeded.

Po zwróceniu typu challengeFailedPinNeeded Assistant ponownie prosi o kod zabezpieczający. Jeśli użytkownik wykona zbyt wiele nieudanych prób, możesz zwrócić tooManyFailedAttempts błąd. Zobacz Odpowiedzi na błędy.

Użytkownik 333222
Google Assistant Kod jest nieprawidłowy. Czy mogę dostać kod zabezpieczający?
Żądanie
{
  "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 odpowiedzi ważnego kodu PIN.

Użytkownik 333444
Google Assistant Otwieram drzwi.
Żądanie
{
  "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 mogę dostać kod zabezpieczający?
Żądanie
{
  "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"
      }
    }]
  }
}

Reakcje na błędy

Oto niektóre kody błędów, które można zwrócić w odpowiedziach:

  • challengeFailedNotSetup – To działanie wymaga podania kodu zabezpieczającego, ale nie został on skonfigurowany w aplikacji na urządzeniu.
  • tooManyFailedAttempts – Niestety, zbyt wiele nieudanych prób. Aby to zrobić, otwórz aplikację na urządzeniu.
  • pinIncorrect – Kod bezpieczeństwa jest nieprawidłowy.
  • userCancelled – OK.

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