Witamy w Centrum dla deweloperów Google Home, nowym miejscu, w którym dowiesz się, jak tworzyć działania dla inteligentnego domu.

Ta strona została przetłumaczona przez Cloud Translation API.

Stan raportu
bookmark_border Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Punkt kluczowy: aby przesłać integrację Cloud-to-cloud, musisz wdrożyć Report State.

Report State to ważna funkcja, która umożliwia akcji Google Home proaktywnie zgłaszanie najnowszego stanu urządzenia użytkownika do usługi Google Home Graph zamiast czekania na intencję QUERY.

Report State przesyła do Google stany urządzeń użytkowników z powiązanymi z nimi określonymi agentUserId (wysłanymi w pierwotnym żądaniu SYNC). Gdy Google Assistant chce podjąć działanie, które wymaga poznania bieżącego stanu urządzenia, może po prostu sprawdzić informacje o stanie w Home Graph zamiast wysyłać intencję QUERY do różnych chmur innych firm przed wysłaniem intencji EXECUTE.

Bez Report State, jeśli w salonie są światła od różnych dostawców, polecenie OK Google, rozjaśnij światło w salonie wymaga rozwiązania wielu QUERY intencji wysłanych do wielu chmur, zamiast po prostu sprawdzenia bieżących wartości jasności na podstawie wcześniejszych danych. Aby zapewnić użytkownikom jak najlepsze wrażenia, Assistant musi znać bieżący stan urządzenia bez konieczności wielokrotnego łączenia się z nim.

Po początkowym SYNC urządzenia platforma wysyła intencję QUERY, która zbiera stan urządzenia, aby wypełnić Home Graph. Po tym czasie Home Graph przechowuje tylko stan wysłany z Report State.

Podczas wywoływania funkcji Report State pamiętaj, aby podać pełne dane stanu danej cechy. Home Graph aktualizuje stany na podstawie atrybutu i zapisuje wszystkie dane dotyczące tego atrybutu, gdy zostanie wywołane Report State. Jeśli na przykład przekazujesz stan atrybutu StartStop, ładunek musi zawierać wartości zarówno dla isRunning, jak i isPaused.

Rozpocznij

Aby wdrożyć Report State, wykonaj te czynności:

Włącz interfejs Google HomeGraph API
Tworzenie klucza konta usługi
Wywoływanie interfejsu API

Włącz interfejs Google HomeGraph API

W Google Cloud Console otwórz stronę HomeGraph API.
Otwórz stronę interfejsu HomeGraph API
Wybierz projekt, który odpowiada Twojemu identyfikatorowi projektu smart home.
Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

Aby wygenerować klucz konta usługi z poziomu Google Cloud Console, wykonaj te czynności:

Uwaga: podczas wykonywania tych czynności upewnij się, że używasz prawidłowego projektu Google Cloud Platform. Jest to projekt, który pasuje do identyfikatora projektu smart home.

W Google Cloud Console otwórz stronę Konta usługi.
Otwórz stronę Konta usługi.
Zanim przejdziesz na stronę Konta usługi, musisz może wybrać projekt.
Kliknij Utwórz konto usługi.
W polu Nazwa konta usługi wpisz nazwę.
W polu Identyfikator konta usługi wpisz identyfikator.
W polu Opis konta usługi wpisz opis.
Kliknij Utwórz i kontynuuj.
W menu Rola wybierz Konta usługi > Twórca tokenów tożsamości OpenID Connect konta usługi.
Kliknij Dalej.
Kliknij Gotowe.
Na liście kont usług wybierz właśnie utworzone konto usługi i w menu Działania kliknij Zarządzaj kluczami.
Kliknij Dodaj klucz > Utwórz nowy klucz.
W polu Typ klucza wybierz opcję JSON.
Kliknij Utwórz. Plik JSON zawierający klucz zostanie pobrany na komputer.

Szczegółowe instrukcje i informacje o tworzeniu kluczy kont usługi znajdziesz w artykule Tworzenie i usuwanie kluczy kont usługi w Centrum pomocy Google Cloud Console.

Wywoływanie interfejsu API

Wybierz opcję na poniższych kartach:

HTTPgRPCNode.jsJava

Usługa Home Graph udostępnia punkt końcowy HTTP.

Użyj pobranego pliku JSON konta usługi, aby utworzyć token internetowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie za pomocą konta usługi.
Aby uzyskać token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph, użyj polecenia oauth2l:

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

Utwórz żądanie JSON za pomocą interfejsu API agentUserId. Oto przykładowa prośba w formacie JSON dotycząca stanu raportu i powiadomienia:

{
  "requestId": "123ABC",
  "agentUserId": "user-123",
  "payload": {
    "devices": {
      "states": {
        "light-123": {
          "on": true
        }
      }
    }
  }
}

Połącz stan zgłoszenia i token w pliku JSON powiadomienia z żądaniem HTTP POST do punktu końcowego Google Home Graph. Oto przykład żądania wysyłanego z poziomu wiersza poleceń za pomocą polecenia curl:

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

Usługa Home Graph udostępnia punkt końcowy gRPC

Pobierz definicję usługi protocol buffers dla interfejsu Home Graph API.
Aby wygenerować atrapy klienta dla jednego z obsługiwanych języków, postępuj zgodnie z instrukcjami podanymi w dokumentacji dla deweloperów gRPC.
Wywołaj metodę ReportStateAndNotification.

Interfejs Node.js Client API od Google udostępnia powiązania dla interfejsu API Home Graph.

Inicjuje usługę google.homegraph za pomocą domyślnych danych logowania aplikacji.
Wywołaj metodę reportStateAndNotification z parametrem ReportStateAndNotificationRequest. Zwraca Promise z ReportStateAndNotificationResponse.

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});

Biblioteka klienta HomeGraph API dla języka Java udostępnia elementy wiążące dla interfejsu Home Graph API.

Inicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
Wywołaj metodę reportStateAndNotification z parametrem ReportStateAndNotificationRequest. Zwraca wartość ReportStateAndNotificationResponse.

  // Get Application Default credentials.
  GoogleCredentials credentials =
      GoogleCredentials.getApplicationDefault()
          .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

  // Create Home Graph service client.
  HomeGraphService homegraphService =
      new HomeGraphService.Builder(
              GoogleNetHttpTransport.newTrustedTransport(),
              GsonFactory.getDefaultInstance(),
              new HttpCredentialsAdapter(credentials))
          .setApplicationName("HomeGraphExample/1.0")
          .build();

  // Build device state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request);
}

Stan raportu z testu

Wyświetlający Home Graph

Zalecane narzędzia do wykonania tego zadania

Aby przygotować integrację Cloud-to-cloud do certyfikacji, ważne jest przetestowanie Report State.

W tym celu zalecamy użycie narzędzia Home Graph Viewer, które jest samodzielną aplikacją internetową, która nie wymaga pobierania ani wdrażania.

Panel Report State jest nadal dostępny, ale został wycofany i nie jest już obsługiwany.

Panel stanu raportu

Wymagania wstępne

Zanim przetestujesz integrację z Cloud-to-cloud, musisz mieć klucz konta usługi i agentUserId. Jeśli masz już klucz konta usługi i agentUserId, zapoznaj się z artykułem Wdrażanie paneluReport State.

Jak utworzyć klucz konta usługi

Aby wygenerować klucz konta usługi z poziomu Google Cloud Console, wykonaj te czynności:

Uwaga: podczas wykonywania tych czynności upewnij się, że używasz prawidłowego projektu Google Cloud Platform. Jest to projekt, który pasuje do identyfikatora projektu smart home.

W Google Cloud Console otwórz stronę Konta usługi.
Otwórz stronę Konta usługi.
Zanim przejdziesz na stronę Konta usługi, musisz może wybrać projekt.
Kliknij Utwórz konto usługi.
W polu Nazwa konta usługi wpisz nazwę.
W polu Identyfikator konta usługi wpisz identyfikator.
W polu Opis konta usługi wpisz opis.
Kliknij Utwórz i kontynuuj.
W menu Rola wybierz Konta usługi > Twórca tokenów tożsamości OpenID Connect konta usługi.
Kliknij Dalej.
Kliknij Gotowe.
Na liście kont usług wybierz właśnie utworzone konto usługi i w menu Działania kliknij Zarządzaj kluczami.
Kliknij Dodaj klucz > Utwórz nowy klucz.
W polu Typ klucza wybierz opcję JSON.
Kliknij Utwórz. Plik JSON zawierający klucz zostanie pobrany na komputer.

Szczegółowe instrukcje i informacje o tworzeniu kluczy kont usługi znajdziesz w artykule Tworzenie i usuwanie kluczy kont usługi w Centrum pomocy Google Cloud Console.

Jak pobrać agentUserId

Aby odzyskać agentUserId:

Otwórz narzędzia OAuth Playground.
Kliknij ikonę koła zębatego w prawym górnym rogu, aby otworzyć okno Konfiguracja OAuth 2.0.
W polu Punkty końcowe OAuth wybierz Niestandardowe.
Podaj te parametry łączenia kont, używając wartości ustawionych w konsoli Actions podczas tworzenia projektu inteligentnego domu. Kliknij Zamknij, aby zapisać zmiany.
- Punkt końcowy autoryzacji: w konsoli ustaw ten parametr na URL autoryzacji.
- Punkt końcowy tokena: w konsoli ustaw ten parametr na URL tokena.
- Identyfikator klienta OAuth: ustaw tę wartość taką samą jak w konsoli.
- Tajne hasło klienta OAuth: ustaw tę wartość taką samą jak w konsoli.
Rysunek 1.Konfiguracja OAuth 2.0
Rozwiń Krok 1. Wybierz i autoryzuj interfejsy API. W polu tekstowym „Podaj własne zakresy” wpisz „urządzenia” i kliknij Autoryzuj interfejsy API.
Uwaga: jeśli w konsoli zostały określone dodatkowe zakresy, musisz je też podać w kroku 1.
Jeśli poprzedni krok zakończył się powodzeniem, zostaniesz przekierowany do punktu końcowego OAuth. Zaloguj się na konto użytkownika, które chcesz przetestować. Po zalogowaniu się zostaniesz przekierowany z powrotem do narzędzia OAuth Playground, gdzie krok 2 będzie rozwinięty i zawierać będzie wygenerowany dla Ciebie kod autoryzacji.
Aby uzyskać token odświeżania i token dostępu, kliknij Wymień autoryzowany kod na tokeny.
W sekcji Krok 3. Skonfiguruj żądanie do interfejsu API wykonaj te czynności:
1. Ustaw Metoda HTTP na POST.
2. Ustaw parametr Request URI na adres URL realizacji.
3. Kliknij Wpisz treść żądania i dodaj ten przykładowy tekst:
```
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.SYNC"
  }]
}
        
```
4. Kliknij Wyślij prośbę.
W odpowiedzi znajdź wartość pola „agentUserId”.

Wdrażanie panelu Stan raportu

Gdy masz klucz konta usługi i identyfikator użytkownika agenta dla projektu, pobierz najnowszą wersję z Report StatePulpit. Po pobraniu najnowszej wersji postępuj zgodnie z instrukcjami zawartymi w dołączonym pliku README.MD.

Po wdrożeniu panelu Report State możesz uzyskać do niego dostęp, korzystając z tego adresu URL (zastąp your_project_id identyfikatorem projektu):

http://<your-project-id>.appspot.com

W panelu wykonaj te czynności:

Wybierz plik klucza konta
Dodaj agentUserId

Następnie kliknij Lista.

Wszystkie Twoje urządzenia są widoczne na liście. Po wypełnieniu listy możesz użyć przycisku Odśwież, aby zaktualizować stany urządzeń. Jeśli nastąpiła zmiana stanu urządzenia, wiersz zostanie wyróżniony na zielono.

Odpowiedzi na błędy

Podczas wywoływania funkcji Report State możesz otrzymać jedną z tych odpowiedzi o błędzie. Te odpowiedzi mają postać kodów stanu HTTP.

400 Bad Request – serwer nie może przetworzyć żądania wysłanego przez klienta z powodu błędnej składni. Typowe przyczyny to źle sformatowany plik JSON lub użycie znaku null zamiast znaku „” w przypadku wartości ciągu znaków.
404 Not Found – nie znaleziono żądanego zasobu, ale może być on dostępny w przyszłości. Zwykle oznacza to, że nie możemy znaleźć żądanego urządzenia. Może to też oznaczać, że konto użytkownika nie jest połączone z Google lub otrzymaliśmy nieprawidłowy adres agentUserId. Upewnij się, że agentUserId jest zgodny z wartością w odpowiedzi na żądanie SYNC, i prawidłowo obsłuż intencje DISCONNECT.

Wstecz

Poproś o synchronizację

Dalej

Wysyłanie powiadomień

Stan raportu bookmark_borderbookmark Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Stan raportu
bookmark_border Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.