6.3. Модуль requests

Ключевые вопросы параграфа

• Как устроен протокол 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. Это безопасный способ получить доступ к файлам, не запрашивая логин и пароль. Вместо этого используется токен авторизации — уникальная строка-ключ, которую необходимо добавлять к каждому запросу.

Чтобы получить токен, нужно:

1. Зарегистрировать приложение на странице создания клиента OAuth.
2. Указать:

• название сервиса;
• платформу «Веб-сервисы»;
• тип URL — «Подставить URL для разработки»;
• доступ к «Яндекс Диск REST API» со всеми четырьмя правами.

3. После регистрации приложения вы получите учётные данные клиента: 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. Получите временную ссылку для загрузки файла.
2. Отправьте файл по этой ссылке.
3. Убедитесь, что файл успешно загружен.

Шаг 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 и передача токена в заголовке запроса; это позволяет управлять файлами в облаке.