Poproś o synchronizację

Synchronizacja żądań wyzwala żądanie SYNC na realizację zamówień, które obejmuje wszystkich użytkowników Google z przypisanymi do niego danymi agentUserId (wysłanymi 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 połączeni z tym identyfikatorem otrzymają żądanie SYNC.

Musisz wywołać żądanie SYNC:

  • Jeśli użytkownik doda nowe urządzenie.
  • Usuwając istniejące urządzenie
  • Jeśli użytkownik zmieni nazwę istniejącego urządzenia.
  • Jeśli wdrażasz nowy typ urządzenia, przypisujesz nową cechę lub dodajesz nową funkcję.

Rozpocznij

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

Włącz interfejs Google HomeGraph API

  1. W Google Cloud Console przejdź do strony HomeGraph API.

    Otwórz stronę interfejsu HomeGraph API
  2. Wybierz projekt zgodny z identyfikatorem projektu smart home.
  3. Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

Aby wygenerować klucz konta usługi z Google Cloud Console:

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

    Otwórz stronę tworzenia 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 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 artykule Uwierzytelnianie przy użyciu 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 za pomocą agentUserId. Oto przykładowe żądanie JSON dla Synchronizacji żądań:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Połącz JSON żądania synchronizacji i token w żądaniu HTTP POST z punktem końcowym Google Home Graph. Oto przykład, jak utworzyć żądanie w wierszu poleceń przy użyciu 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 udostępnia punkt końcowy gRPC.

  1. Pobierz definicję usługi buforów protokołów dla interfejsu Home Graph API.
  2. Wykonaj instrukcje podane w dokumentacji dla programistów gRPC, aby wygenerować wycinki dla jednego z obsługiwanych języków.
  3. Wywołaj metodę RequestSync.

Node.js

Klient Node.js interfejsu API Google udostępnia powiązania interfejsu Home Graph API.

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

  1. Zainicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
  2. Wywołaj metodę requestSync metodą RequestSyncDevicesRequest. Zwraca pusty element 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);
    

Reakcje na błędy

Podczas wywoływania żądania synchronizacji możesz zobaczyć jedną z poniższych odpowiedzi dotyczących błędów. Te odpowiedzi mają postać kodów stanu HTTP.

  • 400 Bad Request – serwer nie może przetworzyć żądania wysłanego przez klienta ze względu na nieprawidłową składnię. Typowe przyczyny to zniekształcony kod JSON lub użycie wartości „null” zamiast „" jako wartości ciągu.
  • 403 Forbidden – serwer nie mógł przetworzyć żądania dla agentUserId z powodu błędu podczas odświeżania tokena. Sprawdź, czy punkt końcowy OAuth prawidłowo reaguje na żądania tokenów tokena i sprawdza stan połączenia kont użytkownika.
  • 404 Not Found – żądanego zasobu nie udało się znaleźć, 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łowe żądanie agentUserId. Upewnij się, że agentUserId odpowiada wartości podanej w odpowiedzi SYNC i że obsługujesz intencje DISCONNECT.
  • 429 Too Many Requests – maksymalna liczba równoczesnych żądań synchronizacji dla określonego pola agentUserId została przekroczona. Rozmówca może wysłać tylko jedno żądanie synchronizacji, chyba że flaga async ma wartość Prawda.