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

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

Вам необходимо активировать запрос SYNC:

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

Начать

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

Включите Google HomeGraph API

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

    Перейти на страницу HomeGraph API
  2. Выберите проект, соответствующий идентификатору проекта smart home.
  3. Нажмите Включить.

Как создать ключ сервисного аккаунта

Чтобы создать ключ сервисного аккаунта в Google Cloud Console, выполните следующие действия:

Примечание. Убедитесь, что вы используете правильный проект GCP. Это проект, который соответствует вашему идентификатору проекта smart home.

  1. В Google Cloud Console перейдите на страницу Service accounts (Сервисные аккаунты).

    Откройте страницу Сервисные аккаунты.

    Возможно, вам потребуется выбрать проект, прежде чем вы перейдете на страницу "Сервисные аккаунты".

  2. Нажмите Create service account (Создать сервисный аккаунт).

  3. В поле Service account name (Название сервисного аккаунта) введите название.

  4. В поле Service account ID (Идентификатор сервисного аккаунта) введите идентификатор.

  5. В поле Service account description (Описание сервисного аккаунта) введите описание.

  6. Нажмите кнопку Создать и продолжить.

  7. В раскрывающемся списке Роль выберите Сервисные аккаунты > Создатель токенов идентификации OpenID Connect для сервисных аккаунтов.

  8. Нажмите Продолжить.

  9. Нажмите Готово.

  10. Выберите только что созданный сервисный аккаунт из списка и в меню Действия нажмите Управление ключами.

  11. Нажмите Add key (Добавить ключ) > Create new key (Создать ключ).

  12. В поле Key type (Тип ключа) выберите JSON.

  13. Нажмите Создать. На ваш компьютер будет скачан JSON-файл с ключом.

Подробные инструкции и информацию о создании ключей сервисных аккаунтов можно найти в статье Как создавать и удалять ключи сервисных аккаунтов на сайте справки консоли Google Cloud.

Вызов API

HTTP

Home Graph API предоставляет конечную точку 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
  3. Создайте запрос JSON с помощью agentUserId. Вот пример запроса JSON для Request Sync:
    4. {
  "agentUserId": "user-123"
}
  4. Объедините JSON-код запроса на синхронизацию и токен в HTTP-запросе POST к конечной точке Google Home Graph. Ниже приведен пример тестового запроса в командной строке с помощью 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

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

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

Node.js

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

  1. Инициализируйте сервис google.homegraph, используя Application Default Credentials.
  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
  }
});

Java

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

  1. Инициализируйте HomeGraphApiService с помощью Application Default Credentials.
  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.
Назад
Отключить
Далее
Реализуйте Report State