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ślonymi agentUserId (które zostały wysłane 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 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, może być konieczne wybranie projektu.
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 z użyciem znaku agentUserId. Oto przykładowe żądanie synchronizacji w formacie JSON:

{
  "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 wysłać żądanie w wierszu poleceń za pomocą curl w celu przetestowania:

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 Home Graph 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ęstą przyczyną jest nieprawidłowy format JSON lub użycie znaku null zamiast cudzysłowu w przypadku wartości tekstowej.
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 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 jest ustawiona na wartość true.