Не так давно, на мероприятии 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. Мы можем указать один или несколько следующих параметров:maxNotesmaxNotebooksmaxTags
Из их названий очевидно их назначение. Если мы укажем число в
maxNotes, то получим соответствующее (или меньшее) число заметок. Аналогично это работает с блокнотами и метками. Если вы не укажете значение для того или иного параметра, то не получите результатов соответствующего типа.В нашем примере мы определили только
maxNotes. Это значит, что наш объкект класса RelatedResult, возвращаемый findRelated, не будет содержать блокноты или метки.Дополнительная информация по
RelatedResultSpec есть в справке по API.Варианты использования
Эта функция API может оказаться полезной во многих ситуациях. В Evernote мы используем
findRelated в наших веб-клипперах для браузеров, чтобы показывать пользователям заметки из их аккаунта, которые могут быть тематически связаны с просматриваемой веб-страницей. Функция также используется в “угадывании” меток и блокнотов при создании новой заметки из фрагмента веб-страницы.Например, если вы разрабатываете приложение, которое специализируется на заметках, посвященных встречам и совещаниям,
findRelated будет полезен для быстрого просмотра заметок по встречам, похожих на текущий документ. Использование findRelated будет уместно во множестве случаев, и вы сможете существенно повысить полезность своего приложения с относительно небольшими трудозатратами.Заключение
Если все прошло гладко, вы получите объект
RelatedResult, в нашем случае с 1-3 связанными заметками. Это объекты Note, так что вы можете запросить их имя, GUID, метаданные и т. д.Описание функции
findRelated можно найти в нашей документации по API.Для дополнительной информации по работе с нашим API и другой информации о разработке приложения, интегрированного с Evernote, посетите наш сайт для разработчиков. И если вы уже начали работу над таким проектом, то не забудьте принять участие в нашем конкурсе и привлечь первых пользователей с помощью премиум-подписок Evernote.
