Poproś o synchronizację

Żądanie synchronizacji wywołuje żądanie SYNC do 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ą prośbę o 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 wdrażasz nowy typ urządzenia, cechę lub dodajesz nową funkcję urządzenia.

Rozpocznij

Aby zaimplementować żądanie synchronizacji, wykonaj te czynności:

Włączanie interfejsu Google HomeGraph API

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

    Otwórz stronę HomeGraph API
  2. Wybierz projekt, który odpowiada identyfikatorowi projektu smart home.
  3. 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.

  1. W 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.

  2. Kliknij Utwórz konto usługi.

  3. W polu Nazwa konta usługi wpisz nazwę.

  4. W polu Identyfikator konta usługi wpisz identyfikator.

  5. W polu Opis konta usługi wpisz opis.

  6. Kliknij Utwórz i kontynuuj.

  7. W menu Rola wybierz Konta usługi > Twórca tokenów tożsamości OpenID Connect konta usługi.

  8. Kliknij Dalej.

  9. Kliknij Gotowe.

  10. Wybierz utworzone konto usługi z listy kont usługi i wybierz Zarządzaj kluczami z menu Działania.

  11. Kliknij Dodaj klucz > Utwórz nowy klucz.

  12. W polu Typ klucza wybierz opcję JSON.

  13. 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 na stronie pomocy konsoli Google Cloud.

Wywoływanie interfejsu API

HTTP

Interfejs Home Graph API udostępnia punkt końcowy HTTP,

  1. Użyj pobranego pliku JSON konta usługi, aby utworzyć token internetowy JSON (JWT). Więcej informacji znajdziesz w artykule na temat uwierzytelniania 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
  3. Utwórz żądanie JSON za pomocą agentUserId. Oto przykładowe żądanie JSON dotyczące żądania synchronizacji:
    4. {
  "agentUserId": "user-123"
}
  4. Połącz kod JSON żądania synchronizacji i token w żądaniu HTTP POST do punktu końcowego Google Home Graph. Oto przykład, jak w ramach testu wysłać żądanie w wierszu poleceń za pomocą curl:
    5. 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.

  1. Pobierz definicję usługi buforów protokołu dla interfejsu Home Graph API.
  2. Postępuj zgodnie z dokumentacją dla deweloperów gRPC, aby wygenerować kody pośredniczące klienta w jednym z obsługiwanych języków.
  3. Wywołaj metodę RequestSync.

Node.js

Klient interfejsów API Google dla Node.js udostępnia powiązania dla interfejsu Home Graph API.

  1. Zainicjuj usługę google.homegraph przy użyciu domyślnego uwierzytelniania aplikacji.
  2. Wywołaj metodę requestSync za pomocą RequestSyncDevicesRequest. Zwraca Promise z pustym 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 dla interfejsu Home Graph API.

  1. Zainicjuj HomeGraphApiService za pomocą domyślnego uwierzytelniania aplikacji.
  2. Wywołaj metodę requestSync z RequestSyncDevicesRequest. Zwraca pusty obiekt 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 żądania synchronizacji 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. Typowe przyczyny to nieprawidłowo sformatowany kod JSON lub użycie null zamiast „” w przypadku wartości ciągu znaków.
  • 403 Forbidden – serwer nie mógł przetworzyć żądania dla podanego agentUserId z powodu błędu podczas odświeżania tokena. Upewnij się, że punkt końcowy protokołu OAuth prawidłowo odpowiada na żądania tokena odświeżania, i sprawdź 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 parametr agentUserId. Upewnij się, że agentUserId odpowiada wartości podanej w odpowiedzi SYNC i że prawidłowo obsługujesz intencje DISCONNECT.
  • 429 Too Many Requests – przekroczono maksymalną liczbę równoczesnych żądań synchronizacji dla: agentUserId. Wywołujący może wysłać tylko jedno równoczesne żądanie synchronizacji, chyba że flaga async jest ustawiona na wartość „true”.
Wstecz
Odłącz
Dalej
Wdróż stan raportu