Введение в работу с библиотекой Requests в Python

Введение

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

Из этой статьи вы узнаете о библиотеке Python Requests, позволяющей отправлять запросы HTTP в Python.

Поскольку при использовании API отправляются запросы HTTP и получаются ответы, библиотека Requests открывает возможность использования API в Python. Мы продемонстрируем использование API для языкового перевода, чтобы вы увидели, как это работает.

Краткий обзор запросов HTTP

Запросы HTTP лежат в основе всемирной сети. Каждый раз, когда вы открываете веб-страницу, ваш браузер направляет множество запросов на сервер этой веб-страницы. Сервер отвечает на них, пересылая все необходимые данные для вывода страницы, и ваш браузер отображает страницу, чтобы вы могли увидеть ее.

В целом этот процесс выглядит так: клиент (например браузер или скрипт Python, использующий библиотеку Requests) отправляет данные на URL, а сервер с этим URL считывает данные, решает, что с ними делать, и отправляет клиенту ответ. После этого клиент может решить, что делать с полученными в ответе данными.

В составе запроса клиент отправляет данные по методу запроса. Наиболее распространенными методами запроса являются GET, POST и PUT. Запросы GET обычно предназначены только для чтения данных без их изменения, а запросы POST и PUT обычно предназначаются для изменения данных на сервере. Например, Stripe API позволяет использовать запросы POST для тарификации, чтобы пользователь мог купить что-нибудь в вашем приложении.

При отправке запроса из скрипта Python или веб-приложения вы как разработчик решаете, что отправлять в каждом запросе и что делать с полученными ответами. Для начала отправим запрос на Scotch.io и используем API для перевода.

Установка Python Requests

Прежде чем мы сможем что-либо сделать, нам нужно установить библиотеку. Так что для начала мы установим библиотеку Requests с помощью pip. Если вы еще не создали виртуальную среду, стоит сделать это сейчас.

pip install requests

Наш первый запрос

Для начала мы используем библиотеку Requests для отправки запроса на сайт Scotch.io. Создайте файл с именем script.py и добавьте в него следующий код. В этой статье мы рассматриваем небольшое количество кода, поэтому если что-то изменится, вы можете просто обновить существующий код вместо добавления новых строк.

import requests

res = requests.get('https://scotch.io')

print(res)

Этот код просто отправляет запрос GET на сайт Scotch.io. Это такой же тип запроса, какой используется вашим браузером для просмотра этой страницы, и единственное отличие заключается в том, что библиотека Requests не может выполнить рендеринг кода HTML, и поэтому вы получите просто код HTML и другую информацию, содержащуюся в ответе.

Здесь мы используем функцию .get(), однако Requests также позволяет использовать при отправке запросов и другие функции, в том числе .post() и .put().

Для отправки запроса нужно запустить файл script.py.

python script.py

Вот что вы получите в результате: запуск .

Коды состояния

Прежде всего мы проверим код состояния. Коды HTTP находятся в диапазоне от 1XX до 5XX. Наверняка вы уже знакомы с кодами состояния 200, 404 и 500.

Далее мы приведем краткий обзор значений кодов состояния:

• 1XX — информация
• 2XX — успешно
• 3XX — перенаправление
• 4XX — ошибка клиента (ошибка на вашей стороне)
• 5XX — ошибка сервера (ошибка на их стороне)

Обычно при выполнении наших собственных запросов мы хотим получить коды состояния в диапазоне 200.

Библиотека Requests понимает, что коды состояния 4XX и 5XX сигнализируют об ошибках, и поэтому при возврате этих кодов состояния объекту ответа на запрос присваивается значение False.

Проверив истинность ответа, вы можете убедиться, что запрос успешно обработан. Например:

if res:
    print('Response OK')
else:
    print('Response Failed')

Сообщение Response Failed появится только при возврате кода состояния 400 или 500. Попробуйте заменить URL на несуществующий, чтобы увидеть ошибку ответа 404.

Чтобы посмотреть код состояния, добавьте следующую строку:

print(res.status_code)

Так вы увидите код состояния и сможете сами его проверить.

Заголовки

Также в ответе вы можете получить заголовки. Вы можете посмотреть их, используя словарь headers для объекта response.

print(res.headers)

Заголовки отправляются вместе с запросом и возвращаются с ответом. Заголовки используются для того, чтобы клиент и сервер понимали, как интерпретировать данные, отправляемые и получаемые в запросе и ответе.

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

Обычно требуется заголовок content type, поскольку он показывает формат данных, например HTML, JSON, PDF, обычный текст и т. д. Однако заголовок content type обрабатывается библиотекой Requests, и вы имеете доступ ко всем возвращаемым данным.

Текст ответа

Если мы посмотрим на файл res.text (это работает для текстовых данных, таких как просматриваемая нами страница HTML), мы увидим весь код HTML, требуемый для построения домашней страницы Scotch. Рендеринг выполняться не будет, но мы увидим, что он принадлежит Scotch. Если вы сохраните этот код в файл и откроете его, вы увидите что-то похожее на сайт Scotch. В реальных условиях для загрузки на одну веб-страницу изображений, скриптов, таблиц стилей и т. д. отправляется несколько запросов, так что если вы сохраните в файл только код HTML и откроете его в браузере, результат не будет похож на страницу Scotch.io, поскольку для получения данных HTML был отправлен только один запрос.

print(res.text)

Использование Translate API

Теперь перейдем к чему-то более интересному. Мы используем API Яндекс.Перевод (Yandex Translate API) для выполнения запроса на перевод текста на другой язык.

Чтобы использовать API, нужно предварительно войти в систему. После входа в систему перейдите к Translate API и создайте ключ API. Когда у вас будет ключ API, добавьте его в свой файл в качестве константы. Далее приведена ссылка, с помощью которой вы можете сделать все перечисленное: https://tech.yandex.com/translate/

API_KEY = 'your yandex api key'

Ключ API нужен, чтобы Яндекс мог проводить аутентификацию каждый раз, когда мы хотим использовать его API. Ключ API представляет собой облегченную форму аутентификации, поскольку он добавляется в конце URL запроса при отправке.

Чтобы узнать, какой URL нам нужно отправить для использования API, посмотрим документацию Яндекса.

Там мы найдем всю информацию, необходимую для использования их Translate API для перевода текста.

Если вы видите URL с символами амперсанда (&), знаками вопроса (?) или знаками равенства (=), вы можете быть уверены, что это URL запроса GET. Эти символы задают сопутствующие параметры для URL.

Обычно все, что размещено в квадратных скобках ([]), будет необязательным. В данном случае для запроса необязательны формат, опции и обратная связь, но обязательны параметры key, text и lang.

Добавим код для отправки на этот URL. Замените первый созданный нами запрос на следующий:

url = 'https://translate.yandex.net/api/v1.5/tr.json/translate'
res = requests.get(url)

Существует два способа добавления параметров. Мы можем прямо добавить параметры в конец URL, или библиотека Requests может сделать это за нас. Для последнего нам потребуется создать словарь параметров. Нам нужно указать три элемента: ключ, текст и язык. Создадим словарь, используя ключ API, текст Hello и язык en-es, т. к. нам требуется перевод с английского на испанский.

Другие коды языков можно посмотреть здесь. Нам нужен столбец 639-1.

Мы создаем словарь параметров, используя функцию dict(), и передаем ключи и значения, которые хотим использовать в нашем словаре.

params = dict(key=API_KEY, text='Hello', lang='en-es')

Теперь возьмем словарь параметров и передадим его функции .get().

res = requests.get(url, params=params)

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

Теперь добавим команду печати текста ответа и посмотрим, что мы получим в результате.

print(res.text)

Мы видим три вещи. Мы видим код состояния, который совпадает с кодом состояния ответа, мы видим заданный нами язык и мы видим переведенный текст внутри списка. Итак, мы должны увидеть переведенный текст Hola.

Повторите эту процедуру с кодом языка en-fr, и вы получите ответ Bonjour.

params = dict(key=API_KEY, text='Hello', lang='en-fr')

Посмотрим заголовки полученного ответа.

print(res.headers)

Разумеется, заголовки должны быть другими, поскольку мы взаимодействуем с другим сервером, но в данном случае мы видим тип контента application/json вместо text/html. Это означает, что эти данные могут быть интерпретированы в формате JSON.

Если ответ имеет тип контента application/json, библиотека Requests может конвертировать его в словарь и список, чтобы нам было удобнее просматривать данные.

Для обработки данных в формате JSON мы используем метод .json() на объекте response.

Если вы распечатаете его, вы увидите те же данные, но в немного другом формате.

json = res.json()
print(json)

Причина отличия заключается в том, что это уже не обычный текст, который мы получаем из файла res.text. В данном случае это печатная версия словаря.

Допустим, нам нужно получить доступ к тексту. Поскольку сейчас это словарь, мы можем использовать ключ текста.

print(json['text'])

Теперь мы видим данные только для этого одного ключа. В данном случае мы видим список из одного элемента, так что если мы захотим напрямую получить текст в списке, мы можем использовать указатель для доступа к нему.

print(json['text'][0])

Теперь мы видим только переведенное слово.

Разумеется, если мы изменим параметры, мы получим другие результаты. Изменим переводимый текст с Hello на Goodbye, изменим язык перевода на испанский и снова отправим запрос.

params = dict(key=API_KEY, text='Goodbye', lang='en-es')

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

Примеры ошибок Translate API

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

Попробуйте изменить ключ API, удалив один символ. Теперь ваш ключ API будет недействителен. Попробуйте отправить запрос.

Если вы посмотрите код состояния, вы увидите следующее:

print(res.status_code)

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

Заключение

Мы узнали следующее:

• Принципы работы запросов HTTP
• Различные коды состояния, которые могут присутствовать в ответе
• Как отправлять запросы и получать ответы с помощью библиотеки Python Requests
• Как использовать API языкового перевода для перевода текста
• Как конвертировать ответы в формате application/JSON в словари

Если вы хотите узнать больше, посмотрите в этом списке различные доступные API и попробуйте использовать их с библиотекой Python Requests.