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.

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

Poproś o synchronizację

Punkt kluczowy: aby przesłać działanie smart home, musisz zaimplementować synchronizację żądań.

Prośba o synchronizację powoduje wysłanie SYNC do Twojego systemu do przetwarzania zamówień w przypadku każdego użytkownika Google, którego urządzenia są powiązane z określonym agentUserId (który został wysłany w ramach pierwotnego żądania synchronizacji). Dzięki temu możesz aktualizować urządzenia użytkowników bez odłączania i ponownie łączenia ich kont. Wszyscy użytkownicy powiązani z tym identyfikatorem otrzymają żądanie SYNC.

Musisz wywołać żądanie SYNC:

Jeśli użytkownik doda nowe urządzenie.
Jeśli użytkownik usunie już używane urządzenie.
Jeśli użytkownik zmieni nazwę istniejącego urządzenia.
Jeśli wdrożysz nowy typ urządzenia, cechę lub funkcję urządzenia.

Rozpocznij

Aby wdrożyć funkcję synchronizacji żądań:

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 Google Cloud Console, wykonaj te instrukcje:

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

W panelu Google Cloud Console otwórz stronę Utwórz klucz konta usługi.
Otwórz stronę tworzenia klucza konta usługi
Z listy Konto usługi wybierz Nowe konto usługi.
W polu Nazwa konta usługi wpisz nazwę.
W polu Identyfikator konta usługi wpisz identyfikator.
Na liście Rola wybierz Konta usługi > Twórca tokena konta usługi.
W polu Typ klucza wybierz opcję JSON.
Kliknij Utwórz. Na komputer zostanie pobrany plik JSON zawierający klucz.

Wywoływanie interfejsu API

HTTP

Interfejs Home Graph API 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 o uwierzytelnianiu 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ą agentUserId. Oto przykładowa prośba o synchronizację w formacie JSON:

{
  "agentUserId": "user-123"
}

Połącz żądanie synchronizacji w formacie JSON z tokenem w żądaniu HTTP POST z punktem końcowym Google Home Graph. Oto przykład żądania wysyłanego w wierszu 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:requestSync"

gRPC

Interfejs Home Graph API udostępnia punkt końcowy gRPC.

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

Node.js

Interfejs Node.js dla interfejsów Google API zapewnia powiązania dla interfejsu Home Graph API.

Zainicjuj usługę google.homegraph przy użyciu domyślnych danych logowania aplikacji.
Wywołaj metodę requestSync za pomocą RequestSyncDevicesRequest. Zwraca ona odpowiedź Promise z pustym elementem RequestSyncDevicesResponse.

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

const res = await homegraphClient.devices.requestSync({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    async: false
  }
});

Java

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ę requestSync za pomocą funkcji RequestSyncDevicesRequest. Zwraca pustą 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();

// Request sync.
RequestSyncDevicesRequest request =
    new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false);
homegraphService.devices().requestSync(request);

Odpowiedzi na błędy

Podczas wywołania metody RequestSync może pojawić się jeden z tych komunikatów 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 nieprawidłowej składni. Typowe przyczyny to źle sformatowany plik JSON lub użycie znaku null zamiast znaku „” w przypadku wartości ciągu znaków.
403 Forbidden – serwer nie mógł przetworzyć żądania dotyczącego danego agentUserId z powodu błędu podczas odświeżania tokena. Upewnij się, że punkt końcowy OAuth odpowiada prawidłowo na prośby o odświeżenie tokena, i sprawdź stan łączenia konta użytkownika.
404 Not Found – nie znaleziono żądanego zasobu, ale może być on dostępny w przyszłości. Zwykle oznacza to, ż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 SYNC i że poprawnie obsługujesz intencje DISCONNECT.
429 Too Many Requests – została przekroczona maksymalna liczba równoczesnych żądań synchronizacji dla: agentUserId. Wywołujący może wysłać tylko jedno żądanie synchronizacji równoległej, chyba że flaga async jest ustawiona na wartość true.