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ę

Cloud-to-cloud

Request Sync wywołuje SYNC żądanie do usługi realizacji w przypadku każdego użytkownika Google, który ma urządzenia powiązane z określonym agentUserId (który został wysłany w pierwotnym żądaniu SYNC). Dzięki temu możesz aktualizować urządzenia użytkowników bez odłączania i ponownego łączenia ich kont. Wszyscy użytkownicy powiązani z tym identyfikatorem otrzymają SYNC prośbę.

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 wdrażasz nowy typ urządzenia, cechę lub dodajesz nową funkcję urządzenia.

Rozpocznij

Aby wdrożyć synchronizację żądań, wykonaj te czynności:

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

Włączanie interfejsu Google HomeGraph API

W sekcji Google Cloud Console otwórz stronę HomeGraph API.
Otwórz stronę HomeGraph API
Wybierz projekt, który pasuje do Twojego identyfikatora 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 właściwego projektu GCP. Jest to projekt, który pasuje do Twojego identyfikatora projektu smart home.

W konsoli Google Cloud Console otwórz stronę Konta usługi.
Otwórz stronę Konta usługi.
Zanim przejdziesz na stronę Konta usługi, być może musisz 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.
Wybierz z listy kont usług utworzone przed chwilą 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. Na komputer zostanie pobrany plik JSON zawierający klucz.

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

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.
Uzyskaj token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph za pomocą narzędzia oauth2l:

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

Utwórz żądanie JSON za pomocą znaku agentUserId. Oto przykładowe żądanie w formacie JSON dotyczące żądania synchronizacji:

{
  "agentUserId": "user-123"
}

Połącz JSON żądania synchronizacji i token w żądaniu HTTP POST do punktu końcowego Google Home Graph. Ten przykład pokazuje, jak w ramach testu wysłać żądanie w wierszu poleceń za pomocą 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 buforów protokołu interfejsu Home Graph API.
Postępuj zgodnie z dokumentacją dla deweloperów gRPC, aby wygenerować atrapy klienta w jednym z obsługiwanych języków.
Wywołaj metodę RequestSync.

Node.js

Google APIs Node.js Client udostępnia powiązania z interfejsem Home Graph API.

Zainicjuj usługę google.homegraph za pomocą domyślnych danych logowania aplikacji.
Wywołaj metodę requestSync za pomocą RequestSyncDevicesRequest. Zwraca 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 powiązania z interfejsem Home Graph API.

Zainicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
Wywołaj metodę requestSync z parametrem RequestSyncDevicesRequest. Zwraca pusty 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ływania funkcji Request Sync możesz otrzymać jedną z tych odpowiedzi o błędzie. Odpowiedzi te mają postać kodów stanu HTTP.

400 Bad Request – serwer nie mógł przetworzyć żądania wysłanego przez klienta z powodu nieprawidłowej składni. Częste przyczyny to nieprawidłowy format JSON lub użycie znaku null zamiast znaku cudzysłowu „” w przypadku wartości ciągu znaków.
403 Forbidden – serwer nie mógł przetworzyć żądania dla danego agentUserId z powodu błędu podczas odświeżania tokena. Sprawdź, czy punkt końcowy OAuth prawidłowo odpowiada na żądania tokena odświeżania, i zweryfikuj stan połączenia konta użytkownika.
404 Not Found – nie znaleziono żądanego zasobu, ale może on być dostępny w przyszłości. Zwykle oznacza to, że konto użytkownika nie jest połączone z Google lub otrzymaliśmy nieprawidłowy identyfikator agentUserId. Upewnij się, że wartość agentUserId jest zgodna z wartością podaną w odpowiedzi SYNC i że prawidłowo obsługujesz intencje DISCONNECT.
429 Too Many Requests – przekroczono maksymalną liczbę równoczesnych żądań synchronizacji dla danego agentUserId. Wywołujący może wysłać tylko 1 jednoczesne żądanie synchronizacji, chyba że flaga async ma wartość true.