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.
175

Raport stanu to ważna funkcja, która pozwala inteligentnemu działaniu na stronie głównej informować użytkowników o najnowszym stanie urządzenia z wyprzedzeniem na wykresie na stronie głównej Google, zamiast czekać na działanie QUERY.

Zgłaszaj stan usług Google do stanów urządzeń użytkowników, które są z nimi określone w polu agentUserId (wysłane w pierwotnym żądaniu SYNC). Gdy Asystent Google chce wykonać działanie, które wymaga zrozumienia bieżącego stanu urządzenia, może przed pobraniem intencji EXECUTE sprawdzić informacje o stanie na wykresie głównym, zamiast wysyłać intencję QUERY do różnych chmur.

Biorąc pod uwagę fakt, że różne źródła światła w salonie pochodzą od wielu dostawców, polecenie OK Google, rozjaśnij mój salon wymaga rozpoznania w wielu chmurach wielu intencji QUERY, a nie tylko sprawdzania bieżących wartości jasności na podstawie wcześniejszego raportowania. Aby wygodniej korzystać z usługi, Asystent Google musi mieć informacje o bieżącym stanie urządzenia i nie wymagać przesyłania informacji w obie strony.

Po wstępnym działaniu SYNC, platforma wysyła intencję QUERY, która zbiera informacje o stanie urządzenia, aby zapełnić wykres główny. Od tego momentu wykres na stronie głównej będzie zawierał tylko stan, który został wysłany ze stanem raportu.

Podczas wywoływania stanu raportu podaj pełne dane o danym stanie. Wykres Home aktualizuje stany poszczególnych cech i zastępuje wszystkie dane dla tego atrybutu po wywołaniu stanu raportu. Jeśli na przykład zgłaszasz stan cech StartStop, ładunek musi zawierać wartości zarówno dla isRunning, jak i isPaused.

Pierwsze kroki

Aby zaimplementować stan raportu, wykonaj te czynności:

Włącz interfejs Google HomeGraph API

  1. W konsoli Google Cloud Platform otwórz stronę HomeGraph API.

    Wejdź na stronę HomeGraph API
  2. Wybierz projekt, który pasuje do identyfikatora Twojego projektu inteligentnego domu.
  3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

Aby wygenerować klucz konta usługi z konsoli GCP, wykonaj te czynności:

Uwaga: podczas wykonywania tych czynności upewnij się, że używasz odpowiedniego projektu GCP. To jest projekt zgodny z identyfikatorem Twojego inteligentnego domu.
  1. W konsoli GCP 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 konta usługi.

  6. W polu Typ klucza wybierz opcję JSON.

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

Wywoływanie interfejsu API

Wybierz jedną z kart poniżej:

HTTP

Home Graph API udostępnia punkt końcowy HTTP.

  1. Użyj tokena JSON pobranego konta usługi, aby utworzyć token sieciowy JSON (JWT). Więcej informacji znajdziesz w artykule Uwierzytelnianie za pomocą 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 za pomocą 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 kod JSON powiadomień, a token w żądaniu POST w protokole HTTP z punktem końcowym Google Home Graph. Ten przykład pokazuje, jak wysłać żądanie w wierszu poleceń przy użyciu 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 API udostępnia punkt końcowy gRPC.

  1. Pobierz definicję usługi buforów protokołu dla interfejsu Home Graph API.
  2. Wykonaj instrukcje podane w dokumentacji dla deweloperów gRPC, aby wygenerować klucze klienta dla jednego z obsługiwanych języków.
  3. Wywołaj metodę ReportStateAndNotification.

Node.js

Klient Node.js interfejsów API Google zapewnia powiązania z interfejsem Home Graph API.

  1. zainicjuj usługę google.homegraph przy użyciu domyślnych danych logowania aplikacji.
  2. Wywołaj metodę reportStateAndNotification za pomocą ReportStateAndNotificationRequest. Zwraca wartość Promise z wartością 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 zapewnia powiązania z Home Graph API.

  1. Zainicjuj interfejs 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, warto najpierw przetestować stan raportu.

Wymagania wstępne

Aby przetestować działanie, musisz mieć klucz konta usługi i agentUserId. Jeśli masz już klucz konta usługi, aagentUserId zapoznaj się z artykułem Wdrażanie panelu stanu raportu,

Wdrażanie panelu stanu raportu

Gdy uzyskasz w projekcie dostęp do klucza konta usługi i identyfikatora UserAgent, pobierz i wdróż najnowszą wersję z panelu stanu raportu. Po pobraniu najnowszej wersji postępuj zgodnie z instrukcjami z dołączonego pliku README.MD.

Po wdrożeniu panelu stanu raportu przejdź do panelu 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.

Zobaczysz listę wszystkich urządzeń. Po wypełnieniu listy możesz zaktualizować stan urządzenia za pomocą przycisku Odśwież. W przypadku zmiany stanu urządzenia wiersz jest wyróżniony na zielono.

Odpowiedzi na błąd

Podczas wywoływania stanu raportu możesz zobaczyć jedną z tych odpowiedzi dotyczących błędów. Odpowiedzi te 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ą są nieprawidłowy format JSON lub użycie ciągu null zamiast „” jako wartości ciągu.
  • 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. Upewnij się, że agentUserId odpowiada wartości podanej w odpowiedzi SYNC i że obsługujesz intencje DISCONNECT.