[Из песочницы] Интеграция OneNote Services API в мобильные приложения
Недавно Microsoft представила для разработчиков новый OneNote Services API, который позволяет создавать записи в Notebook'е пользователя напрямую из Вашего приложения. На данный момент API поддерживает создание записей, состоящих из текста, html, URL'ов и изображений, а также создание snapshot'ов web-страниц по URL (при помощи Bing). News360, как партнер Microsoft, в числе первых интегрировали API во все свои мобильные приложения (iOS, Android, WinPhone и Windows 8). Интеграция не составляет труда — Microsoft предоставляет Live SDK для iOS, Android и WIndows, а также REST API для web и мобильных приложений.Live SDK поволяет интегрировать OneNote с минимальными затратами, так как предоставляет авторизацию «из коробки» и значительно упрощает весь процесс создания записей. Но News360 имеет свою подсистему работы с внешними API, которая основана на разделении модели и представления при взаимодействии с API (авторизация, шаринг и т.п.), поэтому интеграция производилась через REST. Но обо всем по порядку.Регистрация приложения Для интеграции OneNote Services API первым делом необходимо зарегистрировать приложение через Live Connect здесь.После регистрации вы получаете ClientID и Secret. Если вы интегрируете API в мобильное приложение, нужно обязательно включить настройку «Mobile or desktop client app» в разделе API Settings.Авторизация в мобильном приложении Для того, чтобы пользователь мог создавать записи в OneNote, ему необходимо авторизоваться с его Live ID.Если вы используете Live SDK, то интеграция значительно упрощается. Вам понадобится ClientID и scope, позволяющий создавать записи. Microsoft рекомендует использовать “wl.signin office.onenote_create”. Live SDK предоставляет весь UI, необходимый для авторизации, а также обеспечивает хранение полученных credential’ов.Для авторизации через REST Microsoft предоставляет стандартный OAuth2 Authorization code flow.Для получения authorization code необходимо перейти в WebView по адресу: GET https://login.live.com/oauth20_authorize.srf?client_id=<your_client_id>&scope=<your_scopes>@&response_type=code&redirect_uri=https://login.live.com/oauth20_desktop.srf&display=touch Параметр scope должен быть “wl.signin%20office.onenote_create”. Если вы планиуете использовать долгоживущие токены и механизм refresh-токенов, то необходимо также запросить scope “wl.offline_access”, тогда вместе с access token’ом Вам придет refresh token, который можно использовать для обновления access token’а без повторной авторизации. В этом случае результирующий scope будет “wl.signin%20wl.offline_access%20office.onenote_create”.Параметр redirect_uri для мобильных приложений обязательно должен быть равен “https://login.live.com/oauth20_desktop.srf”.Параметр display=touch обеспечит web-страницу авторизации, оптимизированную для мобильных устройств.После успешной авторизции WebView перейдет по ссылке:
https://login.live.com/oauth20_desktop.srf?code=<your_authorization_code> Этот переход необходимо обработать и получить из него authorization code.После этого можно скрыть WebView и любым удобным способом выполнить запрос: POST https://login.live.com/oauth20_token.srf
“client_id=<your_clint_id>&client_secret=<your_secret>&redirect_uri=https://login.live.com/oauth20_desktop.srf&code=<your_authorization_code>&grant_type=authorization_code” Если все сделано правильно, то в ответ на этот запрос Вы получите json с access token’ом и expire date, а также refresh token, если Вы указали в scope’е wl.offline_access. { "access_token" : "<your_access_token>", "expires_in" : <expires_in_seconds>, "refresh_token" : "<your_refresh_token>" } Теперь access token может быть использован для создания записей.Обновление access token'а Срок жизни access token составляет 30 минут и при длительном использовании его необходимо обновлять. Чтобы обновить access token нужно выполнить запрос POST https://login.live.com/oauth20_token.srf
“client_id=<your_clint_id>&client_secret=<your_secret>&redirect_uri=https://login.live.com/oauth20_desktop.srf&refresh_token=<your_refresh_token>&grant_type=refresh_token” Ответ нужно обработать аналогично первоначальному получению access token'а.Создание записей в OneNote После успешной авторизации Вы можете создавать записи в OneNote. На данный момент API не поддерживает выбор блокнота и создает все записи в блокноте под названием “Quick Notes”.Создание записи происходит очень просто. Если вы хотите создать простую запись, содержащую текст и изображения, как это делает News360, то нужно задать простой html-шаблон вида: <html> <head> <title>Story title</title> <meta name=\"created\" content=\"<ISO8601_date_string>\" />" </head> <body> <your_story_text/html> </body> </html> В body можно также передавать html, который помимо всего прочего поддерживает тэг img.После заполнения шаблона нужно выполнить запрос:
POST https://www.onenote.com/api/v1.0/pages
Content-Type : text/html Authorization : Bearer <your_access_token>
"your_html_template_with_data" Если все сделано правильно, в ответ придет json со ссылками на созданную запись: 201 Created
"{ "links" : { "oneNoteClientUrl" : {"href" : "onenote:https://..."}, "oneNoteWebUrl" : {"href" : "https://..."} } }" Данные ссылки могут использоваться для deep linking’а и дополнить пользовательский experience — сlient url может использоваться для перехода в клиент OneNote, если он установлен на устройстве, а web url — для перехода в web-версию.Таким образом, интеграция OneNote Services API не представляет никаких трудностей, даже при использовании REST API для авторизации. Надеюсь, кому-нибудь пригодится эта статья.
Ссылка по теме:Microsoft Office Blogs — News360 and OneNote
