Ключевые вопросы параграфа
- Как устроен протокол HTTP и как формируются запросы?
- Что такое API и зачем они нужны?
- Как отправлять HTTP-запросы с помощью библиотеки
requests
? - Как получать и сохранять данные, возвращаемые API?
- Как работать с авторизацией через OAuth и API Яндекс Диска?
Как устроен протокол HTTP и как формируются запросы
Когда вы загружаете веб-страницу или отправляете данные через форму, ваш компьютер общается с сервером. Но как именно происходит этот обмен?
На самом деле данные в компьютере — это просто последовательности байтов. А между устройствами эти байты передаются в виде сигналов — электрических, радиоволн, света и т. д. Чтобы такие передачи были возможны и согласованы, используется система уровней передачи данных, описанная в модели OSI (Open Systems Interconnection model).
Обмен данными между устройствами, при котором данные проходят все уровни от прикладного до физического и обратно
Каждый уровень OSI определяет свои правила — протоколы, которые задают, как именно передавать информацию. Программы, с которыми мы работаем (браузеры, почтовые клиенты, API), используют прикладной уровень — самый верхний из семи. Это позволяет программисту не думать о низкоуровневой передаче сигналов, а просто выбрать нужный протокол и отправить запрос.
Один из самых распространённых протоколов прикладного уровня — HTTP (HyperText Transfer Protocol). Изначально он создавался для работы с HTML-документами, но сегодня используется для передачи любых типов данных: текстов, изображений, видео, документов.
HTTP устроен по принципу «запрос — ответ»:
- клиент (например, браузер или программа) формирует запрос;
- сервер принимает его и возвращает ответ с данными и кодом состояния.
Коды состояния — это числа, по которым можно понять, как обработан запрос. Например:
200
— всё прошло успешно;404
— объект не найден;500
— ошибка на сервере.
Среди команд (методов) HTTP есть:
GET
— получить данные;POST
— отправить данные;PUT
— создать или заменить ресурс;DELETE
— удалить ресурс.
HTTP-запросы широко применяются не только для загрузки веб-страниц. Многие современные сервисы возвращают по ним структурированные данные — например, список фильмов, прогноз погоды, изображение карты или результат поиска. Это возможно благодаря API (Application Programming Interface) — описаниям правил, по которым программы могут взаимодействовать друг с другом через HTTP.
API можно вызывать напрямую из браузера (через URL), но чаще всего для этого пишут программы на Python, JavaScript и других языках.
Далее мы разберём, как формировать такие запросы с помощью библиотеки requests
, и вы научитесь получать полезные данные с внешних сервисов. Но сперва поговорим о том, что такое API.
Что такое API и зачем они нужны
Когда веб-сервису нужно передавать не веб-страницу, а данные — например, изображение, JSON-файл или координаты объекта, — он предоставляет API (Application Programming Interface). Это набор правил, по которым внешняя программа может отправить запрос и получить ответ. Обычно API работает поверх протокола HTTP — и поддерживает те же принципы: «запрос — ответ».
Один из примеров такого интерфейса — Static API Яндекс Карт. С его помощью можно получить изображение карты по заданным координатам, настроить масштаб, тип отображения (схема, спутник), добавить метки и включить пробки. Такой API особенно удобен, когда нужна актуальная карта, а не заранее загруженное изображение.
Простой пример запроса, который можно открыть прямо в браузере:
https://static-maps.yandex.ru/1.x/?ll=37.677751,55.757718&spn=0.016457,0.00619&l=map
В этом URL:
ll
— координаты центра карты (долгота и широта);spn
— размер области показа;l
— тип карты (map
,sat
и др.).
Обратите внимание: в бесплатной версии Static API изображение карты должно быть размещено в открытом доступе — на сайте или в приложении. Также есть и другие ограничения, с которыми важно ознакомиться до начала работы.
А теперь потренируемся отправлять запросы с помощью библиотеки requests
.
Как отправлять HTTP-запросы с помощью библиотеки requests
Чтобы получить данные от API в своей программе, нужно отправить HTTP-запрос и обработать HTTP-ответ. Сделать это удобно с помощью популярной библиотеки Python — requests
.
Библиотека не входит в стандартную поставку Python, поэтому перед началом работы установите её с помощью команды:
pip install `requests`
В requests
используются функции с теми же названиями, что и HTTP-запросы: get()
, post()
, put()
и другие.
Рассмотрим пример GET-запроса к Static API Яндекс Карт:
1from requests import get
2
3response = get("<https://static-maps.yandex.ru/1.x/>?"
4 "ll=37.677751,55.757718&"
5 "spn=0.016457,0.00619&"
6 "l=map")
7print(response)
8
9# Вывод программы
10
11# <Response [200]>
Код ответа 200
означает, что запрос был успешно обработан сервером. Теперь можно извлечь полученные данные. Они находятся в атрибуте .content
и представлены в виде последовательности байтов — это изображение карты в формате PNG.
Запишем его в файл:
1with open("map.png", "wb") as file:
2 file.write(response.content)
Файл map.png
будет создан в той же папке, где находится программа. В нём окажется изображение нужного участка карты, сгенерированное сервером по указанным координатам и параметрам.
Как получать и сохранять данные, возвращаемые API
Ранее мы формировали HTTP-запрос как одну длинную строку. Однако у функции get()
есть удобный именованный аргумент params
, в который можно передать словарь параметров, — это делает код чище и понятнее:
1params = {
2 "ll": "37.677751,55.757718",
3 "spn": "0.016457,0.00619",
4 "l": "map"
5}
6response = get("<https://static-maps.yandex.ru/1.x/>", params=params)
При работе с API важно предусматривать обработку нештатных ситуаций, например отсутствие подключения к интернету. Если Сеть недоступна, requests
выбросит исключение ConnectionError
. Чтобы программа не завершалась с ошибкой, обернём запрос в конструкцию try–except
:
1from requests import get, ConnectionError
2
3params = {
4 "ll": "37.677751,55.757718",
5 "spn": "0.016457,0.00619",
6 "l": "map"
7}
8
9try:
10 response = get("<https://static-maps.yandex.ru/1.x/>", params=params)
11except ConnectionError:
12 print("Проверьте подключение к Сети.")
13else:
14 with open("map.png", "wb") as file:
15 file.write(response.content)
Если запрос прошёл успешно, карта будет сохранена в файл map.png в виде PNG-изображения.
На заметку: Static API Яндекс Карт поддерживает гораздо больше параметров — их список и примеры использования доступны в официальной документации.
Как работать с авторизацией через OAuth и API Яндекс Диска
Рассмотрим ещё один пример взаимодействия с API — на этот раз с облачным хранилищем Яндекс Диск. Он позволяет сохранять файлы, получать информацию о доступном месте и управлять содержимым хранилища. API Яндекс Диска подробно описан в официальной документации.
Авторизация по OAuth 2.0
Для доступа к данным пользователя необходима авторизация по протоколу OAuth 2.0. Это безопасный способ получить доступ к файлам, не запрашивая логин и пароль. Вместо этого используется токен авторизации — уникальная строка-ключ, которую необходимо добавлять к каждому запросу.
Чтобы получить токен, нужно:
- Зарегистрировать приложение на странице создания клиента OAuth.
- Указать:
- название сервиса;
- платформу «Веб-сервисы»;
- тип URL — «Подставить URL для разработки»;
- доступ к «Яндекс Диск REST API» со всеми четырьмя правами.
- После регистрации приложения вы получите учётные данные клиента:
ClientID
,Client secret
,Redirect URL
. Они используются для аутентификации и авторизации вашего приложения при работе с API по протоколу OAuth 2.0.
Эти данные понадобятся для получения токена через библиотеку requests-oauthlib
.
Пример авторизации
1from requests_oauthlib import OAuth2Session
2from requests import get, post, put, delete
3
4client_id = ""
5client_secret = ""
6auth_url = "<https://oauth.yandex.ru/authorize>"
7token_url = "<https://oauth.yandex.ru/token>"
8
9oauth = OAuth2Session(client_id=client_id)
10authorization_url, state = oauth.authorization_url(auth_url, force_confirm="true")
11print("Перейдите по ссылке и авторизуйтесь:", authorization_url)
12
13code = input("Введите одноразовый код: ")
14
15token = oauth.fetch_token(
16 token_url=token_url,
17 code=code,
18 client_secret=client_secret
19)
20
21access_token = token["access_token"]
22print(access_token)
Полученный токен нужно добавлять к каждому запросу через заголовок Authorization
.
1headers = {"Authorization": f"OAuth {access_token}"}
Как получить информацию о диске
Для получения базовой информации (объём, свободное место, ограничения) используйте GET-запрос:
1r = get("<https://cloud-api.yandex.net/v1/disk>", headers=headers)
2print(r.json())
Ответ будет в формате JSON. Его можно обработать как словарь Python.
Как создать папку на диске
Создадим новую папку под названием Тест API
:
1params = {"path": "Тест API"}
2r = put("<https://cloud-api.yandex.net/v1/disk/resources>", headers=headers, params=params)
3print(r)
Если всё прошло успешно, вы увидите: <Response [201]>
. Папка появится в корне диска.

Как загрузить файл в облако
Чтобы загрузить файл map.png на Яндекс Диск с помощью API, выполните следующие шаги:
- Получите временную ссылку для загрузки файла.
- Отправьте файл по этой ссылке.
- Убедитесь, что файл успешно загружен.
Шаг 1. Получите временную ссылку
Сначала нужно запросить URL, по которому вы сможете загрузить файл:
1params = {"path": "Тест API/map.png"}
2r = get("<https://cloud-api.yandex.net/v1/disk/resources/upload>", headers=headers, params=params)
3href = r.json()["href"]
Шаг 2. Отправьте файл по этой ссылке
Теперь загрузите файл map.png
с помощью метода PUT:
1files = {"file": open("map.png", "rb")}
2r = put(href, files=files)
3print(r)
Шаг 3. Проверьте результат
Если файл успешно загружен, вы увидите в выводе:
Результат: <Response [201]>
. Файл будет загружен в облако.

Теперь файл доступен в вашем Яндекс Диске по пути Тест API/map.png
.
Что ещё можно сделать
Полный список возможностей API Яндекс Диска доступен по ссылке. Вы можете:
- удалять и перемещать файлы;
- публиковать ссылки;
- отслеживать изменения в хранилище;
- организовывать структуру папок.
✅ У вас получилось разобраться с HTTP и API?
Что дальше
В этом параграфе вы узнали, как устроен протокол HTTP и как формировать запросы с помощью библиотеки requests
. Вы научились отправлять запросы, получать ответы от сервера, сохранять данные и обрабатывать возможные ошибки Сети.
Также вы познакомились с концепцией API — интерфейса для взаимодействия между программами. Мы разобрали, как работать с Static API Яндекс Карт и выполнять авторизацию через OAuth 2.0 для доступа к API Яндекс.Диска. Теперь вы умеете отправлять запросы, использовать токены, работать с заголовками и даже загружать файлы в облако.
В следующем параграфе подведем итоги всей главы: вспомним ключевые приёмы работы с числами, таблицами и запросами и обсудим, как двигаться дальше.
А пока вы не ушли дальше — закрепите материал на практике:
- Отметьте, что урок прочитан, при помощи кнопки ниже.
- Пройдите мини-квиз, чтобы проверить, насколько хорошо вы усвоили тему.
- Перейдите к задачам этого параграфа и потренируйтесь.
- Перед этим загляните в короткий гайд о том, как работает система проверки.
Хотите обсудить, задать вопрос или не понимаете, почему код не работает? Мы всё предусмотрели — вступайте в сообщество Хендбука! Там студенты помогают друг другу разобраться.
Ключевые выводы параграфа
- Протокол HTTP описывает правила обмена данными по модели «запрос — ответ» и используется для взаимодействия между программами.
- Библиотека
requests
позволяет отправлять HTTP-запросы и получать ответы, обрабатывать ошибки и сохранять данные. - API — это интерфейс взаимодействия с внешним сервисом: вы можете отправлять параметры, получать ответы и строить автоматизации.
- Static API Яндекс Карт возвращает изображения карт по заданным координатам через HTTP-запрос.
- Для работы с API Яндекс Диска требуется авторизация по OAuth 2.0 и передача токена в заголовке запроса; это позволяет управлять файлами в облаке.