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.

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

Cloud-to-cloud

Synchronizacja żądań powoduje wysłanie SYNC do Twojego systemu do przetwarzania żądań dla 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ą prośbę SYNC.

Musisz wywołać żądanie SYNC:

Jeśli użytkownik doda nowe urządzenie.
Jeśli użytkownik usunie istniejące 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ć synchronizację żą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 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

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 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ą agentUserId. Oto przykład żądania JSON do synchronizacji żądań:

{
  "agentUserId": "user-123"
}

Połącz dane JSON żądania synchronizacji z tokenem w żądaniu 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: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 dla jednego 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 udostępnia powiązania dla interfejsu Home Graph API.

Inicjuje usługę google.homegraph przy użyciu domyślnych danych logowania aplikacji.
Wywołaj metodę requestSync z parametrem 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 z parametrem 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 żądania odświeżania 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 wartość agentUserId odpowiada wartości podanej w odpowiedzi na żądanie SYNC, i sprawdź, czy prawidłowo obsługujesz intencje DISCONNECT.
429 Too Many Requests – w przypadku danego agentUserId przekroczono maksymalną liczbę równoczesnych żądań synchronizacji. Wywołujący może wysłać tylko jedno żądanie synchronizacji równoległej, chyba że flaga async jest ustawiona na wartość true.