Некоторое время назад я запустил бота для постинга в Evernote через джаббер и пообещал открыть исходный код, чтобы показать примеры работы с Evernote API и OAuth.
Код — в конце статьи, а для начала я расскажу о некоторых особенностях работы с Evernote.
Для того, чтобы использовать Evernote API, нужно отправить заявку в службу поддержки и получить consumer key. Уже здесь начинаются неожиданности — нигде об этом не написано, но ключи бывают двух видов: для клиентских приложений (с доступом по логину и паролю) и для доступа через веб-авторизацию — OAuth. В письме обязательно уточните, что именно вам нужно.
Важно: все параметры OAuth-доступа (права, срок жизни токена) задаются на стороне сервера, поэтому о них тоже лучше написать сразу. Максимальный срок жизни — 365 дней, бессрочно токены (увы) не выдаются. Права — стандартный набор create/read/update/delete плюс просмотр информации о пользователе и ее изменение.
Через некоторое время придет ответ с парой ключей (consumer key и consumer secret) для доступа на сервер-«песочницу» — sandbox.evernote.com. После того, как приложение будет готово, нужно отправить еще один запрос в саппорт — чтобы ключи работали для основного сервера, — а пока можно свободно пользоваться «песочницей» без боязни что-то сломать.
Следующая неожиданность, с которой я столкнулся — отсутствие примеров OAuth-авторизации в документации по API. Безусловно, документация есть и на oauth.net, и на других сервисах, которые используют OAuth (твиттер, например), но без привязки к конкретному сервису разобраться достаточно тяжело.
Итак, схема авторизации:
1. Запрос request token приложением
Полный url запроса выглядит так:
www.evernote.com/oauth?oauth_consumer_key=<consumer key>&oauth_signature=<consumer secret>%26&oauth_signature_method=plaintext
По этой ссылке приложению отдается токен, используемый для генерации ссылки, которую нужно будет отдать пользователю для авторизации
2. Авторизация пользователя
Пользователь должен пройти по сгенерированной ссылке и подтвердить, что он дает Вашему приложению доступ к своему аккаунту.
Ссылка, выдаваемая пользователю:
www.evernote.com/OAuth.action?oauth_callback=<callback url>&oauth_token=<полученный на первом этапе request token>
Очередная неожиданность: параметр oauth_callback (url, куда пользователь будет перенаправлен после подтверждения доступа) в спецификациях oauth указан как необязательный, но он обязателен при запросе к Evernote. Впрочем, вполне достаточно подставить туда слеш для перенаправления на главную страницу EN.
3. Запрос authorization token приложением
После того, как пользователь подтвердил доступ, приложение запрашивает постоянный токен, который позже будет использоваться для авторизации:
www.evernote.com/oauth?oauth_consumer_key=<consumer key>&oauth_signature=<consumer secret>%26&oauth_signature_method=plaintext&oauth_token=<полученный на первом этапе request token>
После этого Вы получаете authorization token и указатель для шарда (конкретного сервера Evernote), который понадобится в дальнейшем при работе с API.
В python есть библиотека для работы с OAuth, но я отказался от ее использования: не стал усложнять процесс, который сводится к генерации ссылок и обработке результатов, тем более что обычная схема OAuth выглядит сложнее, чем использованная в Evernote (вот за это разработчикам EN большое спасибо — практически всё лишнее убрали).
Из библиотек, которых нет в стандартной сборке python, для работы бота требуются sqlite3, xmpp-py и, разумеется, Evernote API (который также включает в себя thrift).
Для работы необходим python 2.6 (из-за использования «with» statements) или python 2.5 с импортом with_statements из модуля __future__.
Хабр не дал мне вставить полтысячи строк кода с хайлайтом, поэтому я выложил весь код целиком на snipt.org. Программист из меня не ахти, но зато it works. :) Пользуйтесь, хабралюди!
Код — в конце статьи, а для начала я расскажу о некоторых особенностях работы с Evernote.
Evernote
Для того, чтобы использовать Evernote API, нужно отправить заявку в службу поддержки и получить consumer key. Уже здесь начинаются неожиданности — нигде об этом не написано, но ключи бывают двух видов: для клиентских приложений (с доступом по логину и паролю) и для доступа через веб-авторизацию — OAuth. В письме обязательно уточните, что именно вам нужно.
Важно: все параметры OAuth-доступа (права, срок жизни токена) задаются на стороне сервера, поэтому о них тоже лучше написать сразу. Максимальный срок жизни — 365 дней, бессрочно токены (увы) не выдаются. Права — стандартный набор create/read/update/delete плюс просмотр информации о пользователе и ее изменение.
Через некоторое время придет ответ с парой ключей (consumer key и consumer secret) для доступа на сервер-«песочницу» — sandbox.evernote.com. После того, как приложение будет готово, нужно отправить еще один запрос в саппорт — чтобы ключи работали для основного сервера, — а пока можно свободно пользоваться «песочницей» без боязни что-то сломать.
OAuth
Следующая неожиданность, с которой я столкнулся — отсутствие примеров OAuth-авторизации в документации по API. Безусловно, документация есть и на oauth.net, и на других сервисах, которые используют OAuth (твиттер, например), но без привязки к конкретному сервису разобраться достаточно тяжело.
Итак, схема авторизации:
1. Запрос request token приложением
Полный url запроса выглядит так:
www.evernote.com/oauth?oauth_consumer_key=<consumer key>&oauth_signature=<consumer secret>%26&oauth_signature_method=plaintext
По этой ссылке приложению отдается токен, используемый для генерации ссылки, которую нужно будет отдать пользователю для авторизации
2. Авторизация пользователя
Пользователь должен пройти по сгенерированной ссылке и подтвердить, что он дает Вашему приложению доступ к своему аккаунту.
Ссылка, выдаваемая пользователю:
www.evernote.com/OAuth.action?oauth_callback=<callback url>&oauth_token=<полученный на первом этапе request token>
Очередная неожиданность: параметр oauth_callback (url, куда пользователь будет перенаправлен после подтверждения доступа) в спецификациях oauth указан как необязательный, но он обязателен при запросе к Evernote. Впрочем, вполне достаточно подставить туда слеш для перенаправления на главную страницу EN.
3. Запрос authorization token приложением
После того, как пользователь подтвердил доступ, приложение запрашивает постоянный токен, который позже будет использоваться для авторизации:
www.evernote.com/oauth?oauth_consumer_key=<consumer key>&oauth_signature=<consumer secret>%26&oauth_signature_method=plaintext&oauth_token=<полученный на первом этапе request token>
После этого Вы получаете authorization token и указатель для шарда (конкретного сервера Evernote), который понадобится в дальнейшем при работе с API.
В python есть библиотека для работы с OAuth, но я отказался от ее использования: не стал усложнять процесс, который сводится к генерации ссылок и обработке результатов, тем более что обычная схема OAuth выглядит сложнее, чем использованная в Evernote (вот за это разработчикам EN большое спасибо — практически всё лишнее убрали).
Python и библиотеки
Из библиотек, которых нет в стандартной сборке python, для работы бота требуются sqlite3, xmpp-py и, разумеется, Evernote API (который также включает в себя thrift).
Для работы необходим python 2.6 (из-за использования «with» statements) или python 2.5 с импортом with_statements из модуля __future__.
Исходный код
Хабр не дал мне вставить полтысячи строк кода с хайлайтом, поэтому я выложил весь код целиком на snipt.org. Программист из меня не ахти, но зато it works. :) Пользуйтесь, хабралюди!