Во многих веб-приложениях считается нормальным подключаться к различным сторонним сервисам с помощью API. Используя эти API, вы можете получить доступ к таким данным, как информация о погоде, результаты спортивных соревнований, списки фильмов, твиты, результаты поиска и изображения. Вы также можете использовать API для добавления различных функций в ваше приложение. Примерами такого добавления могут служить платежи, планирование, электронные письма, переводы, карты и передача файлов. Если бы вы создавали какую-либо из таких функций самостоятельно, это заняло бы уйму времени, но с помощью API, вам потребуется несколько минут для подключения к нему и доступа к его функциям и данным.
В этой статье будет рассказано о библиотеке Python Requests, которая позволяет отправлять HTTP-запросы в Python.
Поскольку использование API – это просто отправка HTTP-запросов и получение ответов, Python Requests позволяют использовать API в Python. В этой лекции будет показано использование языкового перевода API, чтобы вы могли увидеть возможности его работы и потенциально использовать его в своих собственных приложениях.
Краткий обзор HTTP-запросов
HTTP-запросы – это то, как работает сеть. Каждый раз, когда вы переходите на веб-страницу, ваш браузер делает несколько запросов на сервер этой страницы. Затем сервер отвечает всеми данными, необходимыми для отображения страницы, после чего ваш браузер отображает фактическую страницу, чтобы вы могли ее увидеть.
Общий процесс таков: клиент (например, браузер или скрипт Python, использующий Python Requests) отправляет некоторые данные на URL, а затем сервер, расположенный на этом URL, считывает данные, решает, что с этими данными делать, после чего возвращает ответ клиенту. Наконец, клиент может решить, что делать с данными, полученными от сервера в качестве ответа.
Часть данных, отправляемых клиентом в запросе, является методом запроса. Некоторыми распространенными методами запроса являются такие как GET, POST и PUT. GET-запросы обычно предназначены только для чтения данных без внесения каких-либо изменений, в то время как POST и PUT-запросы обычно предназначены для изменения данных на сервере. Например, Stripe API позволяет вам использовать POST-запросы для создания объектов оплаты, чтобы пользователь мог что-то купить в вашем приложении.
В этой статье будут рассмотрены только GET-запросы потому, что нам не понадобится изменять какие-либо данные на сервере.
Отправляя запрос из скрипта Python или из веб-приложения, вы, как разработчик, должны решить, что будет отправлено в каждом запросе и что делать с ответом. Давайте исследуем Python Requests, отправив сначала запрос к сайту ya.ru, а затем с помощью API языковых переводов Яндекса.
Установка запросов Python
Прежде чем мы сможем что-либо сделать, нам нужно установить библиотеку Python Requests. Делается это с помощью команды:
pip install requests
Наш первый запрос
Для начала давайте воспользуемся запросами для чего-то простого, например, запрос для сайта ya.ru. Создадим файл с именем script.py и добавим в него следующий код.
import requests
res = requests.get('https://ya.ru')
print(res)
Этот код отправляет GET-запрос на ya.ru.
Мы используем метод get(), но библиотека Python Requests позволяет использовать и другие методы, такие как post() и put().
Запустите скрипт, выполнив файл script.py с помощью команды:
python script.py
И в качестве ответа вы увидите строчку:
<Response [200]>
Это ответ с кодом состояния 200. Что такое коды состояния читайте ниже.
Коды состояния
Первое, что мы можем сделать, это проверить код состояния или HTTP-код. Коды HTTP варьируются от 1XX до 5XX. Общие коды состояния, которые вы, вероятно, видели, это 200, 404 и 500.
Вот краткий обзор того, что означает каждый код состояния:
- 1XX - Информация
- 2XX - Успех
- 3XX - Перенаправление
- 4XX - ошибка клиента (вы ошиблись)
- 5XX - Ошибка сервера (они ошиблись)
Обычно, когда вы выполняете свои собственные запросы, вам нужны коды состояния в диапазоне 200-х.
Python Requests распознают, что коды состояния 4XX и 5XX являются ошибками, поэтому, если эти коды состояния возвращаются, объект ответа из запроса оценивается как Ложь (False).
Вы можете выяснить, ответил ли запрос успешно, просто проверив ответ на правду.
Например:
import requests
res = requests.get('https://ya.ru')
print(res)
if res:
print('Ok')
else:
print('Error')
Результатом работы кода будет:
<Response [200]>
Ok
Попробуйте сменить URL-адрес на какую-то ерунду, чтобы увидеть ответ 404.
Вы можете взглянуть на код состояния напрямую, выполнив следующее:
import requests
res = requests.get('https://ya.ru/dfdf')
print(res.status_code)
Результат работы кода:
404
Заголовки
Еще одна вещь, которую вы можете получить из ответа – это заголовки. Вы можете взглянуть на них, используя словарь заголовков объекта ответа.
import requests
res = requests.get('https://ya.ru')
print(res.headers)
Результат работы кода:
Заголовки отправляются вместе с запросом и возвращаются в ответе. Заголовки используются, чтобы и клиент, и сервер знали, как интерпретировать данные, отправляемые и получаемые.
Мы видим различные заголовки, которые возвращаются. Часто вам не нужно напрямую использовать информацию заголовка, но периодически заголовки все-таки приходится использовать.
Текст ответа
В заключении, если мы используем метод res.text (это работает для текстовых данных, таких как HTML-страница), мы можем увидеть весь HTML-код, необходимый для создания домашней страницы ya.ru. Если вы сохраните это в файл и откроете его, вы увидите нечто похожее на сайт ya.ru. В реальной ситуации для одной веб-страницы делается несколько запросов на загрузку таких компонентов, как изображения, скрипты и таблицы стилей, поэтому, если вы сохраняете только файл HTML в файл, он не будет выглядеть так, как выглядит страница ya.ru. в вашем браузере, потому что только один запрос был выполнен для получения HTML-данных.
import requests
res = requests.get('https://ya.ru')
print(res.text)
Использование API переводчика Яндекс
Итак, теперь давайте перейдем к чему-то более интересному. Мы будем использовать API Яндекс.Переводчика для выполнения запроса на перевод текста на другой язык.
Чтобы использовать API, нужно, естественно иметь аккаунт в Яндексе. А также нужен API-ключ. Чтобы его получить перейдите по ссылке – https://translate.yandex.ru/developers/keys.
Получив ключ API, добавьте его в свой файл как константу.
API_KEY = 'ваш апи ключ'
Причина, по которой нам нужен ключ API, заключается в том, что Яндекс может аутентифицировать нас каждый раз, когда мы хотим использовать их API. Ключ API, вероятно, является самой простой формой аутентификации, поскольку он просто добавляется в конец URL-адреса запроса при отправке.
Чтобы узнать, какой URL нам нужно отправить, чтобы использовать API, мы можем посмотреть документацию Яндекса здесь: https://yandex.ru/dev/translate/doc/dg/reference/translate-docpage/
Если мы посмотрим, то увидим всю информацию, необходимую для использования их API для перевода текста.
https://translate.yandex.net/api/v1.5/tr.json/translate
? [key=<API-ключ>]
& [text=<переводимый текст>]
& [lang=<направление перевода>]
& [format=<формат текста>]
& [options=<опции перевода>]
& [callback=<имя callback-функции>]
Документация по API иногда бывает трудной для чтения, но в данном случае все просто. Когда мы видим URL с амперсандами (&), вопросительными знаками (?) и знаками равенства (=), мы можем быть уверены, что URL предназначен для запросов GET. Эти символы указывают параметры, которые передаются в URL.
Обычно, то, что находится в квадратных скобках ([]), необязательно. В этом случае формат, параметры и обратный вызов являются необязательными, в то время как ключ, текст и язык требуются для запроса.
Итак, давайте напишем код для отправки данных на этот URL.
url = 'https://translate.yandex.net/api/v1.5/tr.json/translate'
res = requests.get(url)
Есть два способа добавить параметры. Мы можем либо добавить их в конец URL-адреса напрямую, либо сделать так, чтобы Python Requests делали это за нас. Второй вариант является наиболее простым.
Для этого мы можем создать словарь для наших параметров. Для этого необходимы ключ, текст и язык.
Давайте создадим словарь, используя ключ API, «Привет» для текста и «ru-es» в качестве lang, что означает, что мы хотим перевести с русского на испанский.
Если вам нужно знать коды других языков, вы можете посмотреть здесь: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes. Смотрите столбец 639-1.
Мы создаем словарь параметров, используя функцию dict() и передавая ключи и значения, которые мы хотим, в нашем словаре.
params = dict(key=API_KEY, text='Привет', lang='ru-es')
Теперь берем словарь параметров и передаем его в функцию get().
res = requests.get(url, params=params)
Когда мы передадим параметры таким способом, запросы начнут добавляться к URL-адресу автоматически.
Также давайте добавим оператор печати текста ответа и посмотрим, какой вернется результат.
import requests
API_KEY = 'ваш ключ'
url = 'https://translate.yandex.net/api/v1.5/tr.json/translate'
params = dict(key=API_KEY, text='Привет', lang='ru-es')
res = requests.get(url, params=params)
print(res.text)
Результат работы кода:
{"code":200,"lang":"ru-es","text":["Hola"]}
Что мы видим? Мы видим код состояния, мы видим язык, который мы указали, и мы видим переведенный текст внутри списка.
Попробуйте еще раз с ru-fr в качестве кода языка, и вы должны увидеть ' Salut' в ответе.
Посмотрим на заголовки этого конкретного ответа.
print(res.headers)
Результат:
{'Server': 'nginx/1.6.2', 'Date': 'Sat, 18 Jan 2020 12:06:13 GMT', 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': '44', 'Connection': 'keep-alive', 'Keep-Alive': 'timeout=120', 'X-Content-Type-Options': 'nosniff', 'Cache-Control': 'no-store'}
Здесь ти контента application/json. Это это означает, что данные могут быть интерпретированы как JSON.
Когда application/json является типом содержимого ответа, мы можем сделать так, чтобы Python Requests преобразовали ответ в словарь и список, чтобы мы могли легче получать доступ к данным.
Чтобы данные были проанализированы как JSON, мы используем метод json() для объекта ответа.
Если вы распечатаете его, вы увидите, что данные выглядят одинаково, но формат немного отличается.
print(res.json())
Результат:
{'code': 200, 'lang': 'ru-fr', 'text': ['Salut']}
Причина, по которой он отличается, заключается в том, что он больше не является простым текстом, который вы получаете из res.text. На этот раз это печатная версия словаря.
Допустим, мы хотим получить доступ к тексту. Поскольку теперь это словарь, мы можем использовать текстовый ключ.
json = res.json()
print(json['text'])
Результат:
['Salut']
Теперь мы видим только данные для этого ключа. В этом случае мы смотрим на список из одного элемента, поэтому, если мы хотим получить этот текст в списке напрямую, мы можем получить к нему доступ по индексу.
print(json['text'][0])
Результат:
Salut
Теперь единственное, что мы видим, это переведенное слово.
API Переводчика. Ошибки
Наконец, мы рассмотрим один пример ошибки в работе с API.
Попробуйте изменить ключ API, удалив один символ. Когда вы сделаете это, ваш ключ API больше не будет действительным. Затем попробуйте отправить запрос.
Если вы посмотрите на код состояния, вот что вы получите:
print(res.status_code)
Результат:
403
Используя API, важно проверять, насколько все прошло успешно, чтобы вы могли обрабатывать возможные ошибки в соответствии с потребностями вашего приложения.