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ę

Ważna informacja: aby przesłać integrację, musisz zaimplementować Request Sync.

Cloud-to-cloud

Synchronizacja żądań powoduje wysłanie SYNC do Twojego systemu do przetwarzania żądań dla każdego użytkownika Google, którego urządzenia są powiązane z określonym agentUserId (który został wysłany w ramach pierwotnego żądania synchronizacji). Dzięki temu możesz aktualizować urządzenia użytkowników bez odłączania i ponownie łączenia ich kont. Wszyscy użytkownicy powiązani z tym identyfikatorem otrzymają prośbę 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 wdrożysz nowy typ urządzenia, cechę lub funkcję urządzenia.

Rozpocznij

Aby wdrożyć funkcję synchronizacji żądań:

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

Włącz interfejs Google HomeGraph API

W sekcji Google Cloud Console otwórz stronę HomeGraph API.
Otwórz stronę interfejsu HomeGraph API
Wybierz projekt, który odpowiada Twojemu identyfikatorowi projektu smart home.
Kliknij WŁĄCZ.

Tworzenie klucza konta usługi

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

Uwaga: podczas wykonywania tych czynności upewnij się, że używasz prawidłowego projektu Google Cloud Platform. Jest to projekt, który pasuje do identyfikatora projektu smart home.

W panelu Google Cloud Console otwórz stronę Utwórz klucz konta usługi.
Otwórz stronę tworzenia klucza konta usługi
Na liście Konto usługi wybierz Nowe konto usługi.
W polu Nazwa konta usługi wpisz nazwę.
W polu Identyfikator konta usługi wpisz identyfikator.
Na liście Rola wybierz Konta usługi > Twórca tokena konta usługi.
W polu Typ klucza wybierz opcję JSON.
Kliknij Utwórz. Plik JSON z kluczem zostanie pobrany na komputer.

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.
Aby uzyskać token dostępu OAuth 2.0 z zakresem https://www.googleapis.com/auth/homegraph, użyj polecenia oauth2l:

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

Utwórz żądanie JSON za pomocą interfejsu API agentUserId. Oto przykład żądania JSON do synchronizacji żądań:

{
  "agentUserId": "user-123"
}

Połącz dane JSON żądania synchronizacji z tokenem w żądaniu HTTP POST do punktu końcowego Google Home Graph. Oto przykład żądania wysyłanego w wierszu poleceń za pomocą polecenia curl, które możesz wykorzystać do przeprowadzenia testu:

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 protocol buffers dla interfejsu Home Graph API.
Aby wygenerować atrapy klienta w jednym z obsługiwanych języków, postępuj zgodnie z instrukcjami podanymi w dokumentacji dla deweloperów gRPC.
Wywołaj metodę RequestSync.

Node.js

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

Inicjuje usługę google.homegraph za pomocą domyślnych danych logowania aplikacji.
Wywołaj metodę requestSync z parametrem RequestSyncDevicesRequest. Zwraca ona odpowiedź 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 elementy wiążące dla interfejsu Home Graph API.

Inicjuj HomeGraphApiService za pomocą domyślnych danych logowania aplikacji.
Wywołaj metodę requestSync z parametrem 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 na błędy

Podczas wywołania metody RequestSync może pojawić się jeden z tych komunikatów o błędzie. Te odpowiedzi mają postać kodów stanu HTTP.

400 Bad Request – serwer nie może przetworzyć żądania wysłanego przez klienta z powodu błędnej składni. Typowe przyczyny to źle sformatowany plik JSON lub użycie znaku null zamiast znaku „” 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. Upewnij się, że punkt końcowy OAuth odpowiada prawidłowo na żądania odświeżania tokena, i sprawdź stan łączenia konta użytkownika.
404 Not Found – żądanego zasobu nie można było znaleźć, ale może być on dostępny w przyszłości. Zwykle oznacza to, że konto użytkownika nie jest połączone z Google lub otrzymaliśmy nieprawidłową odpowiedź.agentUserId Upewnij się, że wartość agentUserId odpowiada wartości podanej w odpowiedzi SYNC, i sprawdź, czy prawidłowo obsługujesz intencje DISCONNECT.
429 Too Many Requests – w przypadku danego agentUserId przekroczono maksymalną liczbę równoczesnych żądań synchronizacji. Wywołujący może wysłać tylko jedno żądanie synchronizacji równoległej, chyba że flaga async jest ustawiona na wartość true.