Поле цифровой дидактики - Вклад [ru]

Unsplash

2026-03-26T14:41:43Z

CherenkovIR:

{{DigitalTool
|Description=Unsplash — это популярный бесплатный фотосток и онлайн-платформа, предоставляющая доступ к миллионам высококачественных фотографий в высоком разрешении.
|Affordances=Скачивание фото для коммерческого и личного использования без авторских отчислений, интеграцию через API в приложения, использование плагинов, а также загрузку собственных работ для продвижения.
|Field_of_knowledge=Информатика, Медиа
|Область применения=Образование
|Website=https://unsplash.com
|End users=Учащиеся, Преподаватели, Исследователи, Организации, Разработчики
|distant_collab=Да
|Language_Ru_Eng=English
|AI=Да
}}
==== Пример работы с API фотостока ====

Одним примером из работы с API является работа с фотостоками, в котором описан полноценный цикл работы с API и созданием бота в Telegram с интеграцией поиска фотографий с сайта-фотостока.

Посмотреть статью можно ниже по ссылке:

[[Телеграм-бот для поиска фотографий через API-ключ фотостока]]

Unsplash

2026-03-26T14:40:30Z

CherenkovIR:

{{DigitalTool
|Description=Unsplash — это популярный бесплатный фотосток и онлайн-платформа, предоставляющая доступ к миллионам высококачественных фотографий в высоком разрешении.
|Affordances=Скачивание фото для коммерческого и личного использования без авторских отчислений, интеграцию через API в приложения, использование плагинов, а также загрузку собственных работ для продвижения.
|Field_of_knowledge=Информатика, Медиа
|Область применения=Образование
|End users=Учащиеся, Преподаватели, Исследователи, Организации, Разработчики
|distant_collab=Да
|Language_Ru_Eng=English
|AI=Да
}}
==== Пример работы с API фотостока ====

Одним примером из работы с API является работа с фотостоками, в котором описан полноценный цикл работы с API и созданием бота в Telegram с интеграцией поиска фотографий с сайта-фотостока.

Посмотреть статью можно ниже по ссылке:

[[Телеграм-бот для поиска фотографий через API-ключ фотостока]]

Unsplash

2026-03-26T14:39:40Z

CherenkovIR: Новая страница: «{{DigitalTool |Description=Unsplash — это популярный бесплатный фотосток и онлайн-платформа, предоставляющая доступ к миллионам высококачественных фотографий в высоком разрешении. |Affordances=Скачивание фото для коммерческого и личного использования без авторских отчи...»

{{DigitalTool
|Description=Unsplash — это популярный бесплатный фотосток и онлайн-платформа, предоставляющая доступ к миллионам высококачественных фотографий в высоком разрешении.
|Affordances=Скачивание фото для коммерческого и личного использования без авторских отчислений, интеграцию через API в приложения, использование плагинов, а также загрузку собственных работ для продвижения.
|Field_of_knowledge=Информатика
|Область применения=Образование
|End users=Учащиеся, Преподаватели
|Tool is made for=Генерация и использование контента
|distant_collab=Да
|Language_Ru_Eng=English
|AI=Да
}}

==== Пример работы с API фотостока ====

Одним примером из работы с API является работа с фотостоками, в котором описан полноценный цикл работы с API и созданием бота в Telegram с интеграцией поиска фотографий с сайта-фотостока.

Посмотреть статью можно ниже по ссылке:

[[Телеграм-бот для поиска фотографий через API-ключ фотостока]]

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-26T14:36:19Z

CherenkovIR: /* Методические материалы */

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с [[API]] фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз [[Unsplash]] API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса =====

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

После этого действия можем начинать работать и тестировать бота.

Переходим в телеграм, пишем команду /start

[[Файл:Изображение 2026-03-05 233503508.png|400px]]

Как видим, запрос прошел успешно, бот ответил то, что я зашил в код программы.

Попробуем получить случайное фото командой /random:

[[Файл:Изображение 2026-03-05 233610248.png|200px]]

[[Файл:Изображение 2026-03-05 233641178.png|200px]]

Теперь попробуем найти что-то конкретное и посмотреть как это будет выглядеть. Для этого сформируем команду /search. Искать будем собаку с породой самоед:

[[Файл:Изображение 2026-03-05 233810808.png|200px]]

[[Файл:Изображение 2026-03-05 233832396.png|200px]]

Как видим, бот отправил нам 4 варианта фотографий, к каждой из которой добавил ссылку на оригинал.

Притом каждый раз в терминале (консоли) мы можем заметить, как бот поддерживает подключение с Unsplash и логирует отправку сообщений.

[[Файл:Изображение 2026-03-05 234038505.png|700px]]

=== Методические материалы ===

{{#ask: [[API]] OR [[Python]] OR [[UML]] OR [[Telegram]] OR [[Unsplash]] | ?Description }}

----
[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

----
[[Категория:Работа с API]]

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-26T14:36:09Z

CherenkovIR: /* Получение API и создание внутреннего конфигурационного API файла */

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с [[API]] фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз [[Unsplash]] API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса =====

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

После этого действия можем начинать работать и тестировать бота.

Переходим в телеграм, пишем команду /start

[[Файл:Изображение 2026-03-05 233503508.png|400px]]

Как видим, запрос прошел успешно, бот ответил то, что я зашил в код программы.

Попробуем получить случайное фото командой /random:

[[Файл:Изображение 2026-03-05 233610248.png|200px]]

[[Файл:Изображение 2026-03-05 233641178.png|200px]]

Теперь попробуем найти что-то конкретное и посмотреть как это будет выглядеть. Для этого сформируем команду /search. Искать будем собаку с породой самоед:

[[Файл:Изображение 2026-03-05 233810808.png|200px]]

[[Файл:Изображение 2026-03-05 233832396.png|200px]]

Как видим, бот отправил нам 4 варианта фотографий, к каждой из которой добавил ссылку на оригинал.

Притом каждый раз в терминале (консоли) мы можем заметить, как бот поддерживает подключение с Unsplash и логирует отправку сообщений.

[[Файл:Изображение 2026-03-05 234038505.png|700px]]

=== Методические материалы ===

{{#ask: [[API]] OR [[Python]] OR [[UML]] OR [[Telegram]] | ?Description }}

----
[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

----
[[Категория:Работа с API]]

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-26T14:35:56Z

CherenkovIR: /* Получение API и создание внутреннего конфигурационного API файла */

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с [[API]] фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз Unsplash API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса =====

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

После этого действия можем начинать работать и тестировать бота.

Переходим в телеграм, пишем команду /start

[[Файл:Изображение 2026-03-05 233503508.png|400px]]

Как видим, запрос прошел успешно, бот ответил то, что я зашил в код программы.

Попробуем получить случайное фото командой /random:

[[Файл:Изображение 2026-03-05 233610248.png|200px]]

[[Файл:Изображение 2026-03-05 233641178.png|200px]]

Теперь попробуем найти что-то конкретное и посмотреть как это будет выглядеть. Для этого сформируем команду /search. Искать будем собаку с породой самоед:

[[Файл:Изображение 2026-03-05 233810808.png|200px]]

[[Файл:Изображение 2026-03-05 233832396.png|200px]]

Как видим, бот отправил нам 4 варианта фотографий, к каждой из которой добавил ссылку на оригинал.

Притом каждый раз в терминале (консоли) мы можем заметить, как бот поддерживает подключение с Unsplash и логирует отправку сообщений.

[[Файл:Изображение 2026-03-05 234038505.png|700px]]

=== Методические материалы ===

{{#ask: [[API]] OR [[Python]] OR [[UML]] OR [[Telegram]] | ?Description }}

----
[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

----
[[Категория:Работа с API]]

2026-03-26T14:35:11Z

CherenkovIR: /* Пример работы с API */

{{DigitalTool
|Description=Telegram — это мессенджер и платформа для сообществ, где можно создавать групповые чаты, каналы и ботов для координации командной работы и учебных проектов.
|Affordances=Telegram позволяет организовывать большие группы и каналы, поддерживает обмен файлами, голосовые и видеозвонки, опросы и реакции, а также подключение ботов для автоматизации рутинных действий (сбор заданий, напоминания, мини‑опросы). Благодаря этому он подходит как для оперативной коммуникации команды, так и для распределённой проектной работы и смешанного обучения.
|Field_of_knowledge=Информатика
|Область применения=Образование
|End users=Учащиеся, Преподаватели, Исследователи
|Tool is made for=генерация контента
|distant_collab=Нет
|Language_Ru_Eng=Russian
|AI=Да
}}
В Telegram легко формируются учебные и профессиональные сообщества: студенческие группы курса, проектные команды, профессиональные каналы с обсуждениями и поддержкой новичков. Исследования показывают, что работа в таких чат‑группах усиливает взаимодействие, совместное обсуждение решений и вовлечённость участников, что делает платформу удобной для изучения координации, распределения ролей, аргументации и других аспектов командной деятельности

=== Симуляция поведения группы в [[ТГ]] ===
<netlogo model="tg_group_v2" />

=== Работа с API [[Telegram]] для работы с ботами ===

Для того, чтобы получить ключ для бота, необходимо его сгенерировать после создания бота. Сделать это можно через одноименного бота @BotFather в самом телеграме.

После запуска бота откройте интегрированное приложение через кнопку "Open" и создайте своего бота.

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

==== Пример работы с API ====

Одним примером из работы с API является работа с фотостоками, в котором описан полноценный цикл работы с API и созданием бота в Telegram с интеграцией поиска фотографий с сайта-фотостока.

Посмотреть статью можно ниже по ссылке:

[[Телеграм-бот для поиска фотографий через API-ключ фотостока]]

2026-03-26T14:34:52Z

CherenkovIR: /* Работа с API Telegram для работы с ботами */

{{DigitalTool
|Description=Telegram — это мессенджер и платформа для сообществ, где можно создавать групповые чаты, каналы и ботов для координации командной работы и учебных проектов.
|Affordances=Telegram позволяет организовывать большие группы и каналы, поддерживает обмен файлами, голосовые и видеозвонки, опросы и реакции, а также подключение ботов для автоматизации рутинных действий (сбор заданий, напоминания, мини‑опросы). Благодаря этому он подходит как для оперативной коммуникации команды, так и для распределённой проектной работы и смешанного обучения.
|Field_of_knowledge=Информатика
|Область применения=Образование
|End users=Учащиеся, Преподаватели, Исследователи
|Tool is made for=генерация контента
|distant_collab=Нет
|Language_Ru_Eng=Russian
|AI=Да
}}
В Telegram легко формируются учебные и профессиональные сообщества: студенческие группы курса, проектные команды, профессиональные каналы с обсуждениями и поддержкой новичков. Исследования показывают, что работа в таких чат‑группах усиливает взаимодействие, совместное обсуждение решений и вовлечённость участников, что делает платформу удобной для изучения координации, распределения ролей, аргументации и других аспектов командной деятельности

=== Симуляция поведения группы в [[ТГ]] ===
<netlogo model="tg_group_v2" />

=== Работа с API [[Telegram]] для работы с ботами ===

Для того, чтобы получить ключ для бота, необходимо его сгенерировать после создания бота. Сделать это можно через одноименного бота @BotFather в самом телеграме.

После запуска бота откройте интегрированное приложение через кнопку "Open" и создайте своего бота.

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

==== Пример работы с API ====

Одним примером из работы с API является работа с фотостоками, в котором описан полноценный цикл работы с API и созданием бота в Telegram с интеграцией поиска фотографий с сайта-фотостока.

[[Телеграм-бот для поиска фотографий через API-ключ фотостока]]

2026-03-26T14:31:42Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-26T14:30:08Z

CherenkovIR: /* Методические материалы */

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с [[API]] фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз Unsplash API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса =====

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

После этого действия можем начинать работать и тестировать бота.

Переходим в телеграм, пишем команду /start

[[Файл:Изображение 2026-03-05 233503508.png|400px]]

Как видим, запрос прошел успешно, бот ответил то, что я зашил в код программы.

Попробуем получить случайное фото командой /random:

[[Файл:Изображение 2026-03-05 233610248.png|200px]]

[[Файл:Изображение 2026-03-05 233641178.png|200px]]

Теперь попробуем найти что-то конкретное и посмотреть как это будет выглядеть. Для этого сформируем команду /search. Искать будем собаку с породой самоед:

[[Файл:Изображение 2026-03-05 233810808.png|200px]]

[[Файл:Изображение 2026-03-05 233832396.png|200px]]

Как видим, бот отправил нам 4 варианта фотографий, к каждой из которой добавил ссылку на оригинал.

Притом каждый раз в терминале (консоли) мы можем заметить, как бот поддерживает подключение с Unsplash и логирует отправку сообщений.

[[Файл:Изображение 2026-03-05 234038505.png|700px]]

=== Методические материалы ===

{{#ask: [[API]] OR [[Python]] OR [[UML]] OR [[Telegram]] | ?Description }}

----
[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

----
[[Категория:Работа с API]]

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-26T14:29:26Z

CherenkovIR: /* Код перед созданием класса = */

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с [[API]] фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз Unsplash API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса =====

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

После этого действия можем начинать работать и тестировать бота.

Переходим в телеграм, пишем команду /start

[[Файл:Изображение 2026-03-05 233503508.png|400px]]

Как видим, запрос прошел успешно, бот ответил то, что я зашил в код программы.

Попробуем получить случайное фото командой /random:

[[Файл:Изображение 2026-03-05 233610248.png|200px]]

[[Файл:Изображение 2026-03-05 233641178.png|200px]]

Теперь попробуем найти что-то конкретное и посмотреть как это будет выглядеть. Для этого сформируем команду /search. Искать будем собаку с породой самоед:

[[Файл:Изображение 2026-03-05 233810808.png|200px]]

[[Файл:Изображение 2026-03-05 233832396.png|200px]]

Как видим, бот отправил нам 4 варианта фотографий, к каждой из которой добавил ссылку на оригинал.

Притом каждый раз в терминале (консоли) мы можем заметить, как бот поддерживает подключение с Unsplash и логирует отправку сообщений.

[[Файл:Изображение 2026-03-05 234038505.png|700px]]

=== Методические материалы ===
* [[Python]]
{{#ask: [[Python]] | ?Description }}
* [[UML]]
{{#ask: [[UML]] | ?Description }}
* [[Telegram]]
{{#ask: [[Telegram]] | ?Description }}
* [[API]]
{{#ask: [[API]] | ?Description }}

{{#ask: [[API]] OR [[Python]] OR [[UML]] | ?Description }}

----
[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

----
[[Категория:Работа с API]]

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T20:41:07Z

CherenkovIR:

----
[[Категория:Работа с API]]

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с API фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз Unsplash API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса ======

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

После этого действия можем начинать работать и тестировать бота.

Переходим в телеграм, пишем команду /start

[[Файл:Изображение 2026-03-05 233503508.png|400px]]

Как видим, запрос прошел успешно, бот ответил то, что я зашил в код программы.

Попробуем получить случайное фото командой /random:

[[Файл:Изображение 2026-03-05 233610248.png|200px]]

[[Файл:Изображение 2026-03-05 233641178.png|200px]]

Теперь попробуем найти что-то конкретное и посмотреть как это будет выглядеть. Для этого сформируем команду /search. Искать будем собаку с породой самоед:

[[Файл:Изображение 2026-03-05 233810808.png|200px]]

[[Файл:Изображение 2026-03-05 233832396.png|200px]]

Как видим, бот отправил нам 4 варианта фотографий, к каждой из которой добавил ссылку на оригинал.

Притом каждый раз в терминале (консоли) мы можем заметить, как бот поддерживает подключение с Unsplash и логирует отправку сообщений.

[[Файл:Изображение 2026-03-05 234038505.png|700px]]

=== Методические материалы ===
* [[Python]]
{{#ask: [[Python]] | ?Description }}
* [[UML]]
{{#ask: [[UML]] | ?Description }}
* [[Telegram]]
{{#ask: [[Telegram]] | ?Description }}
* [[API]]
{{#ask: [[API]] | ?Description }}

[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T20:40:53Z

CherenkovIR:

----
[[Категория:Работа с API]]

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с API фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз Unsplash API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса ======

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

После этого действия можем начинать работать и тестировать бота.

Переходим в телеграм, пишем команду /start

[[Файл:Изображение 2026-03-05 233503508.png|400px]]

Как видим, запрос прошел успешно, бот ответил то, что я зашил в код программы.

Попробуем получить случайное фото командой /random:

[[Файл:Изображение 2026-03-05 233610248.png|200px]]

[[Файл:Изображение 2026-03-05 233641178.png|200px]]

Теперь попробуем найти что-то конкретное и посмотреть как это будет выглядеть. Для этого сформируем команду /search. Искать будем собаку с породой самоед:

[[Файл:Изображение 2026-03-05 233810808.png|200px]]

[[Файл:Изображение 2026-03-05 233832396.png|200px]]

Как видим, бот отправил нам 4 варианта фотографий, к каждой из которой добавил ссылку на оригинал.

Притом каждый раз в терминале (консоли) мы можем заметить, как бот поддерживает подключение с Unsplash и логирует отправку сообщений.

[[Файл:Изображение 2026-03-05 234038505.png|400px]]

=== Методические материалы ===
* [[Python]]
{{#ask: [[Python]] | ?Description }}
* [[UML]]
{{#ask: [[UML]] | ?Description }}
* [[Telegram]]
{{#ask: [[Telegram]] | ?Description }}
* [[API]]
{{#ask: [[API]] | ?Description }}

[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

Файл:Изображение 2026-03-05 234038505.png

2026-03-05T20:40:40Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T20:39:18Z

CherenkovIR:

----
[[Категория:Работа с API]]

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с API фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз Unsplash API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса ======

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

После этого действия можем начинать работать и тестировать бота.

Переходим в телеграм, пишем команду /start

[[Файл:Изображение 2026-03-05 233503508.png|400px]]

Как видим, запрос прошел успешно, бот ответил то, что я зашил в код программы.

Попробуем получить случайное фото командой /random:

[[Файл:Изображение 2026-03-05 233610248.png|200px]]

[[Файл:Изображение 2026-03-05 233641178.png|200px]]

Теперь попробуем найти что-то конкретное и посмотреть как это будет выглядеть. Для этого сформируем команду /search. Искать будем собаку с породой самоед:

[[Файл:Изображение 2026-03-05 233810808.png|200px]]

[[Файл:Изображение 2026-03-05 233832396.png|200px]]

Как видим, бот отправил нам 4 варианта фотографий, к каждой из которой добавил ссылку на оригинал.

=== Методические материалы ===
* [[Python]]
{{#ask: [[Python]] | ?Description }}
* [[UML]]
{{#ask: [[UML]] | ?Description }}
* [[Telegram]]
{{#ask: [[Telegram]] | ?Description }}
* [[API]]
{{#ask: [[API]] | ?Description }}

[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T20:39:08Z

CherenkovIR:

----
[[Категория:Работа с API]]

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с API фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз Unsplash API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса ======

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

После этого действия можем начинать работать и тестировать бота.

Переходим в телеграм, пишем команду /start

[[Файл:Изображение 2026-03-05 233503508.png|400px]]

Как видим, запрос прошел успешно, бот ответил то, что я зашил в код программы.

Попробуем получить случайное фото командой /random:

[[Файл:Изображение 2026-03-05 233610248.png|200px]]

[[Файл:Изображение 2026-03-05 233641178.png|200px]]

Теперь попробуем найти что-то конкретное и посмотреть как это будет выглядеть. Для этого сформируем команду /search. Искать будем собаку с породой самоед:

[[Файл:Изображение 2026-03-05 233810808.png|200px]]

[[Файл:Изображение 2026-03-05 233832396.png|200px]]

Как видим, бот отправил нам 4 варианта фотографий, к каждой из которой добавил ссылку на оригинал.

=== 📚 Методические материалы ===
* [[Python]]
{{#ask: [[Python]] | ?Description }}
* [[UML]]
{{#ask: [[UML]] | ?Description }}
* [[Telegram]]
{{#ask: [[Telegram]] | ?Description }}
* [[API]]
{{#ask: [[API]] | ?Description }}

[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

Файл:Изображение 2026-03-05 233832396.png

2026-03-05T20:38:34Z

CherenkovIR:

Файл:Изображение 2026-03-05 233810808.png

2026-03-05T20:38:13Z

CherenkovIR:

Файл:Изображение 2026-03-05 233641178.png

2026-03-05T20:36:44Z

CherenkovIR:

Файл:Изображение 2026-03-05 233610248.png

2026-03-05T20:36:12Z

CherenkovIR:

Файл:Изображение 2026-03-05 233503508.png

2026-03-05T20:35:06Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T20:33:44Z

CherenkovIR:

----
[[Категория:Работа с API]]

=== Определение функциональных требований к боту ===

Перед работой над созданием бота, я решил создать реестр требований, чтобы точно отслеживать какие моменты я хочу увидеть в работе бота.

В моем представлении, бот, работающий с API фотостока, должен уметь работать с медиа-файлами. Помимо всего прочего, бот - есть бот, он должен уметь первоначально взаимодействовать с пользователем и отзываться на его команды. Соответственно, необходимо эти команды придумать и понять, что пользователь захочет сделать.

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

* Бот должен уметь начинать работу с пользователем через команду /start
* Бот должен уметь рассказывать о себе и о том зачем он нужен
* В случае, если пользователь забыл команды - напомнить пользователю о них через команду /help
* Иметь возможность работать как с открытыми запросами (на случай, если нужна случайная фотография), так и с закрытыми (при конкретных запросах)
* Выдавать ссылку на источник с фотографией, при выборе пользователем нужной фотографии (из 4-х)

=== Получение API и создание внутреннего конфигурационного API файла ===

Далее также важный момент, для работы бота потребуется '''ДВА API ключа'''. Первый - Telegram Bot Key, второй - как раз Unsplash API.

Для того, чтобы получить ключ для бота [[Telegram]], необходимо его создать. Сделать это можно через бота @BotFather.

При заходе в бота, необходимо открыть внутреннее интегрированное приложение через кнопку "Open" и создать своего бота:

[[Файл:Vnutrprilozh.jpg|300px]]

[[Файл:Изображение 2026-03-05 193728808.png|300px]]

После получения доступа к API бота - его нужно будет в дальнейшем сохранить в файл .env в той же папке, где и сам файл Python, но об этом чуть позже.

[[Файл:Изображение 2026-03-05 193843194.png|300px]]

Теперь нужно получить API ключ фотостока, я выбрал [[Unsplash]], так как получение API там не затруднено лишними тарифными планами и дополнительными регистрациями.

Чтобы получить доступ к API [[Unsplash]] необходимо зайти на их [https://unsplash.com/documentation сайт], зарегистрироваться и в личном кабинете открыть новое приложение (проект), указать его вид и название. Важно, что Access и Secret ключи должны быть конфиденциальны и не могут передаваться третьим лицам, поэтому в этом проекте и статье, ключи будут скрыты.

[[Файл:Изображение 2026-03-05 194604126.png|300px]]

После получения всех требуемых API ключей - сохраняем их в файл окружения .env в переменные, которые в дальнейшем будем использовать в Python-коде.

[[Файл:Изображение 2026-03-05 194020044.png|300px]]

=== Разработка бота ===

==== Начало работы и создание заглушки ====

Для начала был создан файлик с начальными зависимостями в [[Python]]

"requirements.txt"

[[Файл:Requirements.jpg|300px]]

После создания этого файлика необходимо запустить команду `pip install -r [путь к файлу]` и указать путь к созданному requirements.txt

[[Файл:Pipinstall-r.jpg|500px]]

<syntaxhighlight lang="bash">
pip install -r requirements.txt
</syntaxhighlight>

==== Начало разработки кода ====

Так как разработка в [[Python]] позволяет работать с разными существующими библиотеками, имеющие свои документации, будем пользоваться предоставленными правами.

Для работы бота я подключил несколько библиотек, такие как:

* python-telegram-bot - основная библиотека для создания Telegram ботов
* requests - библиотека для отправки HTTP-запросов к API Unsplash
* python-dotenv - загрузка переменных окружения из файла .env
* logging - логирование событий и ошибок для отладки
* os - взаимодействие с операционной системой
* uuid - генерация уникальных идентификаторов

В соответствии с ранее описанными функциональными требованиями диаграмма [[UML]] ниже

<uml>
@startuml
actor Пользователь as User
participant "Telegram Bot" as TB
participant "Обработчик" as H
participant "Unsplash API" as API
participant "Хранилище" as DB

== Поиск фото ==
User -> TB: /search природа
TB -> H: Команда
H -> API: GET photos?query=природа
API --> H: 4 фото
H -> DB: Сохранить фото
loop 4 фото
H -> TB: Фото + кнопка
TB --> User: Показать
end

== Выбор фото ==
User -> TB: Нажимает кнопку
TB -> H: callback_data
H -> DB: Получить фото
DB --> H: Данные фото
H -> TB: Ссылки на фото
TB --> User: Оригинал\nАвтор\nUnsplash

== Случайное фото ==
User -> TB: /random
TB -> H: Команда
H -> API: GET random photo
API --> H: Случайное фото
H -> TB: Фото + ссылки
TB --> User: Показать

alt Ошибка
H -> TB: Ошибка...
TB --> User: Сообщение об ошибке
end
@enduml
</uml>

==== Непосредственная работа с кодом приложения ====

===== Код перед созданием класса ======

Импорт вышеописанных библиотек и подгрузка переменных из файла .env:

<syntaxhighlight lang="python">
import logging
import os
import uuid
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes, CallbackQueryHandler
import requests

load_dotenv()
</syntaxhighlight>

Настройка логирования

<syntaxhighlight lang="python">
logging.basicConfig(
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
level=logging.INFO
)
logger = logging.getLogger(__name__)
</syntaxhighlight>

===== Работа с классом =====

Далее, так как пользователей у бота может быть несколько - крайне важно создать класс, который поможет работать нескольким пользователям одновременно в соответствие с объектно-ориентированным программированием.

Для этого я создал класс, в котором указал основные метаданные, а также функции:

<syntaxhighlight lang="python">
class UnsplashTelegramBot:
def __init__(self):
self.unsplash_key = os.getenv('UNSPLASH_ACCESS_KEY')
self.telegram_token = os.getenv('TELEGRAM_BOT_TOKEN')
self.unsplash_url = "https://api.unsplash.com"
self.headers = {
'Authorization': f'Client-ID {self.unsplash_key}'
}

self.search_results = {}
</syntaxhighlight>

====== Программирование функций класса бота ======

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

<syntaxhighlight lang="python">
async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /start"""
welcome_message = (
"Привет! Я бот для поиска фотографий на Unsplash.\n\n"
"Команды:\n"
"/search <запрос> - поиск и выбор из 4 фотографий\n"
"/random - случайное фото\n"
"/popular - популярные фото\n"
"/help - помощь"
)
await update.message.reply_text(welcome_message)
</syntaxhighlight>

* /help - дополнительная команда, которая будет отчасти повторять функционал команды /start, но описывать функционал более подробно.

<syntaxhighlight lang="python">
async def help_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Команда /help"""
help_text = (
"? Как пользоваться ботом:\n\n"
"1. Для поиска фото напиши: /search природа\n"
" Бот покажет 4 фото на выбор\n"
"2. Нажми на кнопку под фото, чтобы получить ссылку на источник\n"
"3. Для случайного фото: /random\n"
"4. Для популярных фото: /popular\n\n"
"Также можно просто отправить текстовый запрос для поиска!"
)
await update.message.reply_text(help_text)
</syntaxhighlight>

* /search или сообщение без команды - основа всего бота, поиск фотографий и показ 4-х фотографий.

<syntaxhighlight lang="python">
async def search_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Поиск фотографий и показ 4 вариантов"""

if context.args:
query = ' '.join(context.args)
else:
# Команда без арг-тов, просто сообщение
if update.message and update.message.text and not update.message.text.startswith('/'):
query = update.message.text
else:
await update.message.reply_text("Пожалуйста, укажи запрос. Например: /search природа")
return

# Отправляем сообщение о поиске
status_message = await update.message.reply_text(f"Ищу фото по запросу: {query}...")

try:
# Получаем 4 фотографии
response = requests.get(
f"{self.unsplash_url}/search/photos",
headers=self.headers,
params={'query': query, 'per_page': 4, 'page': 1}
)

if response.status_code == 200:
data = response.json()
if data['results']:
# Удаляем сообщение о поиске
await status_message.delete()

# Уникальный ID
search_id = str(uuid.uuid4())[:8]
self.search_results[search_id] = data['results']

for i, photo in enumerate(data['results'], 1):
caption = f"Вариант {i} из 4\n👤 Автор: {photo['user']['name']}"

keyboard = [
[InlineKeyboardButton(
"Получить ссылку на источник",
callback_data=f"get_link_{search_id}_{i-1}"
)]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
reply_markup=reply_markup
)

# Отправляем сообщение с инструкцией
await update.message.reply_text(
f"✅ Найдено {data['total']} фото. Выбери понравившийся вариант, чтобы получить ссылку на источник!"
)
else:
await status_message.edit_text("Ничего не найдено. Попробуй другой запрос.")
else:
await status_message.edit_text("❌ Ошибка при поиске фото. Попробуй позже.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_message.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /random - случайное фото из Unsplash.

<syntaxhighlight lang="python">
async def random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Случайное фото"""
await self.send_random_photo(update, context)

async def send_random_photo(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Отправка случайного фото"""
# Определяем, откуда пришел запрос
if update.callback_query:
message = update.callback_query.message
await update.callback_query.answer()
else:
message = update.message

query = ' '.join(context.args) if context.args and hasattr(context, 'args') else None

status_msg = await message.reply_text("🎲 Получаю случайное фото...")

try:
params = {}
if query:
params['query'] = query

response = requests.get(
f"{self.unsplash_url}/photos/random",
headers=self.headers,
params=params
)

if response.status_code == 200:
photo = response.json()
await status_msg.delete()

caption = (
f"**Случайное фото**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"📝 **Описание:** {photo.get('description', 'Нет описания')}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Создаем кнопки для действий с фото
keyboard = [
[InlineKeyboardButton("🔗 Получить все ссылки", callback_data=f"get_link_random_{photo['id']}")],
[InlineKeyboardButton("🔄 Еще случайное", callback_data="random_photo")]
]
reply_markup = InlineKeyboardMarkup(keyboard)

await message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото для возможного запроса ссылок
if not hasattr(self, 'random_photos'):
self.random_photos = {}
self.random_photos[photo['id']] = photo

else:
await status_msg.edit_text("❌ Ошибка при получении случайного фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка. Попробуй еще раз.")
</syntaxhighlight>

* /popular - случайное фото из подборки "Популярное" из Unsplash. делается наподобие команды /random.

<syntaxhighlight lang="python">
async def popular_photos(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
"""Популярные фото"""
status_msg = await update.message.reply_text("🔥 Загружаю популярные фото...")

try:
response = requests.get(
f"{self.unsplash_url}/photos",
headers=self.headers,
params={'per_page': 5, 'order_by': 'popular'}
)

if response.status_code == 200:
photos = response.json()
await status_msg.delete()

for i, photo in enumerate(photos, 1):
caption = (
f"🔥 **Популярное фото #{i}**\n\n"
f"👤 **Автор:** {photo['user']['name']}\n"
f"❤️ **Лайков:** {photo['likes']}\n\n"
f"[🔗 Открыть на Unsplash]({photo['links']['html']})"
)

# Кнопка для получения ссылок
keyboard = [[InlineKeyboardButton("🔗 Получить ссылки", callback_data=f"get_link_popular_{photo['id']}")]]
reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_photo(
photo=photo['urls']['regular'],
caption=caption,
parse_mode='Markdown',
reply_markup=reply_markup
)

# Сохраняем фото
if not hasattr(self, 'popular_photos_cache'):
self.popular_photos_cache = {}
self.popular_photos_cache[photo['id']] = photo
else:
await status_msg.edit_text("❌ Ошибка при загрузке популярных фото.")

except Exception as e:
logger.error(f"Ошибка: {e}")
await status_msg.edit_text("❌ Произошла ошибка.")
</syntaxhighlight>

===== Написание обработчика на запуск бота =====

Функция на запуск бота, включает в себя создание приложения, обработчики команд и логирование всех команд в терминале.

<syntaxhighlight lang="python">
def run(self):
"""Запуск бота"""
application = Application.builder().token(self.telegram_token).build()

application.add_handler(CommandHandler("start", self.start))
application.add_handler(CommandHandler("help", self.help_command))
application.add_handler(CommandHandler("search", self.search_photos))
application.add_handler(CommandHandler("random", self.random_photo))
application.add_handler(CommandHandler("popular", self.popular_photos))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self.handle_message))
application.add_handler(CallbackQueryHandler(self.handle_callback))

print("/start")
application.run_polling(allowed_updates=Update.ALL_TYPES)
</syntaxhighlight>

Вне класса также создаем класс и запускаем бота.

<syntaxhighlight lang="python">
if __name__ == "__main__":
bot = UnsplashTelegramBot()
bot.run()
</syntaxhighlight>

==== Запуск бота и его тестирование ====

Производим запуск бота через запуск исполняемого python файла:

[[Файл:Изображение 2026-03-05 233335238.png|400px]]

=== 📚 Методические материалы ===
* [[Python]]
{{#ask: [[Python]] | ?Description }}
* [[UML]]
{{#ask: [[UML]] | ?Description }}
* [[Telegram]]
{{#ask: [[Telegram]] | ?Description }}
* [[API]]
{{#ask: [[API]] | ?Description }}

[[Участник:CherenkovIR|CherenkovIR]] ([[Обсуждение участника:CherenkovIR|обсуждение]])

Файл:Изображение 2026-03-05 233335238.png

2026-03-05T20:33:38Z

CherenkovIR:

Обсуждение участника:CherenkovIR

2026-03-05T19:41:42Z

CherenkovIR: /* А зачем изображения листинга? */

== Пример [[Mermaid]] ==

{{#mermaid:sequenceDiagram
actor Student #red
autonumber
Student->>Admin: Can I enrol this semester?
loop enrolmentCheck
Admin->>Admin: Check previous results
end
Note right of Admin: Exam results may <br> be delayed
Admin-->>Student: Enrolment success
Admin->>Professor: Assign student to tutor
Professor-->>Admin: Student is assigned
}}

== возможности графвиз ==

[[MedicalOntologyDiagram]]

{{#ask: [[MedicalOntologyDiagram]] | format = embedded }}}}

== А зачем изображения листинга? ==

Пишите просто текст программы через <nowiki><syntaxhighlight lang="python"></nowiki>
<syntaxhighlight lang="python">
python-telegram-bot==20.7
</syntaxhighlight>

Спасибо, не знал про этот тег)

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T17:32:11Z

CherenkovIR: /* 📚 Методические материалы */

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T17:31:14Z

CherenkovIR:

Файл:Изображение 2026-03-05 203020179.png

2026-03-05T17:30:22Z

CherenkovIR:

Файл:Изображение 2026-03-05 202911267.png

2026-03-05T17:29:13Z

CherenkovIR:

Файл:Изображение 2026-03-05 202638446.png

2026-03-05T17:26:47Z

CherenkovIR:

Файл:Изображение 2026-03-05 202422793.png

2026-03-05T17:24:25Z

CherenkovIR:

Файл:Изображение 2026-03-05 201937556.png

2026-03-05T17:19:40Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T17:17:22Z

CherenkovIR:

Файл:Изображение 2026-03-05 201713890.png

2026-03-05T17:17:18Z

CherenkovIR:

Файл:Изображение 2026-03-05 201355452.png

2026-03-05T17:14:18Z

CherenkovIR:

Файл:Изображение 2026-03-05 201337716.png

2026-03-05T17:13:40Z

CherenkovIR:

Файл:Изображение 2026-03-05 201145853.png

2026-03-05T17:11:49Z

CherenkovIR:

Файл:Изображение 2026-03-05 201047804.png

2026-03-05T17:10:50Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T16:56:08Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T16:55:36Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T16:54:32Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T16:52:48Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T16:51:37Z

CherenkovIR:

Файл:Изображение 2026-03-05 194604126.png

2026-03-05T16:46:13Z

CherenkovIR:

Файл:Изображение 2026-03-05 194020044.png

2026-03-05T16:40:22Z

CherenkovIR:

Файл:Изображение 2026-03-05 193843194.png

2026-03-05T16:38:48Z

CherenkovIR:

Файл:Изображение 2026-03-05 193728808.png

2026-03-05T16:37:32Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T16:32:44Z

CherenkovIR:

Файл:Vnutrprilozh.jpg

2026-03-05T16:32:27Z

CherenkovIR:

Телеграм-бот для поиска фотографий через API-ключ фотостока

2026-03-05T16:29:38Z

CherenkovIR:

Файл:Pipinstall-r.jpg

2026-03-05T16:27:34Z

CherenkovIR: