УрФУ. Доклад REST API (Telegram bot, сайт УрФУ)

#КР № 1 (ФО-350005, Васильев А., Чабин А.)

ФО-350005
Васильев А.М.
Чабин А.С.

Презентация:
bit.ly/urfu_botapi

Доклад по созданию бота в Telegram на базе API УрФУ.
--------------------------------------

1. Введение. Rest API
Application Programming Interface — набор функций, предоставляемых приложением для их использования в сторонних.

REST (Representational State Transfer — 
«передача состояния представления») — это архитектурный стиль взаимодействия компонентов распределённого приложения в сети.
Взаимодействие происходит по HTTP.

--------------------------------------

2. Мессенджер Telegram и bot API

Telegram — бесплатный кроссплатформенный мессенджер, работающий с августа 2013 года. Используются проприетарная серверная часть c закрытым кодом, работающая на мощностях нескольких компаний США и Германии, финансируемых Павлом Дуровым в объёме порядка 12 млн долларов США ежегодно, и несколько клиентов с открытым исходным кодом, в том числе под лицензией GNU GPL.

Количество активных пользователей сервиса составляет более 100 млн человек. Количество ежедневно пересылаемых сообщений достигло 15 миллиардов. В августе 2017 года в своем Telegram-канале Павел Дуров сообщил, что количество ежедневных новых пользователей составляет более 600 тысяч.

Проект имеет множество дополнительных разработок. Например, различными СМИ в публичных каналах применяется сервис анонимных публикаций http://telegra.ph/.

2.1. Основные возможности:
– Групповые чаты (приватные, публичные)
– Каналы
– Голосовые и видеосообщения
– Загрузка файлов до 1.5 Гб
– Редактор фото, проигрыватель музыки
– Кастомизация клиентов etc.

2.2. Поддержка платформ

Десктопные:
- Windows
- Linux
- OS X

Мобильные:
- Android (нет оф. поддержки 2 версии)
- iOS 
- Windows Phone
- Firefox OS
Так же существует веб-версия web.telegram.org и Chrome Extension.


2.3. Чат-боты

Бот в Telegram - это пользователь с именем, описанием и аватаркой, имя которого оканчивается на "bot". Для доступа достаточно добавить его в адресную книгу и нажать кнопку "Start".

Основной функционал:
– Интеграция с другими сервисами 
– Рассылка уведомлений
– Расширение функционала в Telegram
– HTML 5 игры
– Оплата покупок

К примеру, чат-бот @vkm_bot интегрирован с соц. сетью vk.com. Выполняет поиск аудиозаписей и отправляет их пользователю. Для использования необходимо дать доступ к своему акканнту на vk.com с помощью oAuth-авторизации.

Бот для создания опросов @vote дополняет функционал Telegram-клиента возможностью. Подобный пример - бот @bold, который добавляет возможность форматирования отправления сообщений в чат. 

Многие СМИ, например Meduza использует бота @meduzaprobot для уведомления о новых публикациях на сайте.


2.4. Telegram Bot API

   Для создания бота:
   1.	Зарегистрировать бота у системного бота @Botfather

   2.	Настроить бота в @Botfather
   (указать имя, описание, аватар, список команд, приватность)
   
   Редактирование:
   /setname - указать имя
   /setdescription - указать описание
   /setabouttext  - указать приветственный текст (при добавлении)
   /setuserpic - установить аватар
   /setcommands - указать список команд (в поле отправки сообщения появится символ '/' с их перечислением)
   
   Настройки:
   /token - получить ключ
   /revoke - сменить ключ
   /setjoingroups - разрешение добавлять бота в групповые чаты
   /setprivacy - разрешение доступа к сообщениях в групповых чатах
   
   3.	Получить Access-token - секретный ключ для доступа к API Telegram


2.5. Пример обращения к API

Каждый раз при обращении к API указывается Token бота с указанием метода и параметров в виде Query string:
https://api.telegram.org/bot<token>/methodName?param=value&param2=value

1.	Методы не привязаны к регистру
2.	Запросы должны быть в UTF-8
3.	Поддержка GET и POST запросов
4.	Ответ сервера на application/json


2.6. Пример реализации на PHP
Для отправки HTTP-запросов используется встроенная библиотека сUrl
(в приложении Gist)

2.7. Node.js с прослушиванием сообщений
(в приложении Gist)

Для использования методов Telegram и прослушивания сообщений применяется библиотека node-telegram-bot-api:
https://www.npmjs.com/package/node-telegram-bot-api

--------------------------------------

3. API УрФУ

API УрФУ было обнаружено в режиме разработчика Google Chrome на странице https://urfu.ru/ru/students/study/schedule/.
При вводе в поле "Поиск по номеру группы:" в вкладке Network отображаются GET-запросы по адресу:
https://urfu.ru/api/schedule/groups/suggest/?query=ФО-35000

API расположено по адресу https://urfu.ru/api/.

Был обнаружен метод teachers (urfu.ru/api/teachers/info/)
Выводится общий список преподавателей с указанием контактных данных.
Пример:
{
  "address": "",
  "phone": "+7 (343) 3754714",
  "email": "o.v.limanovskaia@urfu.ru",
  "fio": "Лимановская Оксана Викторовна",
  "disciplines": [
    "Основы программирования",
    "Mоделирование информационных процессов"
  ],
  "position": "Доцент",
  "photo": "/fileadmin/user_upload/urfu.ru/person/f967d25bfdf00ea7b8dfead18fe498f4.png",
  "degree": "кандидат химических наук",
  "username": "O.V.Limanovskaia",
  "url": "/ru/about/personal-pages/Personal/person/o.v.limanovskaia/",
  "room": "Т-512, ул. Софьи Ковалевской, 5"
}

Для разработки бота с выводом расписания необходимые следующие методы в schedule:
   - urfu.ru/api/schedule/groups/ - вывод всех групп
   - urfu.ru/api/schedule/groups/suggest/?query=ФО-35000 - вывод совпадений по названию групп
   - urfu.ru/api/schedule/groups/lessons/975873/20171021 - вывод расписания группы (по идентификатору) за 2 недели с указанной даты

--------------------------------------

4. Прототип с получением списка групп 
(в приложении Gist)

Для использования методов Telegram и прослушивания сообщений применяется библиотека pyTelegramBotAPI:
https://github.com/eternnoir/pyTelegramBotAPI

Обрабатываются все сообщения отправленные к боту, и происходит поиск совпадений в JSON-ответе API УрФУ.

01. Пример на PHP.php

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8" /> 
	<title>Отправка сообщения Telegram</title>
</head>
<body>

<form method="POST">
  Текст сообщения:<br>
	<textarea rows="4" cols="30" name="message"></textarea>
	<br><br>
  <input type="submit" value="Отправить">
</form>

<pre>
<?php
if( isset($_POST['message']) )
{
	$host = "https://api.telegram.org/";
	$token = "477565976:AAEaku5zRweCWciyQ9cMeoVBRwWEQgsWhtM";
	$method = "sendMessage";
	$chat_id = 207858057;
	$text = $_POST['message'];

	$API_request = "https://api.telegram.org/bot$token/$method?chat_id=$chat_id&text=$text";

	$curl = curl_init();
	curl_setopt($curl, CURLOPT_URL, $API_request);
	echo "\n\rОтправленный запрос:\n\r" . $API_request . "\n\r";
	echo "\n\rОтвет сервера:\n\r";
	$res = curl_exec($curl);
	curl_close($curl);
}
?>
</pre>

</body>
</html>

02. Пример на Node.js

var TelegramBot = require('node-telegram-bot-api');
var token = '477565976:AAEaku5zRweCWciyQ9cMeoVBRwWEQgsWhtM';
// Запуск прослушиваний
var bot = new TelegramBot(token, {polling: true}); 

// Команда “/echo текст” возвращает “текст”
bot.onText(/\/echo (.+)/, function (msg, match) {
  var userId = msg.from.id;
  var text = match[1];
  bot.sendMessage(userId, text);
});

// Отправка изображения на все сообщения от пользователя
bot.on('message', function (msg) {
  var userId = msg.from.id;
  var photo = 'cat.jpg';
  bot.sendPhoto(userId, photo, {caption: 'Вот тебе милый кот'});
  console.log(msg.from.first_name + ": " + msg.text);
});

03. Пример на Python.py

import telebot
import requests
import json
from urllib.parse import quote
bot = telebot.TeleBot('308767178:AAErE2ArbK5yWXxYNB5RPa3eZ2uM7YWuvG4')

# Обработка всех текстовых сообщений от пользователей
@bot.message_handler(content_types=['text'])
def handle(msg):
   user_id = msg.from_user.id
   request = 'https://urfu.ru/api/schedule/groups/suggest/?query=' + quote(''.join(msg.text))
   response = requests.get(request);
   suggestions = response.json()['suggestions']
   if suggestions:
       text = 'Найдены группы:\n'
       for group in suggestions:
           text += group['value'] + '\n'
       bot.send_message(user_id, text)
   else:
       bot.send_message(user_id, 'Группы не найдены. Повторите запрос')

# Запуск прослушивания сообщений
while True:
   bot.polling(none_stop = True, interval = 0, timeout = 20)