Интеграция 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