Partilhar via

And SharePoint makes three!

  • Artigo

The OneNote team is happy to announce support for SharePoint site-hosted notebooks (in Preview). This means you can access all your notebooks on the Microsoft cloud! This includes:

  • OneDrive-hosted personal notebooks
  • OneDrive for Business-hosted notebooks on Office 365 (also in Preview)
  • OneDrive for Business-hosted notebooks on SharePoint

Last month, we described our support for enterprise notebooks on Office 365 (new service root URL, auth model, permissions, app registration, etc.). All that pretty much applies to SharePoint site-hosted notebooks, too. The main difference for accessing OneNote content on SharePoint is the service root URL.

Service root URL

This is the pattern you use to access OneNote content on SharePoint sites:

https://www.onenote.com/api/{version}/myorganization/siteCollections/{id}/sites/{id}/notes/

The myorganization segment in the path represents the tenant that the user is logged into. (Currently, that's the only supported tenant.) Everything that comes after /notes is basically the same across services. For example, this example request gets the 10 most recently modified pages from the notebooks on the site that you have permissions to access:

https://www.onenote.com/api/beta/myorganization/siteCollections/09d1a587-a84b-4264-3d15-669429be8cc5/sites/d9e4d5c8-683f-4364-89ae-18c4e3db91e9/notes/pages?top=10

Get the site collection and site IDs

We added the FromUrl method so you can pass in an absolute site URL and get the site collection and site IDs. You should make this call only when needed, and then store the values for future use in your requests to the OneNote API. The site URL depends on your config, for example https://domain.sharepoint.com/site-a or https://domain.com/sites/site-a.

GET https://www.onenote.com/api/beta/myorganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')
Authorization: Bearer {access-token}
Accept: application/json

Here's an example response:

{
    "@odata.context":"https://www.onenote.com/api/beta/$metadata#Microsoft.OneNote.Api.SiteMetadata",
    "siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5",
    "siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"
}

Parity with consumer APIs

All currently supported HTTP operations have equivalent support for enterprise notebooks, with a few exceptions. For example:

  • POST ~/notes/pages is currently not supported. To create a page, you have to include the section ID: ~/me/notes/sections/{id}/pages. Using the ?sectionName parameter to create a page is not supported yet either.
  • The $search query option is currently not supported.

You can see our supported HTTP operations here, but note that the docs and interactive calls currently target consumer notebooks on OneDrive only.

There's a couple other things you might run into when working with notebooks on SharePoint:

  • You can only create OneNote notebooks, sections, and pages on sites that have a default document library. (Some site templates don't create a default document library.) However, GET requests return OneNote content from all document libraries on the site.
  • The OneNote service root URL is immutable, meaning you can't use a SharePoint REST API site path and then tack the /notes endpoint onto it.

And the rest...

Authentication and authorization

The auth model is the same as Office 365. Learn more about Office 365 authentication and authorization.

App registration and permission scopes

You'll specify permissions for your apps when you register an application on Azure AD. The registration process and permission scopes for enterprise notebooks are described in this post. You'll need the Notes.Read.All or Notes.ReadWrite.All scope to access SharePoint site-hosted notebooks. In the future, we'll also add support for finding notebooks that are shared with you.

Keep in touch

As always, we'd love to hear what you think about the OneNote APIs and our enterprise notebook support on UserVoice. You can also contact us on twitter @onenotedev, or ask a question tagged onenote on Stack Overflow.

 

Edit 11/10/2015: Added guidance to use the Notes.Read.All and Notes.ReadWrite.All scopes to access SharePoint site-hosted notebooks.

Comments

  • Anonymous
    June 14, 2015
    Information was good, I like your post. Looking forward for more on this topic. <a href="staygreenacademy.com/">SharePoint 2013 Online Videos</a>

  • Anonymous
    June 22, 2015
    When will be OneNote support SharePoint on Premises (team sites and My sites). There is no app setting to specify a server. This is a very poor implementation.

  • Anonymous
    June 22, 2015
    Dan, we currently have no plans to support on-premises SharePoint servers via the OneNote API.  You can add this as a feature request on UserVoice at onenote.uservoice.com/.../245490-onenote-apis to see if there is broad demand for this.

  • Anonymous
    July 06, 2015
    Not the original person, but I too would really like support for On-Premises SharePoint. I've created a request on UserVoice (onenote.uservoice.com/.../8744506-api-support-for-on-premises-sharepoint). If anyone else is in the same boat, please vote for this request! Thanks again to the OneNote Team! The API looks awesome, I just wish I could use it.

  • Anonymous
    October 05, 2015
    Hi! I am trying to testing this endpoint with the following url according to your sample www.onenote.com/.../pages I have replaced "myorganization" with my tenant name (i.e. mytenant if my tenant is mytenant.sharepoint.com). replaced the site id and web id with the correct ones. But I am getting an error message telling me "No HTTP resource was found that matches the request URI" The exact same code works fine when changing the URL to use "www.onenote.com/.../notebooks" Any hints on what is wrong?

  • Anonymous
    October 09, 2015
    The comment has been removed

  • Anonymous
    October 09, 2015
    Ignore the above comment that was due to a typo.... but the real reason behind my problem was myorganization/sitecollections/FromUrl(url='" + SharePointURL + "')" I was pulling the top level site and not the subside. All is find now, enjoying the blogs.

  • Anonymous
    October 12, 2015
    @Henrick, The "myorganization" keyword in the URL is not meant to be replaced. It represents the current tenant (which is currently the only tenant that's supported). Does that work for you for your /pages and /notebooks requests? @Rick, Glad to hear you got it working. Thanks!

  • Anonymous
    October 16, 2015
    When I use the accessToken from the AzureAD registered app to access the following URL www.onenote.com/.../FromUrl(url='https://*****.sharepoint.com/sites/<site-relativeurl>" I am always getting a 401. Any idea what is going wrong?

  • Anonymous
    October 20, 2015
    Vishnu, can you please post your question on StackOverflow? (stackoverflow.com/.../onenote)

  • Anonymous
    November 18, 2015
    User voice about OneNote supporting Sharpoint on Premises has been closed. onenote.uservoice.com/.../8744506-api-support-for-on-premises-sharepoint

  • Anonymous
    March 08, 2016
    The lack of support for OnPrem SharePoint is an application killer for us. We've been heavily invested in OneNote. We have 3000 users in an OnPrem SharePoint environment, and the silence and seeming lack of interest from MS on this issue, is making us re-evaluate whether OneNote is a viable option for us.

  • Anonymous
    June 19, 2016
    Can I share notebook{In Sharepoint} with specific people through OneNote api at the time of creating of that notebook.OrCan I get editable link of OneNote page at the time of creating onenote page.