Многие веб-приложения подключаются к различным сторонним сервисам с помощью API. Используя эти API, вы можете получить доступ к таким данным, как информация о погоде, результаты спортивных соревнований, списки фильмов, твиты, результаты поиска и изображения. Вы можете использовать API, чтобы расширить функции своего приложения, например, добавить платежи, планирование, электронные письма, переводы, карты и передачу файлов. Чтобы создать какую-либо из этих функций самостоятельно, вы потратили бы уйму времени, но с помощью API вы потратите на это всего несколько минут.
В этом мануале мы расскажем о библиотеке Requests Python, которая позволяет отправлять HTTP-запросы в Python.
Requests позволяет использовать API в Python, поскольку использование API – это не что иное, как отправка HTTP-запросов и получение ответов. В мануале мы покажем, как использовать API для перевода текста с одного языка на другой.
Краткий обзор HTTP-запросов
HTTP-запросы – это основа работы сети. Каждый раз, когда вы переходите на веб-страницу, ваш браузер отправляет несколько запросов на сервер веб-страницы. Сервер в ответ отправляет все данные, необходимые для отображения страницы, а затем ваш браузер фактически отображает страницу.
Общий процесс таков:
- клиент (например, браузер или сценарий Python, использующий запросы) отправляет некоторые данные на URL.
- сервер, расположенный на этом URL, читает данные, решает, что с ними делать, и возвращает ответ клиенту.
- клиент решает, что делать с полученными данными.
Часть данных, которую клиент отправляет в запросе, является методом запроса. Распространенными методами запросов являются GET, POST и PUT. GET-запросы, как правило, предназначены только для чтения данных без внесения каких-либо изменений, а POST и PUT-запросы обычно используются для изменения данных на сервере. Так, например, Stripe API позволяет использовать POST-запросы для создания нового счета, чтобы пользователь мог что-то купить в вашем приложении.
Примечание: В этом мануале мы не будем изменять какие-либо данные на сервере, потому рассматриваем только запросы GET.
Отправляя запрос из скрипта Python или из веб-приложения, разработчик решает, что будет отправлено в каждом запросе и что делать с ответом.
Давайте попробуем поработать с библиотекой Requests. В этом мануале для примера мы сначала отправим запрос в Scotch.io, а затем используем API перевода.
1: Установка библиотеки requests
Сначала нужно установить библиотеку. Давайте установим ее с помощью пакетного менеджера pip.
Примечание: Рекомендуем создать виртуальную среду, если у вас ее еще нет, и установить библиотеку в нее.
pip install requests
2: Отправка запроса
Сначала мы воспользуемся библиотекой 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
И вот что вы получите:
>python script.py
<Response [200]>
>
3: Коды состояния
Первое, что мы должны сделать, – это проверить код состояния. Коды HTTP представлены в диапазоне от 1XX до 5XX. Вы, вероятно, встречали коды состояния 200, 404 и 500.
Вот что означает каждый код:
- 1XX – информация
- 2XX – успешное выполнение
- 3XX – перенаправление
- 4XX – ошибка на стороне клиента (у вас)
- 5XX – ошибка на стороне сервера (у сайта)
Как правило, выполняя свои запросы, вы должны получать коды состояния 2ХХ.
Библиотека Requests понимает, что 4XX и 5XX являются ошибками, поэтому если возвращаются эти коды состояния, объект ответа из запроса оценивается как False.
Вы можете убедиться, что запрос успешно обработан, проверив ответ так:
if res:
print('Response OK')
else:
print('Response Failed')
Сообщение «Response Failed» появится только в случае возврата кода состояния 400 или 500. Попробуйте указать неверный URL-адрес, и тогда вы получите ошибку 404 и увидите сообщение «Response Failed».
Вы можете взглянуть на код состояния напрямую, добавив в script.py строку:
print(res.status_code)
Это покажет вам код состояния напрямую, чтобы вы могли все проверить самостоятельно.
>python script.py
<Response [404]>
Response Failed
404
>
4: Заголовки
Также в ответе на запрос вы можете найти заголовки.
Используйте в файле строку:
print(res.headers)
Затем запустите файл.
Заголовки отправляются вместе с запросом и возвращаются в ответе. Заголовки нужны, чтобы и клиент, и сервер знали, как интерпретировать данные, отправляемые и получаемые в ответах.
На экране вы увидите длинный список возвращаемых заголовков. Чаще всего вам не нужно напрямую использовать информацию заголовков, но вы можете получить ее, если она вам понадобилась. Обычно из всех заголовков вам может понадобиться только тип контента, поскольку он показывает формат данных, например HTML, JSON, PDF и так далее. Но тип контента обычно обрабатывается библиотекой Requests, поэтому вы можете получить доступ к возвращаемым данным.
5: Текст ответа
Обратите внимание на res.text (это касается текстовых данных, таких как HTML-страница, которую мы просматриваем). Здесь вы можете увидеть весь HTML-код, необходимый для создания домашней страницы Scotch. Он не будет обработан, но мы видим, что он принадлежит Scotch. Если вы сохраните этот код в файл и откроете его, вы увидите нечто похожее на сайт Scotch. В реальной ситуации на одну веб-страницу делается несколько запросов для загрузки разных компонентов (таких, как изображения, скрипты и таблицы стилей). Поэтому если вы сохраните в файл только HTML, страница не будет выглядеть так, как выглядит Scotch.io как в браузере, потому что для получения данных HTML был выполнен только один запрос.
print(res.text)
6: Использование Translate API
Теперь давайте попробуем использовать Yandex Translate API для выполнения запроса на перевод текста на другой язык.
Чтобы использовать API, сначала необходимо зарегистрироваться. После регистрации перейдите в Translate API и создайте ключ API. Получив ключ, добавьте его в свой файл script.py как константу.
API_KEY = 'your yandex api key'
Вот ссылка, по которой можно все сделать.
Ключ API нужен нам потому, что с его помощью Яндекс сможет аутентифицировать нас каждый раз, когда мы хотим использовать его API. Ключ API представляет собой упрощенную форму аутентификации, он добавляется в конец URL-адреса запроса при отправке.
Узнать, какой URL нужно отправить, чтобы использовать API, можно в документации Яндекса.
Там можно найти всю информацию, необходимую для использования Translate API для перевода текста.
Если в URL вы видите амперсанды (&), вопросительные знаки (?) и знаки равенства (=), вы можете быть уверены, что такой URL предназначен для запросов GET. Эти символы задают соответствующие параметры URL-адреса.
Обычно в квадратных скобках ([]) указываются опциональные фрагменты. В этом случае таковыми являются format, options и callback, в то время как key, text, and lang обязательно должны присутствовать в запросе.
Давайте добавим код для отправки запроса на этот URL. Вы можете заменить первый созданный нами запрос в файле script.py следующим кодом:
url = 'https://translate.yandex.net/api/v1.5/tr.json/translate'
res = requests.get(url)
Есть два способа добавить параметры. Их можно добавить в конец URL-адреса напрямую, а можно сделать так, чтобы запросы делали это за нас. Чтобы сделать последнее, мы можем создать словарь для наших параметров. Обязательными элементами будут ключ, текст и язык. Давайте создадим словарь, используя ключ API, текст ‘Hello’ и языки ‘en-es’ (то есть текст нужно перевести с английского на испанский).
Другие языковые коды вы можете найти здесь в столбце 639-1.
Давайте создадим словарь параметров, используя функцию dict(), и передадим ей ключи и значения, которые должны быть в этом словаре. Добавьте в файл script.py:
params = dict(key=API_KEY, text='Hello', lang='en-es')
Теперь мы возьмем словарь параметров и передадим его в функцию .get().
res = requests.get(url, params=params)
После этого запросы начнут добавляться к URL-адресу самостоятельно.
Теперь давайте добавим оператор print для текста ответа и посмотрим, что вернется в результате.
print(res.text)
> python script.py
{“code”:200, “lang”:”en-es”, “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 является типом контента, мы можем сделать так, чтобы запросы преобразовывали ответ в словарь и список, чтобы легче получать доступ к данным.
Чтобы данные были обработаны как JSON, мы используем метод .json() для объекта ответа.
Если вы отобразите его, вы увидите, что данные выглядят так же, но формат немного отличается.
json = res.json()
print(json)
Теперь это не простой текст, который вы получаете из res.text, а версия словаря.
Допустим, мы хотим получить доступ к тексту. Поскольку теперь это словарь, мы можем использовать ключ text.
print(json['text'])
И теперь мы увидим только данные для этого ключа. В этом случае мы получим список из одного элемента. Если вам нужно получить этот текст в списке, можно получить к нему доступ по индексу.
print(json['text'][0])
И теперь на экране будет только переведенное слово.
Меняя параметры, вы будете получать разные результаты. Давайте изменим текст, вместо Hello будет Goodbye, а также изменим целевой язык на испанский и отправим запрос снова.
params = dict(key=API_KEY, text='Goodbye', lang='en-es')
Также можно попробовать перевести более длинный текст на другие языки и посмотреть, какие ответы дает API.
7: Ошибки Translate API
Осталось рассмотреть ошибки.
Попробуйте изменить ключ API, удалив один символ. После этого ваш ключ API станет недействительным. Затем попробуйте отправить запрос.
Если вы посмотрите на код состояния, вот что вы получите:
print(res.status_code)
> python script.py
403
>
Когда вы используете API, вам нужно проверять выполнение некоторых операций, чтобы обрабатывать ошибки в соответствии с потребностями вашего приложения.
Заключение
В этом мануале вы узнали:
- Как работают HTTP-запросы
- Различные коды состояния, которые могут быть в ответе
- Как отправлять запросы и получать ответы, используя библиотеку Requests от Python
- Как использовать Translate API для перевода текста
- Как преобразовать ответы application/JSON в словари.
В этом списке вы найдете другие доступные API. Попробуйте использовать их с библиотекой Requests.