Ogólne
P: Gdzie i w jakim języku powinniśmy wdrożyć infrastrukturę realizacji zamówień w chmurze?
O: Możesz wdrożyć infrastrukturę na dowolnej platformie i w dowolnym języku, o ile obsługuje ona nowoczesne protokoły SSL (TLS) i OAuth 2.0. Zalecamy wdrożenie jak najbliżej reszty infrastruktury, aby zwiększyć niezawodność i zmniejszyć opóźnienie w wykonywaniu poleceń na urządzeniach użytkowników.
P: Czy identyfikatory urządzeń muszą być unikalne?
O: Identyfikatory powinny być unikalne. Jeśli w usłudze nie masz unikalnych identyfikatorów, muszą one być unikalne przynajmniej na poziomie użytkownika. Wyobraź sobie użytkownika, który ma kilka domów, a w każdym z nich jest integracja z tym samym użytkownikiem. Poproszenie o włączenie światła w jednym domu nie powinno włączać światła o tym samym identyfikatorze w innym domu.
P: Czy nazwy urządzeń muszą być unikalne?
O: Nazwy nie muszą być unikalne, ale z czasem możemy zachęcać użytkowników do poprawiania nieprawidłowych nazw po skonfigurowaniu, aby poprawić wygodę użytkowania.
Oto krótki przewodnik po nazwach:
- Nazwy powinny być takie, aby użytkownicy mogli je wypowiedzieć.
- Rozpoznajemy podzbiory ciągów znaków, więc jeśli masz „acme color light”, odpowiemy też na „acme light”.
- Zachęcamy do używania zarówno opisowej nazwy produktu, jak i co najmniej jednej nazwy zdefiniowanej przez użytkownika.
- Użytkownicy nie muszą podawać nazw pomieszczeń, ponieważ mamy do tego odpowiednie funkcje. Nazwy powinny być unikalne w każdym pomieszczeniu, ale zawsze można używać liczby mnogiej, aby sterować wszystkim (np. 2 żarówki w kinkietach w biurze to „światło północne” i „światło wschodnie”, ale można nimi sterować za pomocą polecenia „światła”).
P: Jak często aktualizowany jest stan urządzenia?
O: Stan tymczasowy jest pobierany po wykonaniu zapytania lub polecenia, czyli działań zainicjowanych przez użytkownika. Jeśli użytkownik zapyta „Czy światło jest włączone?” lub będzie chciał rozjaśnić światło, musimy wysłać zapytanie, aby sprawdzić aktualny stan.
P: Czy można bezpośrednio aktualizować Home Graph o aktualny stan urządzenia?
O: Tak, użyj wywołania interfejsu Report State API.
Łączenie kont i OAuth
P: Czy musimy łączyć konta?
O: Tak, łączenie kont jest wymagane, aby połączyć urządzenia użytkownika z usługami w chmurze dostawcy.
P: W przypadku OAuth tokeny dostępu wygasają co 15,213 godziny.Czy to jest w porządku?
O: Tak, ale przetestuj to z dość krótkim czasem wygaśnięcia, np. 10–20 minut. Nasz klient OAuth powinien odświeżać tokeny w razie potrzeby, a testowanie z krótkim czasem wygaśnięcia potwierdzi, że to działa.
Intencje
P: Kiedy następuje synchronizacja?
O: Synchronizacja następuje natychmiast po zakończeniu OAuth i po wywołaniu funkcji Request Sync.
P: Dlaczego SYNC nie działa?
O: Może to być spowodowane kilkoma typowymi przyczynami.
Wysyłasz nieprawidłowe typy urządzeń.
- Na przykład oczekujemy
action.devices.types.LIGHT, ale wysyłaszaction.devices.types.Light.
- Na przykład oczekujemy
Wysyłasz nieobsługiwane typy urządzeń.
- Na przykład wysyłasz
action.devices.types.FLASHLIGHT– nie obsługujemy tego.
- Na przykład wysyłasz
Wysyłasz nieprawidłowe lub nieobsługiwane pola.
- Na przykład masz pole, które nie jest zgodne z naszą specyfikacją.
W odpowiedzi SYNC występuje inny problem z formatowaniem.
- Sprawdź nawiasy.
Występuje problem z łączeniem kont.
- Sprawdź, czy w nagłówku Auth żądania SYNC otrzymujesz prawidłowy token dostępu.
Zbyt długo odpowiadasz na żądanie SYNC.
- Sprawdź, czy odpowiadasz na żądanie SYNC w ciągu 5 sekund.
P: Czy odpowiedź „oczekujące” jest prawidłowa?
O: Jeśli Twoje urządzenia są dostępne w czasie rzeczywistym, zdecydowanie preferujemy odpowiedź „sukces” lub „niepowodzenie” zamiast „oczekujące”. Skontaktuj się z nami, jeśli uważasz, że potrzebujesz odpowiedzi „oczekujące”. Wiemy, że niektóre urządzenia o niskim poborze mocy, które nie działają w czasie rzeczywistym, mogą wymagać odpowiedzi „oczekujące” i asynchronicznego modelu wykonywania.
Testowanie i przesyłanie
P: Czy możemy skonfigurować środowisko programistyczne w chmurze?
O: Tak, możesz testować nieuruchomione środowisko i konfigurację w chmurze.
P: Moja akcja nie jest widoczna w sekcji Sterowanie domem w aplikacji Google Home. Co się dzieje?
O: Sprawdź, czy jesteś deweloperem tego projektu.
Raportowanie stanu
P: Czy istnieją wymagania wstępne dotyczące implementacji raportowania stanu?
O: Projekt musi korzystać z interfejsu Smart Home API, obsługiwać OAuth2 i mieć cechy, które mają stany do zgłoszenia.
P: Jak często musimy raportować stan urządzenia?
O: Google interesuje przejście i stan końcowy. Jeśli jednak w krótkim czasie nastąpi wiele zmian stanu (np. użytkownik otworzy i zamknie lodówkę 3 razy w ciągu minuty lub przesunie suwak ściemniacza), musimy zgłosić tylko stan końcowy.
P: Czy podczas wywoływania funkcji Report State trzeba wysyłać pełny stan urządzenia?
O: Częściowe aktualizacje stanu nie są obsługiwane, dlatego Report State wywołania powinny zawsze zawierać wszystkie dane dotyczące danej cechy, która została zaktualizowana. Jeśli 2 cechy powodują niespójność, należy je zgłosić razem.
P: Czy Google może wysyłać zapytania do mojego urządzenia, aby uzyskać jego stan (czyli odpytywać urządzenie)?
O: Jest to mechanizm rezerwowy, którego nie zalecamy. Jeśli będziemy musieli często odpytywać urządzenie w przypadku tych użytkowników, nie możemy zagwarantować, jakie będzie dodatkowe obciążenie. Wynika to z nowych powierzchni wizualnych. Oprócz problemu z nieznanym obciążeniem spowoduje to pogorszenie wygody użytkowników. Uważamy, że Report State jest kluczowe dla platformy.
P: Które cechy obsługują obecnie raportowanie stanu?
O: Obsługiwane są wszystkie cechy publiczne, które mają powiązane stany. Należy też zgłosić każdą zmianę stanu urządzenia na „online”.
Pamiętaj, że sceny nie mają stanów. Mogą jednak powodować zmianę stanu urządzeń. Jeśli stan dowolnego urządzenia w Google Home Graph ulegnie zmianie, należy to zgłosić.
P: Czy raportowanie stanu wymaga wysłania sygnatury czasowej?
O: Nie wymagamy sygnatury czasowej. Ostatni wysłany stan zastąpi poprzednie wywołania.
P: Czy muszę raportować stan osobno, jeśli wysyłam już stan w zapytaniu lub poleceniu?
O: Home Graph przechowuje tylko stan wysłany za pomocą Report State. Stan zwracany w odpowiedzi na intencje EXECUTE i QUERY jest używany tylko do odpowiedzi głosowych dla użytkownika i nie jest przechowywany. W związku z tym należy wywołać funkcję Report State nawet jeśli nowy stan urządzenia został już zwrócony w odpowiedzi na intencję EXECUTE lub QUERY.
P: Jakie są konsekwencje niepełnego wdrożenia raportowania stanu w podanym terminie?
O: Spowoduje to pogorszenie wygody użytkowników, np. w Google Home app (GHA) i na powierzchniach wizualnych. Oznacza to, że wiele intencji QUERY będzie wysyłanych w celu odpytywania stanu, a my nie możemy zagwarantować, jakie będzie dodatkowe obciążenie chmury partnera.
P: Jak mogę przetestować implementację raportowania stanu?
O: Użyj przeglądarki Home Graph – narzędzia do samodzielnego testowania, które pokazuje Twoje aktualne stany urządzeń przechowywane w Home Graph.
P: Czy możemy użyć losowego identyfikatora requestId w przypadku raportowania stanu?
O: Jeśli Report State jest wywoływane przez żądanie EXECUTE, zalecamy, aby partnerzy używali tego samego identyfikatora requestId, który otrzymali w żądaniu EXECUTE. W przeciwnym razie możesz użyć losowego identyfikatora requestId.
P: Jeśli użytkownik ma kilka urządzeń i stan jednego z nich ulegnie zmianie, czy musimy zgłosić najnowszy stan wszystkich urządzeń?
O: Nie. Musisz zgłosić tylko stan tego konkretnego urządzenia.
Sprawdzone metody
P: Jakie opóźnienie jest dopuszczalne?
O: Idealnie, jeśli jest to mniej niż 1000 ms, ale 2–5 s też jest w porządku. Jeśli opóźnienie wynosi około 5 sekund, skontaktuj się z nami.
P: Jak sprawić, aby głośnik aktywowany głosem prawidłowo reagował, gdy jest offline?
O: W przypadku urządzeń offline zwróć stan offline. W przypadku tego błędu zwracamy komunikat „Obecnie niedostępne” w formacie TTS. Więcej informacji znajdziesz w artykule Błędy i wyjątki.