Перейти к содержанию

Первый навык

Добро пожаловать, путник!
Здесь будет представлено, как можно взаимодействовать с API Алисы и отвечать на его запросы.

База

Перед тем, как начать разработку навыка для Алисы, важно знать официальную документацию и принцип работы навыков.

Взаимодействие с Алисой происходит через webhook'и (или облачные функции) - Яндекс отправляет запрос с новым событие навыка, он что-то думает и возвращает ответ. Навыки не опрашивают Алису на предмет новых сообщений, действий и так далее.
Здесь нет pooling'а, поэтому нельзя узнать, принял ли Яндекс ваш ответ без ошибок (но не всегда).

Важно

Именно из-за вебхуков все хэндлеры (и мидлвари) обязаны что-то вернуть, иначе Алиса завершит сессию пользователя.

Типизация

На момент создания библиотеки разработчики постарались перевести все json-объекты из документации в модели pydantic'а, которые и являются подсказками типов.
В моделях не учтены все возможные ограничения Алисы (например, размер всего ответа), поэтому обязательно уточняйте их в официальной документации и тестируйте свои навыки.

Первые шаги

Начнём с написания простого эхо-навыка. Для начала работы следует ознакомиться с основными классами фреймворка: Skill, Dispatcher, и OneSkillAiohttpRequestHandler.

1
2
3
4
5
6
7
from aiohttp import web
from aliceio import Dispatcher, Skill
from aliceio.types import AliceResponse, Message, Response  # О типах чуть позже
from aliceio.webhook.aiohttp_server import OneSkillAiohttpRequestHandler, setup_application

dp = Dispatcher()
skill = Skill(skill_id="...")

При иницализации навыка нужно указать его айди (обязательно) и OAuth Token (опицонально).
Первый позволяет игнорировать запросы, адресованные не этому навыку, а второй даёт возможность взаимодействовать с файлами ваших навыков.

Теперь в диспетчер можно добавить нужный обработчик:

1
2
3
4
5
6
7
@dp.message()
async def message_handler(message: Message) -> AliceResponse:
    if message.session.new:
        text = "Привет!"
    else:
        text = message.original_text
    return AliceResponse(response=Response(text=text))

Разберём этот фрагмент построчно:

@dp.message() - это декоратор, который регистрирует функцию-обработчик, которая сработает, если сообщение будет отвечать заданным фильтрам. Здесь их нет, поэтому функция будет срабатывать на каждое сообщение.

async def message_handler(message: Message) -> AliceResponse: - сигнатура функции-обработчика, в которой первым аргументом всегда будет текущее событие. Эта функция возвращает AliceResponse, но фреймворк поддерживает и другие варианты.

if message.session.new: - проверяем, первое ли это сообщение в текущей сессии (т.е. пользователь только открыл навык). Если это так, то вместо эха будет приветствие.

return AliceResponse(response=Response(text=text)) - возвращаем полный объект, который ждёт Алиса. Вместо него можно вернуть просто Response или str, которая станет текстом.

Запуск

Теперь надо как-то запустить эту шайтан-машину, чтобы она принимала запросы от Алисы.
Для этого напишем простую точку входа, которая будет чуть модифицирована в дальнейшем:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
def main() -> None:
    app = web.Application()
    requests_handler = OneSkillAiohttpRequestHandler(
        dispatcher=dp,
        skill=skill,
    )

    # Навык принимает запросы по пути http://127.0.01:80/alice
    WEB_SERVER_HOST = "127.0.0.1"
    WEB_SERVER_PORT = 80
    WEBHOOK_PATH = "/alice"

    requests_handler.register(app, path=WEBHOOK_PATH)
    setup_application(app, dp, skill=skill)
    web.run_app(app, host=WEB_SERVER_HOST, port=WEB_SERVER_PORT)

if __name__ == "__main__":
    main()

Примеры

Полный код из этой главы:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
from aiohttp import web

from aliceio import Dispatcher, Skill
from aliceio.types import AliceResponse, Message, Response
from aliceio.webhook.aiohttp_server import OneSkillAiohttpRequestHandler, setup_application


dp = Dispatcher()
skill = Skill(skill_id="...", oauth_token="...")


@dp.message()
async def message_handler(message: Message) -> AliceResponse:
    if message.session.new:
        text = "Привет!"
    else:
        text = message.original_text
    return AliceResponse(response=Response(text=text))


def main() -> None:
    app = web.Application()
    requests_handler = OneSkillAiohttpRequestHandler(
        dispatcher=dp,
        skill=skill,
    )

    WEB_SERVER_HOST = "127.0.0.1"
    WEB_SERVER_PORT = 80
    WEBHOOK_PATH = "/alice"

    requests_handler.register(app, path=WEBHOOK_PATH)
    setup_application(app, dp, skill=skill)
    web.run_app(app, host=WEB_SERVER_HOST, port=WEB_SERVER_PORT)


if __name__ == "__main__":
    main()