1. Подготовка
Разработчики интернета вещей могут создавать облачные интеграции, которые позволяют пользователям управлять устройствами с помощью сенсорного управления в приложении Google Home и голосовых команд в Ассистенте.

Облачные интеграции используют Home Graph, чтобы получать контекстные данные о доме и его устройствах и создавать логическую карту дома. Это позволяет Ассистенту лучше понимать запросы пользователя с учетом его местоположения в доме. Например, в Home Graph может храниться информация о гостиной, в которой есть несколько типов устройств от разных производителей, таких как термостат, лампа, вентилятор и пылесос.

Требования
Что вы создадите
В этой практической работе вы опубликуете облачный сервис, который управляет виртуальной умной стиральной машиной, а затем создадите интеграцию Cloud-to-cloud и подключите ее к Ассистенту.
Что вы узнаете
- Как развернуть облачный сервис умного дома
- Как подключить сервис к Ассистенту
- Как публиковать изменения состояния устройства в Google
Что вам понадобится
- браузер, например Google Chrome;
- Устройство iOS или Android с установленным приложением Google Home.
- Node.js версии 24 или более поздней.
- Платежный аккаунт Google Cloud.
- Тарифный план Blaze (оплата по мере использования) для Firebase.
2. Начало работы
Как включить отслеживание действий
Чтобы использовать Google Ассистента, вы должны предоставить Google доступ к определенным данным о своих действиях. Эти данные необходимы для правильной работы Google Ассистента, однако требование об их передаче не связано с SDK. Чтобы поделиться этими данными, создайте аккаунт Google, если у вас его нет. Вы можете использовать любой аккаунт Google, не обязательно аккаунт разработчика.
Откройте страницу Отслеживание действий для аккаунта Google, который вы хотите использовать с Ассистентом.
Убедитесь, что включены следующие переключатели:
- История приложений и веб-поиска. Также установите флажок Также сохранять историю Chrome и данные о действиях на сайтах, в приложениях и на устройствах, которые используют сервисы Google.
- Информация об устройстве
- История голосового управления
Создайте проект интеграции Cloud-to-cloud
- Перейдите в Developer Console.
- Нажмите Создать проект, введите название проекта и нажмите Создать проект.

Выберите интеграцию Cloud-to-cloud
На главной странице проекта в Developer Console выберите Add cloud-to-cloud integration (Добавить интеграцию между облачными сервисами) в разделе Cloud-to-cloud (Облачные сервисы).

Установите интерфейс командной строки Firebase
Интерфейс командной строки Firebase (CLI) позволяет запускать веб-приложения локально и развертывать их в Firebase Hosting.
Чтобы установить CLI, выполните в терминале следующую команду npm:
npm install -g firebase-tools
Чтобы проверить, правильно ли установлен интерфейс командной строки, выполните следующую команду:
firebase --version
Авторизуйте интерфейс командной строки Firebase в аккаунте Google, выполнив следующую команду:
firebase login
3. Запустите шаблон приложения
Теперь, когда вы настроили среду разработки, вы можете развернуть базовый проект, чтобы убедиться, что все настроено правильно.
Получить исходный код
Чтобы скачать пример для этой практической работы на компьютер для разработки, нажмите на ссылку ниже.
Вы также можете клонировать репозиторий GitHub из командной строки:
git clone https://github.com/google-home/smarthome-washer.git
О проекте
Начальный проект содержит следующие подкаталоги:
public:Интерфейс для управления умной стиральной машиной и отслеживания ее состояния.functions:Полностью реализованный облачный сервис, который управляет умной стиральной машиной с помощью Cloud Functions for Firebase и Firebase Realtime Database.
Как добавить Firebase в проект Google Home Developer Console
Способ 1. Через консоль Firebase
- Перейдите в Firebase.
- Нажмите Создать проект Firebase.

- На экране Создание проекта нажмите Добавить Firebase в проект Google Cloud.

- На экране Начало работы выберите облачный проект Google Cloud, который вы только что создали в Google Home Developer Console, и нажмите Продолжить.

Способ 2. С помощью интерфейса командной строки Firebase
firebase projects:addfirebase
Выберите проект Google Home Developer Console, который вы только что создали, чтобы добавить Firebase.
После добавления Firebase в проект Google Home Developer Console он появится в консоли Firebase. Идентификатор проекта Firebase будет совпадать с идентификатором проекта Google Home Developer Console.

Установить связь с Firebase
Перейдите в каталог washer-start и настройте интерфейс командной строки Firebase для проекта интеграции:
cd washer-start firebase use <project-id>
Как настроить проект Firebase
Инициализируйте проект Firebase.
firebase init
Выберите функции CLI, Realtime Database и Functions.
? Which Firebase features do you want to set up for this directory? Press Space to select features, then Enter to confirm your choices. (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed) >( ) Data Connect: Set up a Firebase Data Connect service ( ) Firestore: Configure security rules and indexes files for Firestore ( ) Genkit: Setup a new Genkit project with Firebase (*) Functions: Configure a Cloud Functions directory and its files ( ) App Hosting: Configure an apphosting.yaml file for App Hosting ( ) Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys ( ) Storage: Configure a security rules file for Cloud Storage ( ) Emulators: Set up local emulators for Firebase products ( ) Remote Config: Configure a template file for Remote Config ( ) Extensions: Set up an empty Extensions manifest (*) Realtime Database: Configure a security rules file for Realtime Database and (optionally) provision default instance ( ) Data Connect: Set up a Firebase Data Connect service ( ) Firestore: Configure security rules and indexes files for Firestore
Это инициализирует необходимые API и функции для вашего проекта.
При появлении запроса инициализируйте Realtime Database. Вы можете использовать местоположение по умолчанию для экземпляра базы данных.
? It seems like you haven't initialized Realtime Database in your project yet. Do you want to set it up? Yes ? Please choose the location for your default Realtime Database instance: us-central1
Поскольку вы используете код начального проекта, выберите файл по умолчанию для правил безопасности и убедитесь, что вы не перезаписываете существующий файл правил базы данных.
? File database.rules.json already exists. Do you want to overwrite it with the Realtime Database Security Rules for <project-ID>-default-rtdb from the Firebase Console? No
Если вы повторно инициализируете проект, выберите Перезаписать, когда появится запрос на инициализацию или перезапись базы кода.
? Would you like to initialize a new codebase, or overwrite an existing one? Overwrite
При настройке функций используйте файлы по умолчанию и не перезаписывайте существующие файлы index.js и package.json в примере проекта.
? What language would you like to use to write Cloud Functions? JavaScript ? Do you want to use ESLint to catch probable bugs and enforce style? No ? File functions/package.json already exists. Overwrite? No ? File functions/index.js already exists. Overwrite? No
Если вы повторно инициализируете проект, выберите No (Нет), когда появится запрос на инициализацию или перезапись functions/.gitignore.
? File functions/.gitignore already exists. Overwrite? No
? Do you want to install dependencies with npm now? Yes
Если ESLint был включен случайно, его можно отключить двумя способами:
- В графическом интерфейсе пользователя перейдите в папку
../functionsв проекте, выберите скрытый файл.eslintrc.jsи удалите его. Не путайте его с похожим по названию.eslintrc.json. - В командной строке:
cd functions rm .eslintrc.js
Развертывание в Firebase
Теперь, когда вы установили зависимости и настроили проект, вы можете запустить приложение в первый раз.
firebase deploy
В консоли вы увидите следующее:
... ✔ Deploy complete! Project Console: https://console.firebase.google.com/project/<project-id>/overview Hosting URL: https://<project-id>.web.app
Эта команда развертывает веб-приложение и несколько функций Cloud Functions for Firebase.
Откройте URL хостинга в браузере (https://<project-id>.web.app), чтобы посмотреть веб-приложение. Вы увидите следующий интерфейс:

Этот веб-интерфейс представляет собой стороннюю платформу для просмотра или изменения состояний устройств. Чтобы начать заполнение базы данных информацией об устройствах, нажмите ОБНОВИТЬ. На странице ничего не изменится, но текущее состояние стиральной машины будет сохранено в базе данных.
Теперь нужно подключить развернутый облачный сервис к Google Ассистенту с помощью Google Home Developer Console.
Настройте проект в Developer Console
На вкладке Develop (Разработка) добавьте Display Name (Отображаемое название) для взаимодействия. Оно будет показываться в приложении Google Home.

В разделе Брендинг приложения загрузите файл png для значка приложения размером 144 x 144 пикселя и назовите его .

Чтобы включить связывание аккаунтов, используйте следующие настройки:
Идентификатор клиента |
|
Секретный код клиента |
|
URL авторизации |
|
URL токена |
|

В поле Cloud fulfillment URL (URL выполнения в облаке) введите URL функции Cloud Functions, которая обеспечивает выполнение намерений умного дома.
https://us-central1-<project-id>.cloudfunctions.net/smarthome

Нажмите Сохранить, чтобы сохранить конфигурацию проекта, а затем нажмите Далее: тестирование, чтобы включить тестирование в проекте.

Теперь вы можете начать реализацию вебхуков, необходимых для подключения состояния устройства к Ассистенту.
4. Создать шайбу
Теперь, когда вы настроили интеграцию, вы можете добавлять устройства и отправлять данные. Ваш облачный сервис должен обрабатывать следующие намерения:
- Намерение
SYNCвозникает, когда Ассистент хочет узнать, какие устройства подключены у пользователя. Этот токен отправляется в ваш сервис, когда пользователь связывает аккаунты. Вы должны ответить полезной нагрузкой JSON со всеми устройствами пользователя и их возможностями. - Намерение
QUERYвозникает, когда Ассистенту нужно узнать текущее состояние или статус устройства. Вы должны ответить полезной нагрузкой JSON с состоянием каждого запрошенного устройства. - Намерение
EXECUTEвозникает, когда Ассистент хочет управлять устройством от имени пользователя. Вы должны ответить полезной нагрузкой JSON со статусом выполнения для каждого запрошенного устройства. - Намерение
DISCONNECTвозникает, когда пользователь отменяет связь своего аккаунта с Ассистентом. Вам следует прекратить отправку событий для устройств этого пользователя в Ассистент.
В следующих разделах вы обновите функции, которые вы ранее развернули для обработки этих намерений.
Обновить ответ SYNC
Откройте файл functions/index.js, в котором содержится код для ответа на запросы от Ассистента.
Вам нужно будет обработать намерение SYNC, возвратив метаданные и возможности устройства. Обновите JSON в массиве onSync, чтобы включить информацию об устройстве и рекомендуемые характеристики для стиральной машины.
index.js
app.onSync((body) => {
return {
requestId: body.requestId,
payload: {
agentUserId: USER_ID,
devices: [{
id: 'washer',
type: 'action.devices.types.WASHER',
traits: [
'action.devices.traits.OnOff',
'action.devices.traits.StartStop',
'action.devices.traits.RunCycle',
],
name: {
defaultNames: ['My Washer'],
name: 'Washer',
nicknames: ['Washer'],
},
deviceInfo: {
manufacturer: 'Acme Co',
model: 'acme-washer',
hwVersion: '1.0',
swVersion: '1.0.1',
},
willReportState: true,
attributes: {
pausable: true,
},
}],
},
};
});
Развертывание в Firebase
Разверните обновленное облачное выполнение с помощью интерфейса командной строки Firebase:
firebase deploy --only functions
Связать с Google Ассистентом
Чтобы протестировать интеграцию Cloud-to-cloud, свяжите проект с аккаунтом Google. Это позволит вам тестировать действия на платформах Google Ассистента и в приложении Google Home, в которых выполнен вход в тот же аккаунт.
- Откройте настройки Google Ассистента на телефоне. Убедитесь, что вы вошли в тот же аккаунт, что и в консоли.
- Выберите Google Ассистент > Настройки > Управление домом (в разделе "Ассистент").
- Нажмите на значок поиска в правом верхнем углу.
- Чтобы найти тестовое приложение, введите в строку поиска префикс [test].
- Выберите его. Затем Google Ассистент выполнит аутентификацию в вашем сервисе и отправит запрос
SYNC, чтобы получить список устройств пользователя.
Откройте приложение Google Home и убедитесь, что стиральная машина видна в списке устройств.

5. Обработка команд и запросов
Теперь, когда ваш облачный сервис правильно сообщает Google о стиральной машине, вам нужно добавить возможность запрашивать состояние устройства и отправлять команды.
Обработка намерения QUERY
Намерение QUERY включает набор устройств. Для каждого устройства нужно указать его текущее состояние.
В файле functions/index.js измените обработчик QUERY, чтобы он обрабатывал список целевых устройств, содержащийся в запросе намерения.
index.js
app.onQuery(async (body) => {
const {requestId} = body;
const payload = {
devices: {},
};
const queryPromises = [];
const intent = body.inputs[0];
for (const device of intent.payload.devices) {
const deviceId = device.id;
queryPromises.push(queryDevice(deviceId)
.then((data) => {
// Add response to device payload
payload.devices[deviceId] = data;
}
));
}
// Wait for all promises to resolve
await Promise.all(queryPromises);
return {
requestId: requestId,
payload: payload,
};
});
Для каждого устройства, содержащегося в запросе, верните текущее состояние, хранящееся в Realtime Database. Обновите функции queryFirebase и queryDevice, чтобы они возвращали данные о состоянии стиральной машины.
index.js
const queryFirebase = async (deviceId) => {
const snapshot = await getFirebaseRef().child(deviceId).once('value');
const snapshotVal = snapshot.val();
return {
on: snapshotVal.OnOff.on,
isPaused: snapshotVal.StartStop.isPaused,
isRunning: snapshotVal.StartStop.isRunning,
};
};
const queryDevice = async (deviceId) => {
const data = await queryFirebase(deviceId);
return {
on: data.on,
isPaused: data.isPaused,
isRunning: data.isRunning,
currentRunCycle: [{
currentCycle: 'rinse',
nextCycle: 'spin',
lang: 'en',
}],
currentTotalRemainingTime: 1212,
currentCycleRemainingTime: 301,
};
};
Обработка намерения EXECUTE
Намерение EXECUTE обрабатывает команды на обновление состояния устройства. В ответе возвращается статус каждой команды, например SUCCESS, ERROR или PENDING, и новое состояние устройства.
В файле functions/index.js измените обработчик EXECUTE, чтобы он обрабатывал список функций, которые нужно обновить, и набор целевых устройств для каждой команды:
index.js
app.onExecute(async (body) => {
const {requestId} = body;
// Execution results are grouped by status
const result = {
ids: [],
status: 'SUCCESS',
states: {
online: true,
},
};
const executePromises = [];
const intent = body.inputs[0];
for (const command of intent.payload.commands) {
for (const device of command.devices) {
for (const execution of command.execution) {
executePromises.push(
updateDevice(execution, device.id)
.then((data) => {
result.ids.push(device.id);
Object.assign(result.states, data);
})
.catch(() => functions.logger.error('EXECUTE', device.id)));
}
}
}
await Promise.all(executePromises);
return {
requestId: requestId,
payload: {
commands: [result],
},
};
});
Для каждой команды и целевого устройства обновите значения в Realtime Database, которые соответствуют запрашиваемому типажу. Измените функцию updateDevice, чтобы обновить соответствующую ссылку Firebase и вернуть обновленное состояние устройства.
index.js
const updateDevice = async (execution, deviceId) => {
const {params, command} = execution;
let state; let ref;
switch (command) {
case 'action.devices.commands.OnOff':
state = {on: params.on};
ref = getFirebaseRef().child(deviceId).child('OnOff');
break;
case 'action.devices.commands.StartStop':
state = params.start
? {isRunning: true, isPaused: false}
: {isRunning: false, isPaused: false};
ref = getFirebaseRef().child(deviceId).child('StartStop');
break;
case 'action.devices.commands.PauseUnpause':
const data = await queryDevice(deviceId);
state = (data.isPaused === false && data.isRunning === false)
? {isRunning: false, isPaused: false}
: {isRunning: !params.pause, isPaused: params.pause};
ref = getFirebaseRef().child(deviceId).child('StartStop');
break;
}
return ref.update(state)
.then(() => state);
};
6. Протестируйте интеграцию
После реализации всех трех намерений вы можете проверить, управляет ли ваша интеграция стиральной машиной.
Развертывание в Firebase
Разверните обновленное облачное выполнение с помощью интерфейса командной строки Firebase:
firebase deploy --only functions
Протестируйте стиральную машину
Теперь вы можете увидеть, как меняется значение, когда вы пробуете любую из следующих голосовых команд на телефоне:
"Окей, Google, включи стиральную машину".
"Окей, Google, приостанови стирку".
"Окей, Google, останови стиральную машину".
Вы также можете узнать текущее состояние стиральной машины, задав вопрос.
"Окей, Google, стиральная машина включена?"
"Окей, Google, стиральная машина работает?"
"Окей, Google, какой цикл стирки сейчас запущен?"
Эти запросы и команды можно посмотреть в журналах, которые появляются под функцией в разделе Функции консоли Firebase. Подробнее о журналах Firebase…
Эти запросы и команды также можно найти в консоли Google Cloud, перейдя в Logging > Logs Explorer. Подробнее о журналах Google Cloud рассказывается в статье Как получить доступ к журналам событий с помощью Cloud Logging.
7. Как сообщить Google об изменениях
Вы полностью интегрировали свой облачный сервис с интентами умного дома, что позволяет пользователям управлять своими устройствами и запрашивать их текущее состояние. Однако в реализации по-прежнему отсутствует способ, позволяющий вашему сервису упреждающе отправлять информацию о событиях, например об изменении присутствия или состояния устройства, Ассистенту.
С помощью Request Sync вы можете запустить новый запрос на синхронизацию, когда пользователи добавляют или удаляют устройства или когда меняются возможности их устройств. С помощью Report State облачный сервис может отправлять в Home Graph информацию о состоянии устройства, когда пользователь меняет его физически (например, включает свет) или через другой сервис.
В этом разделе вы добавите код для вызова этих методов из внешнего веб-приложения.
Как включить HomeGraph API
HomeGraph API позволяет хранить и запрашивать информацию об устройствах и их статусах в Home Graph пользователя. Чтобы использовать этот API, сначала откройте консоль Google Cloud и включите HomeGraph API.
В консоли Google Cloud выберите проект, соответствующий вашей интеграции <project-id>.. Затем на экране библиотеки API для HomeGraph API нажмите Включить.

Включить Report State
Записи в Realtime Database запускают функцию reportstate в проекте tarter. Обновите функцию reportstate в functions/index.js, чтобы собирать данные, записанные в базу данных, и отправлять их в Home Graph с помощью Report State.
index.js
exports.reportstate = functions.database.ref('{deviceId}').onWrite(
async (change, context) => {
functions.logger.info('Firebase write event triggered Report State');
const snapshot = change.after.val();
const requestBody = {
requestId: 'ff36a3cc', /* Any unique ID */
agentUserId: USER_ID,
payload: {
devices: {
states: {
/* Report the current state of our washer */
[context.params.deviceId]: {
on: snapshot.OnOff.on,
isPaused: snapshot.StartStop.isPaused,
isRunning: snapshot.StartStop.isRunning,
},
},
},
},
};
const res = await homegraph.devices.reportStateAndNotification({
requestBody,
});
functions.logger.info('Report state response:', res.status, res.data);
});
Как включить синхронизацию запросов
Обновление значка в веб-интерфейсе запускает функцию requestsync в начальном проекте. Реализуйте функцию requestsync в functions/index.js, чтобы вызывать HomeGraph API.
index.js
exports.requestsync = functions.https.onRequest(async (request, response) => {
response.set('Access-Control-Allow-Origin', '*');
functions.logger.info(`Request SYNC for user ${USER_ID}`);
try {
const res = await homegraph.devices.requestSync({
requestBody: {
agentUserId: USER_ID,
},
});
functions.logger.info('Request sync response:', res.status, res.data);
response.json(res.data);
} catch (err) {
functions.logger.error(err);
response.status(500).send(`Error requesting sync: ${err}`);
}
});
Развертывание в Firebase
Разверните обновленный код с помощью интерфейса командной строки Firebase:
firebase deploy --only functions
Как выполнить проверку
Нажмите кнопку Обновить
в веб-интерфейсе и убедитесь, что в журнале консоли Firebase появился запрос на синхронизацию.
Затем измените атрибуты стиральной машины в веб-интерфейсе и нажмите Update (Обновить). Убедитесь, что в журналах консоли Firebase есть запись о том, что изменение статуса было передано в Google.
8. Поздравляю!

Поздравляем! Вы успешно интегрировали Ассистента с облачным сервисом устройства, используя интеграцию Cloud-to-cloud.
Подробнее…
Вот несколько идей, которые вы можете реализовать, чтобы углубиться в тему:
- Добавьте на устройство режимы и переключатели.
- Добавьте больше поддерживаемых функций на устройство.
- Узнайте больше о локальном выполнении для умного дома.
- Дополнительную информацию можно найти в примере на GitHub.
Вы также можете узнать больше о тестировании и отправке интеграции на проверку, включая процесс сертификации для публикации интеграции для пользователей.