Witamy w Google Home Developer Center – nowym miejscu, z którego dowiesz się, jak tworzyć inteligentne działania domowe. Uwaga: nadal będziesz tworzyć działania w konsoli Actions.

Stan raportu

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Kliknij, aby dodać

Report State to ważna funkcja, dzięki której działanie Home może aktywnie zgłaszać najnowszy stan urządzenia użytkownika do Google Home Graph, zamiast czekać na działanie QUERY.

Report State zgłasza Google stany urządzeń użytkowników z powiązanymi z nimi danymi agentUserId (wysłane w pierwotnym żądaniu SYNC). Gdy Google Assistant chce wykonać działanie, które wymaga zrozumienia bieżącego stanu urządzenia, może przed pobraniem intencji EXECUTE przejrzeć informacje o stanie w Home Graph, zamiast wysyłać intencję QUERY do różnych chmur innych firm.

Bez Report State, z powodu światła pochodzącego od wielu dostawców w salonie, polecenie OK Google, rozjaśnij salon wymaga przypisania wielu intencji QUERY wysłanych do wielu chmur, a nie tylko sprawdzania bieżących wartości jasności na podstawie wcześniej zgłoszonych danych. Aby zapewnić użytkownikom jak najlepsze działanie, Assistant musi mieć obecny stan urządzenia, bez konieczności przesyłania go w obie strony.

Po wstępnym wywołaniu SYNC przez urządzenie platforma wysyła intencję QUERY, która zbiera informacje o stanie urządzenia, aby wypełnić Home Graph. Po tym czasie Home Graph przechowuje tylko stan, który został wysłany za pomocą Report State.

Wywołując atrybut Report State, pamiętaj, aby podać pełne dane stanu dla danego atrybutu. Home Graph aktualizuje stany poszczególnych cech i zastępuje wszystkie dane tego atrybutu w momencie wywołania Report State. Jeśli na przykład raportujesz stan dla cechy StartStop, ładunek musi zawierać wartości zarówno dla isRunning, jak i isPaused.

Pierwsze kroki

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

Włącz Google HomeGraph API

  1. W Google Cloud Platform Console przejdź na stronę HomeGraph API.

    Otwórz stronę HomeGraph API
  2. Wybierz projekt zgodny z identyfikatorem projektu smart home.
  3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

Aby wygenerować klucz konta usługi z GCP Console:

Uwaga: podczas wykonywania tych czynności upewnij się, że używasz właściwego projektu GCP. To jest projekt zgodny z Twoim identyfikatorem projektu smart home.
  1. W aplikacji GCP Console otwórz stronę Utwórz klucz konta usługi.

    Otwórz stronę tworzenia klucza konta usługi
  2. Z listy Konto usługi wybierz Nowe konto usługi.
  3. W polu Nazwa konta usługi wpisz nazwę.
  4. W polu Identyfikator konta usługi wpisz identyfikator.
  5. Z listy Rola wybierz Konta usługi > Twórca tokenów kont usługi.

  6. W polu Typ klucza wybierz opcję JSON.

  7. Kliknij Utwórz. Plik JSON zawierający klucz pobrany na Twój komputer.

Wywoływanie interfejsu API

Wybierz opcję na poniższych kartach:

HTTP

Home Graph udostępnia punkt końcowy HTTP.

  1. Za pomocą pobranego pliku JSON konta usługi utwórz token sieciowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie przy użyciu konta usługi.
  2. Uzyskaj token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph za pomocą oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Utwórz żądanie JSON z agentUserId. Oto przykładowe żądanie JSON dotyczące stanu raportu i powiadomienia:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Połącz stan raportu i plik JSON powiadomienia oraz token z żądania POST w protokole HTTP z punktem końcowym Google Home Graph. Oto przykład, jak wykonać żądanie z poziomu wiersza poleceń curl:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
    

gRPC

Home Graph udostępnia punkt końcowy gRPC.

  1. Pobierz definicję usługi buforowania protokołu dla interfejsu Home Graph API.
  2. Postępuj zgodnie z dokumentacją dla deweloperów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Klient Node.js interfejsu Google API udostępnia powiązania dla interfejsu API Home Graph.

  1. Zainicjuj usługę google.homegraph przy użyciu domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification za pomocą metody ReportStateAndNotificationRequest. Zwraca wartość Promise z atrybutem 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
          }
        }
      }
    }
  }
});
    

Java

Biblioteka klienta interfejsu HomeGraph API dla języka Java udostępnia powiązania interfejsu Home Graph API.

  1. Zainicjuj aplikację HomeGraphApiService przy użyciu domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification za pomocą metody 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 testowego

Aby przygotować swoje działanie do uzyskania certyfikatu, przeprowadź test Report State.

Wymagania wstępne

Aby przetestować działanie, musisz mieć klucz konta usługi i agentUserId. Jeśli masz już klucz konta usługi, agentUserIdi zobacz wdrażanie panelu Report State.

Wdrażanie panelu stanu raportu

Gdy uzyskasz klucz konta usługi i identyfikator użytkownika agenta, pobierz i wdróż najnowszą wersję z panelu Report State. Po pobraniu najnowszej wersji postępuj zgodnie z instrukcjami podanymi w dołączonym pliku README.MD.

Po wdrożeniu panelu Report State otwórz panel z tego adresu URL (zastąp identyfikator_projektu swoim identyfikatorem projektu):

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

W panelu wykonaj te czynności:

  • Wybierz plik klucza konta
  • Dodaj identyfikator UserAgent

Następnie kliknij Lista.

Wyświetli się lista wszystkich Twoich urządzeń. Po wypełnieniu listy możesz użyć przycisku Odśwież, aby zaktualizować stany urządzeń. W przypadku zmiany stanu urządzenia wiersz jest wyróżniony na zielono.

Odpowiedzi na błędy

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

  • 400 Bad Request – serwer nie może przetworzyć żądania wysłanego przez klienta z powodu nieprawidłowej składni. Częstą przyczyną jest zniekształcony kod JSON lub użycie wartości null zamiast „” w przypadku wartości ciągu znaków.
  • 404 Not Found – nie udało się znaleźć żądanego zasobu, ale może on być 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łowe żądanie agentUserId. Sprawdź, czy agentUserId pasuje do wartości w odpowiedzi SYNC i czy obsługujesz intencje DISCONNECT.