Добро пожаловать в Центр разработчиков Google Home, новое место, где можно научиться разрабатывать действия для умного дома. Примечание. Вы продолжите создавать действия в консоли действий.

Запросить синхронизацию

Request Sync инициирует запрос SYNC на ваше выполнение для любого пользователя Google с устройствами, с которыми связан указанный agentUserId (который вы отправили в исходном запросе SYNC). Это позволяет обновлять устройства пользователей без отключения и повторного связывания их учетной записи. Все пользователи, связанные с этим идентификатором, получат запрос SYNC .

Вы должны инициировать запрос SYNC :

  • Если пользователь добавляет новое устройство.
  • Если пользователь удаляет существующее устройство.
  • Если пользователь переименовывает существующее устройство.
  • Если вы реализуете новый тип устройства, характеристику или добавляете новую функцию устройства.

Начать

Чтобы реализовать запрос синхронизации, выполните следующие действия:

Включить Google HomeGraph API

  1. В Google Cloud Console перейдите на страницу HomeGraph API .

    Перейдите на страницу API HomeGraph.
  2. Выберите проект, который соответствует вашему идентификатору проекта smart home .
  3. Щелкните ВКЛЮЧИТЬ .

Создайте ключ служебной учетной записи

Следуйте этим инструкциям, чтобы сгенерировать ключ сервисного аккаунта из Google Cloud Console :

Примечание . При выполнении этих шагов убедитесь, что вы используете правильный проект GCP. Это проект, который соответствует вашему идентификатору проекта smart home .
  1. В Google Cloud Console перейдите на страницу создания ключа сервисного аккаунта .

    Перейдите на страницу создания ключа сервисной учетной записи.
  2. В списке Учетная запись службы выберите Новая учетная запись службы .
  3. В поле Имя учетной записи службы введите имя.
  4. В поле Идентификатор учетной записи службы введите идентификатор.
  5. В списке Роли выберите Учетные записи служб > Создатель токена учетной записи службы .

  6. Для Типа ключа выберите вариант JSON .

  7. Щелкните Создать . Файл JSON, содержащий ваш ключ, загружаемый на ваш компьютер.

Вызов API

HTTP

API Home Graph предоставляет конечную точку HTTP.

  1. Используйте загруженный файл JSON учетной записи службы для создания веб-маркера JSON (JWT). Дополнительные сведения см. в разделе Аутентификация с использованием учетной записи службы .
  2. Получите токен доступа OAuth 2.0 с областью действия https://www.googleapis.com/auth/homegraph с помощью oauth2l :
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Создайте запрос JSON с agentUserId . Вот пример запроса JSON для Request Sync:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Объедините Request Sync JSON и токен в запросе HTTP POST с конечной точкой Google Home Graph. Вот пример того, как сделать запрос в командной строке с помощью 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

API Home Graph предоставляет конечную точку gRPC.

  1. Получите определение службы буферов протоколов для API Home Graph.
  2. Следуйте документации разработчика gRPC, чтобы создать клиентские заглушки для одного из поддерживаемых языков .
  3. Вызовите метод RequestSync .

Node.js

Клиент Node.js API Google предоставляет привязки для API Home Graph.

  1. Инициализируйте службу google.homegraph , используя учетные данные приложения по умолчанию .
  2. Вызовите метод requestSync с RequestSyncDevicesRequest . Он возвращает Promise с пустым 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
  }
});
    

Джава

Клиентская библиотека HomeGraph API для Java предоставляет привязки для Home Graph API.

  1. Инициализируйте HomeGraphApiService , используя учетные данные приложения по умолчанию .
  2. Вызовите метод requestSync с RequestSyncDevicesRequest . Он возвращает пустой 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);
    

Ответы на ошибки

Вы можете получить один из следующих ответов об ошибке при вызове Request Sync. Эти ответы приходят в виде кодов состояния HTTP.

  • 400 Bad Request — сервер не смог обработать запрос, отправленный клиентом, из-за неправильного синтаксиса . Общие причины включают искаженный формат JSON или использование null вместо "" для строкового значения.
  • 403 Forbidden — серверу не удалось обработать запрос для данного agentUserId из-за ошибки при обновлении токена. Убедитесь, что ваша конечная точка OAuth правильно отвечает на запросы токена обновления, и проверьте статус привязки учетной записи пользователя.
  • 404 Not Found — запрошенный ресурс не может быть найден, но может быть доступен в будущем. Как правило, это означает, что учетная запись пользователя не связана с Google или мы получили недопустимый agentUserId . Убедитесь, что agentUserId соответствует значению, указанному в вашем ответе SYNC , и вы правильно обрабатываете намерения DISCONNECT .
  • 429 Too Many Requests — превышено максимальное количество одновременных запросов на синхронизацию для данного agentUserId . Вызывающий объект может выдать только один одновременный запрос на синхронизацию, если для флага async не установлено значение true.