Новая функциональность в Evernote API — findRelated(): поиск связанных по смыслу заметок

Не так давно, на мероприятии Evernote Trunk Conference в Сан-Франциско мы анонсировали новую функцию API NoteStore.findRelated, которую могут использовать независимые разработчики и партнеры. Как и следует из названия функции, она позволяет клиентам запрашивать заметки, блокноты и метки, так или иначе связанные по смыслу с исходными данными (такими данными на вхоже может быть как идентификатор другой заметки, так и простой текст).

Идея в том, что Evernote станет полезнее, если будет своевременно подсказывать пользователю заметки из его аккаунта на актуальную в данный момент для него тему. Новая функция API упрощает поиск и представление такой информации. Давайте посмотрим, как эта функция работает.

В Github вы можете найти пример приложения на Python, которое использует findRelated. Приведенный ниже код взят из этого приложения, так что, при желании, можете сразу перейти к нему.

Допустим, что вы уже прошли аутентификацию в Evernote Cloud API, и у вас есть заметка, которую бы вы хотели использовать в качестве исходного запроса. Тогда запрос будет реализован примерно так:

Помимо нашего токена авторизации (как токена разработчика для тестирования, так и токена, полученного через OAuth) нам понадобится создать и заполнить два объекта, которые мы будем передавать в качестве параметров в findRelated: RelatedQuery и RelatedResultSpec.

RelatedQuery

Этот класс позволяет нам указать, что именно (отдельную заметку или блок текста) мы хотим использовать в качестве исходных данных для поиска связанных заметок. В приведенном выше фрагменте мы специально указали неопределенный аргумент parameter, который может быть, как заметкой, так и строкой. При определении RelatedQuery, если у нас в качестве исходных данных выступает заметка, мы будем использовать ее GUID. Тогда в качестве первого пареметра при вызове функции (который в нашем примере так и называется — parameter) мы будем передавать объект типа Note, и укажем этот GUID как атрибут noteGuid объекта RelatedQuery. Если parameter не является заметкой, то мы считаем, что это просто строка, и присваиваем ее значение атрибуту plainText объекта RelatedQuery.

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

Дополнительная информация по RelatedQuery есть в справке по API.

RelatedResultSpec

RelatedResultSpec позволяет нам контролировать тип и число результатов, возвращаемых Evernote Cloud API при вызове findRelated. Мы можем указать один или несколько следующих параметров:

• maxNotes
• maxNotebooks
• maxTags

Из их названий очевидно их назначение. Если мы укажем число в maxNotes, то получим соответствующее (или меньшее) число заметок. Аналогично это работает с блокнотами и метками. Если вы не укажете значение для того или иного параметра, то не получите результатов соответствующего типа.

В нашем примере мы определили только maxNotes. Это значит, что наш объкект класса RelatedResult, возвращаемый findRelated, не будет содержать блокноты или метки.

Дополнительная информация по RelatedResultSpec есть в справке по API.

Варианты использования

Эта функция API может оказаться полезной во многих ситуациях. В Evernote мы используем findRelated в наших веб-клипперах для браузеров, чтобы показывать пользователям заметки из их аккаунта, которые могут быть тематически связаны с просматриваемой веб-страницей. Функция также используется в “угадывании” меток и блокнотов при создании новой заметки из фрагмента веб-страницы.

Например, если вы разрабатываете приложение, которое специализируется на заметках, посвященных встречам и совещаниям, findRelated будет полезен для быстрого просмотра заметок по встречам, похожих на текущий документ. Использование findRelated будет уместно во множестве случаев, и вы сможете существенно повысить полезность своего приложения с относительно небольшими трудозатратами.

Заключение

Если все прошло гладко, вы получите объект RelatedResult, в нашем случае с 1-3 связанными заметками. Это объекты Note, так что вы можете запросить их имя, GUID, метаданные и т. д.

Описание функции findRelated можно найти в нашей документации по API.

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