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

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

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

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

Начать

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

Включите API Google HomeGraph

  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 для запроса синхронизации:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Объедините 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

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

  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.