Poproś o synchronizację

Żądanie synchronizacji uruchamia w Twojej realizacji żądanie SYNC w przypadku dowolnego użytkownika Google z urządzeniami, z którymi są powiązane określone agentUserId (które zostało wysłane przez Ciebie w pierwotnym żądaniu SYNC). Dzięki temu możesz aktualizować urządzenia użytkowników bez rozłączania i ponownego łączenia ich kont. Wszyscy użytkownicy związani z tym identyfikatorem otrzymają żądanie SYNC.

Musisz wywołać żądanie SYNC:

  • Gdy 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;
  • wdrożysz nowy typ urządzenia lub nową cechę urządzenia albo dodasz do niego nową funkcję;

Rozpocznij

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

Włącz interfejs Google HomeGraph API

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

    Otwórz stronę interfejsu HomeGraph API
  2. Wybierz projekt pasujący do identyfikatora projektu w smart home.
  3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

Aby wygenerować klucz konta usługi z Google Cloud Console, wykonaj te czynności:

Uwaga: podczas wykonywania tych czynności sprawdź, czy używasz właściwego projektu GCP. Ten projekt pasuje do identyfikatora projektu w smart home.
  1. W sekcji Google Cloud Console otwórz stronę Tworzenie klucza konta usługi.

    Otwórz stronę Tworzenie klucza konta usługi
  2. Z listy Konto usługi wybierz Nowe konto usługi.
  3. W polu Nazwa konta usługi wpisz nazwę.
  4. W polu Identyfikator konta usługi wpisz identyfikator.
  5. Z listy Rola wybierz Konta usługi > Twórca tokenów konta usługi.

  6. W polu Typ klucza wybierz opcję JSON.

  7. Kliknij Utwórz. Plik JSON zawierający klucz zostanie pobrany na Twój komputer.

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 sieciowy JSON (JWT). Więcej informacji znajdziesz w sekcji Uwierzytelnianie 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
    
  4. Utwórz żądanie JSON z atrybutem agentUserId. Oto przykładowe żądanie JSON dla żądania Synchronizacji:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Połącz plik JSON synchronizacji żądania HTTP i token w żądaniu HTTP POST z punktem końcowym Google Home Graph. Oto przykład, jak w ramach testu wysłać żądanie w wierszu poleceń za pomocą polecenia curl:
  7. 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 zapewnia punkt końcowy gRPC

  1. Pobierz definicję usługi buforów protokołów dla interfejsu Home Graph API.
  2. Postępuj zgodnie z dokumentacją dla programistów gRPC, aby wygenerować namiastki klienta dla jednego z obsługiwanych języków.
  3. Wywołaj metodę RequestSync.

Node.js

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

  1. Zainicjuj usługę google.homegraph za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę requestSync za pomocą żądania RequestSyncDevicesRequest. Zwraca wartość Promise z pustą wartością 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 interfejsu HomeGraph API dla języka Java zawiera powiązania dla interfejsu Home Graph API.

  1. Zainicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę requestSync za pomocą metody 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 z błędami

Po wywołaniu żądania synchronizacji możesz otrzymać jeden z poniższych komunikatów o błędach. 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łowy format JSON lub użycie null zamiast „” dla wartości ciągu.
  • 403 Forbidden – serwer nie mógł przetworzyć żądania dotyczącego podanej wartości agentUserId z powodu błędu podczas odświeżania tokena. Zadbaj o to, aby punkt końcowy OAuth odpowiadał prawidłowo, aby odświeżyć żądania tokenów, i sprawdź stan połączenia kont użytkownika.
  • 404 Not Found – nie udało się znaleźć żą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. Sprawdź, czy agentUserId jest zgodna z wartością podaną w odpowiedzi SYNC i poprawnie obsługujesz intencje DISCONNECT.
  • 429 Too Many Requests – maksymalna liczba jednoczesnych żądań synchronizacji została przekroczona dla określonej wartości agentUserId. Element wywołujący może wysłać tylko 1 jednoczesne żądanie synchronizacji, chyba że flaga async ma wartość Prawda.