Integrating the OneNote Services API into mobile apps
Recently, Microsoft introduced for developers a new OneNote Services API, which allows you to create notes in the user's Notebook directly from your application. At the moment, the API supports the creation of records consisting of text, html, URLs and images, as well as the creation of snapshots of web pages by URL (using Bing). News360, as a partner of Microsoft, was among the first to integrate the API into all its mobile applications (iOS, Android, WinPhone and Windows 8). Integration is easy - Microsoft provides Live SDK for iOS, Android and Windows, as well as REST API for web and mobile applications.
Live SDK makes it possible to integrate OneNote at minimal cost, as it provides out-of-the-box authorization and greatly simplifies the entire process of creating records. But News360 has its own subsystem of working with external APIs, which is based on the separation of the model and presentation when interacting with the API (authorization, sharing, etc.), so integration was done through REST. But first things first.
To integrate the OneNote Services API, you must first register your application via Live Connect here .
After registration you get ClientID and Secret. If you integrate the API into a mobile application, you need to turn on the “Mobile or desktop client app” setting in the Settings section of the API.
In order for a user to create records in OneNote, he needs to log in with his Live ID.
If you use the Live SDK, the integration is much simpler. You will need ClientID and scope to allow entries. Microsoft recommends using wl.signin office.onenote_create. The Live SDK provides the entire UI required for authorization, and also provides storage of the credentials received.
For authorization through REST, Microsoft provides a standard OAuth2 Authorization code flow.
To obtain authorization code, go to WebView at:
')
The scope parameter should be “wl.signin% 20office.onenote_create”. If you plan to use long-lived tokens and the refresh-tokens mechanism, then you should also request the scope “wl.offline_access”, then along with the access token you will have a refresh token, which you can use to refresh the access token without re-authorization. In this case, the resulting scope will be “wl.signin% 20wl.offline_access% 20office.onenote_create”.
The redirect_uri parameter for mobile applications must be equal to “https://login.live.com/oauth20_desktop.srf”.
The display = touch parameter will provide a web page authorization optimized for mobile devices.
After successful authorization, WebView will follow the link:
This transition needs to be processed and an authorization code derived from it.
After that, you can hide the WebView and in any convenient way execute the query:
If everything is done correctly, then in response to this request you will get json with access token and expire date, as well as refresh token if you specify wl.offline_access in the scope.
Now access token can be used to create entries.
The lifetime of the access token is 30 minutes and should be updated for a long time. To update the access token you need to run a query
The response must be processed in the same way as the initial access token.
After successful login, you can create entries in OneNote. At the moment, the API does not support notepad selection and creates all notes in a notebook called “Quick Notes”.
Creating a record is very simple. If you want to create a simple entry that contains text and images, as News360 does, then you need to set a simple html template like:
You can also send html to body, which among other things supports the img tag.
After filling in the template, you need to run the query:
If everything is done correctly, json will come back with links to the record created:
These links can be used for deep linking and complement the user experience - a client url can be used to go to the OneNote client, if it is installed on the device, and web url to go to the web version.
Thus, the integration of the OneNote Services API presents no difficulty, even when using the REST API for authorization. I hope someone will find this article useful.
Related link:
Microsoft Office Blogs - News360 and OneNote
Live SDK makes it possible to integrate OneNote at minimal cost, as it provides out-of-the-box authorization and greatly simplifies the entire process of creating records. But News360 has its own subsystem of working with external APIs, which is based on the separation of the model and presentation when interacting with the API (authorization, sharing, etc.), so integration was done through REST. But first things first.
Application registration
To integrate the OneNote Services API, you must first register your application via Live Connect here .
After registration you get ClientID and Secret. If you integrate the API into a mobile application, you need to turn on the “Mobile or desktop client app” setting in the Settings section of the API.
Authorization in the mobile application
In order for a user to create records in OneNote, he needs to log in with his Live ID.
If you use the Live SDK, the integration is much simpler. You will need ClientID and scope to allow entries. Microsoft recommends using wl.signin office.onenote_create. The Live SDK provides the entire UI required for authorization, and also provides storage of the credentials received.
For authorization through REST, Microsoft provides a standard OAuth2 Authorization code flow.
To obtain authorization code, go to WebView at:
')
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 The scope parameter should be “wl.signin% 20office.onenote_create”. If you plan to use long-lived tokens and the refresh-tokens mechanism, then you should also request the scope “wl.offline_access”, then along with the access token you will have a refresh token, which you can use to refresh the access token without re-authorization. In this case, the resulting scope will be “wl.signin% 20wl.offline_access% 20office.onenote_create”.
The redirect_uri parameter for mobile applications must be equal to “https://login.live.com/oauth20_desktop.srf”.
The display = touch parameter will provide a web page authorization optimized for mobile devices.
After successful authorization, WebView will follow the link:
https://login.live.com/oauth20_desktop.srf?code=<your_authorization_code> This transition needs to be processed and an authorization code derived from it.
After that, you can hide the WebView and in any convenient way execute the query:
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” If everything is done correctly, then in response to this request you will get json with access token and expire date, as well as refresh token if you specify wl.offline_access in the scope.
{ "access_token" : "<your_access_token>", "expires_in" : <expires_in_seconds>, "refresh_token" : "<your_refresh_token>" } Now access token can be used to create entries.
Access token update
The lifetime of the access token is 30 minutes and should be updated for a long time. To update the access token you need to run a query
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” The response must be processed in the same way as the initial access token.
Creating entries in OneNote
After successful login, you can create entries in OneNote. At the moment, the API does not support notepad selection and creates all notes in a notebook called “Quick Notes”.
Creating a record is very simple. If you want to create a simple entry that contains text and images, as News360 does, then you need to set a simple html template like:
<html> <head> <title>Story title</title> <meta name=\"created\" content=\"<ISO8601_date_string>\" />" </head> <body> <your_story_text/html> </body> </html> You can also send html to body, which among other things supports the img tag.
After filling in the template, you need to run the query:
POST https://www.onenote.com/api/v1.0/pages Content-Type : text/html Authorization : Bearer <your_access_token> "your_html_template_with_data" If everything is done correctly, json will come back with links to the record created:
201 Created "{ "links" : { "oneNoteClientUrl" : {"href" : "onenote:https://..."}, "oneNoteWebUrl" : {"href" : "https://..."} } }" These links can be used for deep linking and complement the user experience - a client url can be used to go to the OneNote client, if it is installed on the device, and web url to go to the web version.
Thus, the integration of the OneNote Services API presents no difficulty, even when using the REST API for authorization. I hope someone will find this article useful.
Related link:
Microsoft Office Blogs - News360 and OneNote
Source: https://habr.com/ru/post/220169/
All Articles