Поделиться через

Проверка подлинности и разрешения OneNote

  • Статья

Область применения: пользовательские записные книжки в OneDrive и корпоративные записные книжки в Office 365

OneNote использует учетную запись Microsoft (ранее Live Connect) и Azure Active Directory для обеспечения безопасного доступа к записным книжкам OneNote. Прежде чем вы сможете получить доступ к записным книжкам, сначала необходимо выполнить проверку подлинности с помощью учетной записи Microsoft или Azure AD и получить маркер доступа.

Учетная запись Microsoft используется для доступа к пользовательским записным книжкам OneDrive, а Azure AD используется для доступа к корпоративным записным книжкам в Office 365.

Обе службы авторизации реализуют протокол OAuth 2.0 для предоставления маркеров доступа, которые необходимы для взаимодействия с OneNote. Все запросы к API OneNote должны включать допустимый маркер доступа в заголовке Authorization.

В этой статье описываются процессы, связанные с авторизацией, за которые вы отвечаете: регистрация вашего приложения для получения идентификатора клиента; указание необходимых разрешений; вызов службы авторизации для входа пользователей в систему и получения маркера доступа.

В зависимости от вашей платформы вы можете использовать SDK для упрощения потоков авторизации.

Примечание

OneNote в конечном итоге поддержит единую модель проверки подлинности и регистрацию приложений, предоставляемую моделью приложения v2.0. Следите за соответствующими обновлениями в Блоге разработчика OneNote.

Попробуйте API

Выполните шаги, описанные в этой статье, чтобы получить маркер доступа, используя предпочитаемый вами сетевой инструмент, например, Fiddler.

Проверка подлинности с использованием учетной записи Microsoft (пользовательские приложения)

  1. Регистрация приложения и получение идентификатора клиента и секрета
  2. Выберите разрешения OneNote
  3. Войдите в систему и получите маркер доступа
  4. Получите новый маркер доступа после истечения его срока действия

Регистрация приложения и получение идентификатора клиента и секрета (пользовательские приложения)

Для начала вам необходимо зарегистрировать приложение в Microsoft. Этот процесс создает субъект-службу, к которой вы подключаетесь из вашего приложения, и генерирует идентификатор клиента и секрет, который вы отправляете в службу авторизации.

Сделайте это, если ваше приложение обращается только к пользовательским записным книжкам, или если оно обращается как к пользовательским, так и к корпоративным записным книжкам.

  1. Войдите в Центр разработки учетных записей Microsoft с вашей учетной записью Microsoft. (Если вы разрабатываете приложение для Windows Store, сделайте это).

    Если у вас нет учетной записи Microsoft, вам нужно будет создать ее. Используйте адрес электронной почты, который вы регулярно проверяете. Мы можем попытаться связаться с вами, чтобы выделить ваше приложение в наших Избранных приложениях, или если мы заметим неожиданный сетевой трафик, поступающий из вашего приложения. Мы не будем отправлять вам нежелательную почту или продавать ваши данные.

  2. Выберите Создать приложение.

  3. Введите имя, которое будет отображаться пользователям, когда им будет предложено предоставить разрешения для вашего приложения, и выберите основной язык для своего приложения.

  4. Чтобы принять условия использования, а также политики конфиденциальности и использования файлов cookie, нажмите кнопку Принимаю для продолжения регистрации.

  5. На странице «Параметры API» выберите тип вашего приложения и укажите информацию о своем приложении:

    Веб-приложения (серверные приложения)

    А. Выберите Нет для Мобильное или настольное клиентское приложение.

    Б. Для целевого домена введите URL-адрес службы.

    В. Введите URL-адрес переадресации, куда вы хотите перенаправлять пользователей после того, как они прошли проверку подлинности и им был предоставлен доступ к вашему приложению.

    Собственные приложения (установленные на устройстве)

    А. ** Выберите Нет ** для Мобильное или настольное клиентское приложение.****

    Б. (Необязательно) Для целевого домена введите URL-адрес мобильной службы.

    В. (Необязательно) Для URL-адреса переадресации введите допустимый URL-адрес. Он действует как идентификатор вашего приложения и не обязательно является физической конечной точкой.*

  6. Сохраните идентификатор клиента и секрет клиента, указанный на странице настроек приложения, и URL-адрес перенаправления, если вы предоставляли его.

Приложения Магазина Windows

Если вы создаете приложение Windows, вместо этого зарегистрируйте свое приложение в Центре разработки Windows. Это предоставит вам идентификатор пакета (SID пакета), который вы будете использовать вместо идентификатора клиента.

  1. Войдите в Центр разработки Windows под вашей учетной записью Microsoft.

  2. На панели инструментов выберите Создать новое приложение и введите имя своего приложения.

  3. В Visual Studio щелкните правой кнопкой мыши проект приложения Windows Store и выберите Магазин> Связать приложение с магазином.

  4. В окне «Сопоставить ваше приложение с Магазином Windows» войдите в свою учетную запись Microsoft, выберите свое приложение, а затем выберите Далее> Сопоставить. Это добавит требуемую регистрационную информацию Магазина Windows в манифест приложения.

  5. Для универсального приложения Windows повторите предыдущие два этапа проекта Windows Phone.

Выберите области разрешений OneNote (пользовательские приложения)

Области разрешений представляют уровни доступа к содержимому OneNote. Вы запрашиваете разрешения, которые требуется вашему приложению, и пользователи предоставляют доступ или отклоняют его при входе в ваше приложение. Пользователи могут предоставлять только разрешения, которые у них есть.

Выберите самый низкий уровень разрешений, необходимый вашему приложению для работы. Вы можете сделать запрос для нескольких областей.

Область (объект-получатель) Описание
office.onenote_create Можно просматривать список записных книжек OneNote пользователя и создавать новые страницы, но не просматривать или редактировать существующие страницы.
Можно перечислить иерархию записной книжки пользователя и создать страницы в любом расположении.
office.onenote_update_by_app Разрешение на создание, просмотр и изменение всех страниц, созданных приложением.
office.onenote_update Можно создавать, просматривать и изменять любое содержимое в записных книжках и страницах OneNote.
office.onenote Можно просматривать записные книжки и страницы OneNote, но не изменять их.
wl.signin Область разрешения учетной записи Microsoft.
Позволяет вашему приложению использовать возможности единого входа.
wl.offline_access Область разрешения учетной записи Microsoft.
Позволяет вашему приложению получать маркер обновления, чтобы оно могло работать не в сети, даже если пользователь неактивен. Эта область недоступна для потока маркеров.

Для разрешений, используемых для доступа к записным книжкам Office 365, см. Выбор разрешений OneNote (корпоративные приложения).

Войдите в систему и получите маркер доступа (пользовательские приложения)

Приложение инициирует процесс входа в систему, обратившись в службу авторизации. Если пользователи еще не вошли или уже не дали согласие, служба попросит их предоставить учетные данные и согласиться с разрешениями, запрошенными вашим приложением. Если проверка подлинности и авторизация успешны, вы получите маркер доступа, который вы включите в свои запросы к API OneNote.

Важно!

Обращайтесь с маркерами доступа и обновления так же надежно, как и с паролем пользователя.

Примечание

В зависимости от вашей платформы вы можете использовать SDK для упрощения потоков авторизации.

Выберите поток проверки подлинности. Оба являются стандартными потоками OAuth 2.0.

Поток Описание
Поток маркеров

Получает маркер доступа за один вызов. Полезно для быстрого доступа, но не предоставляет маркер обновления для долгосрочного доступа.

Также называется неявный поток.
Поток кода

Получает код авторизации при первом вызове и обменивается кодом для маркера доступа при втором вызове. При использовании с областью применения wl.offline-access ваше приложение получает маркер обновления, который обеспечивает долгосрочный доступ.

Также называется потоккода авторизации.

Подключить пользователей к потоку маркера

Загрузите следующий URL-запрос в веб-обозревателе или в элементе управления веб-обозревателя.

GET https://login.live.com/oauth20_authorize.srf
  ?response_type=token
  &client_id={client_id}
  &redirect_uri={redirect_uri}
  &scope={scope}
Обязательный параметр строки запроса Описание
response_type Тип используемого вами потока проверки подлинности. В этом случае маркер.
client_id Идентификатор клиента, созданный для приложения.
redirect_uri URL-адрес перенаправления, который вы зарегистрировали для своего приложения. Мобильные и настольные приложения, которые не указали его, могут использовать следующее: https://login.live.com/oauth20_desktop.srf
scope Области, которые требуется вашему приложению.
Пример: office.onenote% 20wl.sign в

После успешной проверки подлинности и авторизации веб-обозреватель перенаправляет на URL-адрес перенаправления и добавляет параметры доступа к URL-адресу. Параметры включают access_token иtoken_type, как показано в следующем примере. Маркер доступа действует в течение времени, указанного в свойстве expires_in (в секундах).

https://your-redirect-url
  #access_token=EwB4Aq...%3d
  &token_type=bearer
  &expires_in=3600
  &scope=office.onenote wl.signin
  &user_id=c519ea026ece84de362cfa77dc0f2348

Вход пользователей в систему с помощью потока кода

Получение маркера доступа - это процесс с потоком кода, состоящий из двух шагов:

  1. Вход пользователя в систему и получение кода авторизации.
  2. Обмен кода на маркер доступа

Этап 1. Вход пользователя в систему и получение кода авторизации. Чтобы запустить процесс регистрации, загрузите следующий URL-запрос в веб-обозревателе или в элементе управления веб-обозревателя

https://login.live.com/oauth20_authorize.srf
  ?response_type=code
  &client_id={client-id}
  &redirect_uri={redirect-uri}
  &scope={scope}
Обязательный параметр строки запроса Описание
response_type Тип используемого вами потока проверки подлинности. В этом случае код.
client_id Идентификатор клиента, созданный для приложения.
redirect_uri URL-адрес перенаправления, который вы зарегистрировали для своего приложения. Мобильные и настольные приложения, которые не указали его, могут использовать следующее: https://login.live.com/oauth20_desktop.srf
scope Области, которые требуется вашему приложению.
Пример: office.onenote wl.signin wl.offline_access

После успешной проверки подлинности и авторизации веб-обозреватель перенаправляет URL-адрес перенаправления с помощью параметра code, добавленного к URL-адресу, как показано в следующем примере. Скопируйте значение code для использования в шаге 2. Этот код действителен в течение нескольких минут.

https://your-redirect-uri
  ?code=M57010781-9e8c-e31e-ca0d-46bc104236c4

Этап 2. Замените код авторизации для маркера доступа и обновите маркер. Отправьте следующий HTTP-запрос с правильно закодированной строкой URL-адреса в тексте сообщения.

POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&code={code}
&redirect_uri={redirect-uri}
Обязательный параметр текста сообщения Описание
grant_type Тип предоставления запроса. В этом случае authorization_code.
client_id Идентификатор клиента, созданный для приложения.
client_secret Секрет клиента, созданный для вашего приложения.
code Код, который вы получили как параметр URL на предыдущем шаге.
redirect_uri URL-адрес перенаправления для вашего приложения. Он должен соответствовать redirect_uri первого запроса.

В случае успешного выполнения ответ содержит строку JSON, которая включает в себя access_ token — и refresh_ token, если вы запросили область wl.offline_access — как показано в следующем примере. Маркер доступа действует в течение времени, указанного в свойстве expires_in (в секундах).

{
  "token_type":"bearer",
  "expires_in":3600,
  "scope":"office.onenote wl.sign-in wl.offline-access",
  "access_token":"EwCAAq...wE=",
  "refresh_token":"MCvePE...$$",
  "user_id":"c519ea026ece84de362cfa77dc0f2348"
}

Включите маркер доступа в свой запрос к API OneNote

Все ваши запросы к API OneNote должны отправлять маркер доступа в качестве маркера носителя в заголовке Authorization. Например, следующий запрос получает пять ваших записных книжек, отсортированных в алфавитном порядке по имени:

GET https://www.onenote.com/api/v1.0/me/notes/notebooks?top=5
Authorization: Bearer {access-token}

Маркеры доступа действительны в течение только одного часа, поэтому вам нужно будет получить новые маркеры, когда срок предыдущих истечет. Вам нужно проверить срок действия маркера перед его использованием и получить новый при необходимости. Пользователи могут оставаться вошедшими в систему, и они не должны снова соглашаться на разрешения, если они не выходят или не отменяют разрешения.

Получение нового маркера доступа после истечения его срока действия (пользовательские приложения)

Вы можете запросить новый маркер доступа, используя маркер обновления, либо повторив процесс авторизации с самого начала.

Если срок действия маркера доступа истек, запросы к API будут возвращать ответ 401 Unauthorized. Ваше приложение должно обработать этот ответ и проверить срок действия маркера перед отправкой запросов.

Отправьте следующий HTTP-запрос с правильно закодированной строкой URL-адреса в тексте сообщения.

Вы получили маркер обновления, если вы запросили разрешение wl.offline_access и использовали поток кода.

POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}
Обязательный параметр текста сообщения Описание
grant_type Тип предоставления запроса. В этом случае refresh_token.
client_id Идентификатор клиента, созданный для приложения.
client_secret Секрет клиента, созданный для вашего приложения.
redirect_uri URL-адрес перенаправления для вашего приложения. Он должен соответствовать redirect_uri, который вы использовали для получения маркеров.
refresh_token Маркер обновления, полученный ранее.

В случае успешного выполнения ответ на запрос POST содержит строку JSON, которая включает в себя access_ token и refresh_token, как показано в следующем примере.

{
  "token_type":"bearer",
  "expires_in": 3600,
  "scope":"office.onenote wl.sign-in wl.offline-access",
  "access_token":"EwB4Aq...wE=",
  "refresh_token":"MCVw8k...$$",
  "user_id":"c519ea026ece84de362cfa77dc0f2348"
}

Обновите сохраненные маркеры, чтобы убедиться, что у вашего приложения есть маркеры с максимальным сроком действия.

Выход пользователей из системы (пользовательские приложения)

Чтобы выполнить выход для пользователя, выполните указанные ниже действия.

  1. Удалите все кэшированные маркеры доступа или маркеры обновления, которые вы получили или сохранили.

  2. Выполните необходимые действия по выходу из системы в своем приложении (например, очистку локального состояния, удаление всех элементов из кэша и т. д.).

  3. Отправьте вызов в веб-службу авторизации, используя следующий URL-адрес:

https://login.live.com/oauth20_logout.srf
  ?client_id={client_id}
  &redirect_uri={redirect_uri}

Этот вызов удаляет все файлы cookie, которые позволяют осуществлять единый вход, и гарантирует, что пользователю будет предложено войти в систему.

Обязательный параметр строки запроса Описание
client_id Идентификатор клиента, созданный для приложения.
redirect_uri URL-адрес перенаправления для вашего приложения. Он должен соответствовать redirect_uri, который вы использовали для получения маркеров.

После удаления файлов cookie веб-обозреватель перенаправляет ваш URL-адрес перенаправления. Страница перенаправления загружается без указания параметров строки запроса проверки подлинности, что означает, что пользователь вышел из системы.

Отмена доступа

Пользователь может отменить доступ приложения к своей учетной записи на странице Управление учетной записью Майкрософт.

При отмене согласия для приложения все маркеры обновления, ранее предоставленные ему, становятся недействительными. При попытке обновить маркер вы получите следующий ответ:

{
  "error":"invalid_grant",
  "error_description":"The request was denied because one or more scopes requested are unauthorized or expired. The user must first sign in and grant the client application access to the requested scope."
}

Вам нужно будет повторить поток авторизации для запроса нового доступа и обновления маркера с самого начала.

Проверка подлинности с использованием Azure AD (корпоративные приложения)

Если ваше приложение использует разрешения приложений (а не разрешения делегата), см. раздел Разрешения проверки подлинности OneNote и приложения Azure AD.

  1. Регистрация приложения и получение идентификатора клиента и секрета
  2. Выберите разрешения OneNote
  3. Войдите в систему и получите маркер доступа
  4. Получите новый маркер доступа после истечения его срока действия

Зарегистрируйте ваше приложение и получите идентификатор клиента и секрет (корпоративные приложения)

Для начала вам необходимо зарегистрировать приложение в Microsoft. Этот процесс создает субъект-службу, к которой вы подключаетесь из вашего приложения, и генерирует идентификатор клиента и секрет, который вы отправляете в службу авторизации.

Сделайте это, если ваше приложение обращается только к пользовательским записным книжкам, или если оно обращается как к пользовательским, так и к корпоративным записным книжкам.

Чтобы зарегистрировать свое приложение у клиента Azure AD, связанного с подпиской Office 365, вам необходимо:

  • Получить учетную запись Office 365 с разрешениями глобального администратора для клиента Office 365

    Вы можете попробовать или купить подписку на Office 365 для разработчиков или подписку на квалификационный план.

  • Подготовка OneDrive для бизнеса для вашего клиента

    Делает приложение OneNote доступным, чтобы вы могли указать разрешения OneNote. Чтобы проверить, предоставлен ли OneDrive для бизнеса, войдите в OneNote Online с вашими полномочиями Office 365 (рабочая или учебная учетная запись, например, someone@example.com или someone@example.onmicrosoft.com).

    Если вы видите свои записные книжки, все готово. Если вы видите «Извините, мы не можем получить ваши записные книжки...», выберите Перейти в мою учетную запись > Далее. Когда ваша страница OneDrive для бизнеса загружается, вернитесь и обновите OneNote Online, чтобы завершить подготовку.

    Примечание

    Прежде чем вы сможете получить доступ к своим записным книжкам, необходимо подготовить персональные сайты ваших пользователей. API OneNote попытается провести автоматическую проверку их сайтов, если это необходимо.

  • Свяжите подписку на Office 365 с подпиской Azure

    Это позволит вам регистрировать ваше приложение и управлять им в Azure AD. (узнайте больше)

    Если у вас нет подписки Azure, выполните Вариант 1 в следующем разделе. Если у вас она есть, выполните Вариант 2.

Важно!

Вы и ваши пользователи должны иметь учетную запись Office 365 с действующей лицензией Office 365. Учетные записи пользователей без действительных лицензий не смогут увидеть записные книжки в OneNote Online, а вызовы API для их записных книжек не будут выполнены. Администраторы Office 365 могут проверить состояние и присвоить неназначенные лицензии.

Примечание

Подписчики MSDN: вы сможете иметь право на бесплатную подписку на Разработчик Office 365, а также добавлять сэкономленные средства при активации вашего преимущества Azure. Проверьте свои преимущества на Странице подписки MSDN.

Свяжите свою подписку Azure с подпиской на Office 365

Вариант 1: Подпишитесь на подписку Azure, используя учетные данные администратора для подписки на Office 365. Сделайте это, если у вас нет подписки Azure. Этот процесс связывает подписки.

  1. Войдите на Портал управления Azure, используя учетные данные администратора Office 365 (рабочая или учебная учетная запись, например, someone@example.com или someone@example.onmicrosoft.com).

  2. На странице «Подписок не найдено» выберите Подписаться на Microsoft Azure. Загрузится страница регистрации, отображая некоторую информацию из вашей подписки Office 365. Эта учетная запись станет администратором службы для новой подписки Azure.

Опыт регистрации зависит от того, есть ли у вас пробная или платная подписка на Office 365:

  • Если у вас есть пробная подписка, введите информацию о платежах на странице «Бесплатная пробная версия». С вашего счета не взимается плата, если вы не решите перейти на оплаченную подписку.

    Если вы согласны с соглашением о подписке, сведениями предложения и заявлением о конфиденциальности, установите флажок и выберите Купить. Откроется страница Подписки для вашей новой учетной записи Azure. Пробные подписки выдаются на сумму 200 долларов США, которые могут быть использованы в течение 30 дней. Вы можете отменить подписку с этой страницы в любое время.

  • Если у вас есть платная подписка, заполните контактную информацию, а затем выберите Подписаться. После создания подписки выберите Начать управлять моим сервисом для открытия портала управления Azure.

Вариант 2: Свяжите существующую подписку Azure с подпиской Office 365. Выберите этот вариант, если у вас есть учетная запись Microsoft, которая является администратором службы или со-администратором для вашей подписки Azure. Этот процесс делает учетную запись Microsoft глобальным администратором клиента Office 365.

  1. Войдите в Портал управления Azure с учетными данными вашей учетной записи Microsoft (например, someone@live.com).

  2. В панели в нижней части страницы выберите Новые приложения> Службы приложений> Active Directory> Справочник> Настраиваемый.

  3. В окне «Добавить справочник» выберите Использовать существующий справочник для справочника.

  4. Выберите Я готов выйти из системы сейчас и нажмите галочку. Это выведет вас из портала.

  5. Войдите в систему с использованием глобальных учетных данных администратора для клиента Office 365, который вы хотите связать (рабочая или учебная учетная запись, например, someone@example.com или someone@example.onmicrosoft.com).

  6. Когда вас спросят, следует ли использовать справочник с Azure, выберите продолжить> Выйти сейчас.

  7. Закройте веб-обозреватель, а затем снова откройте Портал управления Azure.

  8. Войдите снова с учетными данными учетной записи Microsoft и выберите Active Directory в навигационной панели. Справочник Office 365 должен быть указан на вкладке «Справочник».

Регистрация приложения на портале управления Azure

  1. Войдите в портал управления Azure. Используйте учетные данные администратора для подписки на Azure.

  2. В навигационной панели выберите Active Directory.

  3. Выберите справочник, в котором вы хотите зарегистрировать свое приложение, а затем откройте вкладку «Приложения».

  4. В панели в нижней части страницы выберите Добавить> Добавить приложение, которое разрабатывает моя организация.

  5. Введите понятное имя для приложения и выберите тип приложения:

    Веб-приложение или веб-API (приложения для обозревателя или серверные приложения)

    А. Выберите Веб-приложение и/или веб-API.

    Б. Для URL входа в систему введите URL-адрес, под которым пользователи входят и используют ваше приложение.

    В. Для URI идентификатора приложения введите уникальный идентификатор для своего приложения. Это должно быть в проверенном пользовательском домене.

    Г. Для URL-адреса ответа введите URL-адрес для переадресации в ответ на запрос OAuth 2.0. Это не должно быть физической конечной точкой, но это должен быть допустимый URI.

    Д. Чтобы сделать приложение доступным для внешних клиентов Azure, выберите Да для Приложение является многопользовательским.

    Собственное клиентское приложение (приложения, установленные на устройстве)

    А. Выберите Собственное клиентское приложение.

    Б. Введите URI перенаправления для перенаправления в ответ на запрос OAuth 2.0. Это не должно быть физической конечной точкой, но это должен быть допустимый URI.

Для веб-приложений Azure генерирует и идентификатор клиента, и секрет приложения (или ключ). Для собственных приложений Azure генерирует только идентификатор клиента. Сохраните эти значения.

См. Документация Office 365 для получения подробных инструкций по регистрации приложений.

Выбор области разрешений приложения OneNote (корпоративные приложения)

Области разрешений представляют уровни доступа к содержимому OneNote. Вы запрашиваете разрешения, которые требуется вашему приложению, и пользователи предоставляют доступ или отклоняют его при входе в ваше приложение. Пользователи могут предоставлять только разрешения, которые у них есть.

  1. На Портале управления Azure в разделе Разрешения для других приложений страницы настройки приложения выберите Добавить приложение.

  2. Выберите приложение OneNote, а затем установите флажок в правом нижнем углу. Если OneNote отсутствует в списке, убедитесь, что вы указали OneDrive для бизнеса в качестве клиента.

  3. Выберите самый низкий уровень разрешений, которые необходимы вашему приложению для функционирования, и сохраните изменения. Вы можете сделать запрос для нескольких областей.

Области для персональных записных книжек, принадлежащих текущему пользователю

Если вы работаете только с персональными записными книжками OneDrive для бизнеса, выберите их из следующих областей.

Область (корпоративная) Разрешение на портале Azure Описание
Notes.Create Создание страниц в записных книжках OneNote

Пользователь может просматривать заголовки записных книжек и разделов; создавать страницы в любом месте.

Пользовате просматривать или редактировать существующие страницы.
Notes.ReadWrite.CreatedByApp Доступ к записной книжке OneNote только в приложении

Пользователь может просматривать заголовки записных книжек и разделов; создавать страницы; переименовывать разделы; просматривать и изменять страницы, созданные приложением.

Пользователь не может просматривать и изменять страницы, созданные другими приложениями, или страницы в разделах, защищенных паролем.
Notes.Read Просмотр записных книжек OneNote

Пользователь может просматривать содержимое ваших записных книжек и разделов.

Пользователь не может создавать новые страницы, изменять существующие страницы или получать доступ к разделам, защищенным паролем.
Notes.ReadWrite Просмотр и изменение записных книжек OneNote

Пользователь может просматривать заголовки записных книжек и разделов; просматривать и изменять все страницы; создавать страницы; переименовывать разделы.

Пользователь не может получать доступ к разделам, защищенным паролем.

Области для сайтов и групповых записных книжек, к которым может обратиться текущий пользователь

Если вы работаете с записными книжками SharePoint или записными книжками объединенной группы, выберите одну из следующих областей. Эти разрешения также применяются к персональным записным книжкам текущего пользователя, но не к персональным записным книжкам, которые используются другими пользователями. Доступ к общему персональному содержимому в настоящее время не поддерживается.

Область (корпоративная) Разрешение на портале Azure Описание
Notes.Read.All Просмотр записных книжек OneNote в вашей организации

Пользователь может просматривать содержимое записных книжек и разделов во всех записных книжках, к которым имеет доступ авторизовавшийся пользователь.

Пользователь не может создавать новые страницы, изменять существующие страницы или получать доступ к разделам, защищенным паролем.
Notes.ReadWrite.All Просмотр и изменение записных книжек OneNote в вашей организации

Пользователь может просматривать заголовки записных книжек и разделов; просматривать и изменять все страницы; переименовывать все разделы; создавать страницы во всех записных книжках, к которым имеет доступ авторизовавшийся пользователь.

Пользователь не может получать доступ к разделам, защищенным паролем.

Для разрешений, используемых для доступа к персональным записным книжкам OneDrive, см. Выберите разрешения OneNote (пользовательские приложения).

Войдите в систему и получите маркер доступа (корпоративные приложения)

Приложение инициирует процесс входа в систему, обратившись в службу авторизации. Если пользователи еще не вошли или уже не дали согласие, служба попросит их предоставить учетные данные и согласиться с разрешениями, запрошенными вашим приложением. Если проверка подлинности и авторизация успешны, вы получите маркер доступа, который вы включите в свои запросы к API OneNote.

Важно!

Обращайтесь с маркерами доступа и обновления так же надежно, как и с паролем пользователя.

Примечание

В зависимости от вашей платформы вы можете использовать SDK для упрощения потоков авторизации.

Получение маркера доступа - это процесс с потоком кода, состоящий из двух шагов:

  1. Вход пользователя в систему и получение кода авторизации.
  2. Обмен кода на маркер доступа

Этот процесс представляет собой Коэффициент предоставления кода авторизации. Если вы хотите использовать неявный поток, вам нужно будет отредактировать файл манифеста. См. статью Настройте ваше приложение, чтобы обеспечить неявный поток предоставления OAuth 2.0 в разделе Зарегистрируйте свое веб-приложение для веб-обозревателя.

Этап 1. Вход пользователя в систему и получение кода авторизации. Чтобы запустить процесс регистрации, загрузите следующий URL-запрос в веб-обозревателе или в элементе управления веб-обозревателя

В приведенном ниже URL-адресе используется общая конечная точка клиента, допустимая для любого приложения. 

https://login.microsoftonline.com/common/oauth2/authorize
  ?response_type=code
  &client_id={client-id}
  &redirect_uri={redirect-uri}
  &resource=https://onenote.com/
Обязательный параметр строки запроса Описание
response_type Тип используемого вами потока проверки подлинности. В этом случае код.
client_id Идентификатор клиента, созданный для приложения.
redirect_uri URL-адрес перенаправления для вашего приложения.
resource Ресурс, доступ к которому вам нужен. В таком случае https://onenote.com/

После успешной проверки подлинности и авторизации веб-обозреватель перенаправляет URL-адрес перенаправления с помощью параметра code, добавленного к URL-адресу, как показано в следующем примере.** Скопируйте значение code для использования в шаге 2. Этот код действителен в течение нескольких минут.

https://your-redirect-uri/
  ?code=AAABAA...AA
  &session_state=d56e3523-614e-4fbe-bf89-3ba0f065954b

Этап 2. Замените код авторизации для маркера доступа и обновите маркер. Отправьте следующий HTTP-запрос с правильно закодированной строкой URL-адреса в тексте сообщения.

POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&code={code}
&resource=https://onenote.com/
Обязательный параметр текста сообщения Описание
grant_type Тип предоставления запроса. В этом случае authorization_code.
client_id Идентификатор клиента, созданный для приложения.
client_secret Только веб-приложения и веб-API. Секрет клиента, созданный для вашего приложения.
code Код, который вы получили как параметр URL на предыдущем шаге.
redirect_uri URL-адрес перенаправления для вашего приложения. Он должен соответствовать redirect_uri первого запроса.
resource Ресурс, доступ к которому вам нужен. В таком случае, https://onenote.com/

В случае успешного выполнения ответ на запрос POST содержит строку JSON, которая включает в себя access_token и refresh_token, как показано в следующем примере. Маркер доступа действует в течение времени, указанного в свойстве expires_in (в секундах).

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "scope":"Notes.ReadWrite",
  "expires_on":"1446588136",
  "not_before":"1446584236",
  "resource":"https://onenote.com/",
  "access_token":"eyJ0eX...2-w",
  "refresh_token":"AAABAAA...IAA",
  "id_token":"eyJ0eX...fQ."
}

См. Поток предоставления кода авторизации чтобы узнать больше о реализации потока Azure AD, включая дополнительные параметры, которые вы можете использовать в запросах.

Включите маркер доступа в свой запрос к API OneNote

Все ваши запросы к API OneNote должны отправлять маркер доступа в качестве маркера носителя в заголовке Authorization. Например, следующий запрос получает пять ваших записных книжек, отсортированных в алфавитном порядке по имени:

GET https://www.onenote.com/api/v1.0/me/notes/notebooks?top=5
Authorization: Bearer {access-token}

Маркеры доступа действительны в течение только одного часа, поэтому вам нужно будет получить новые маркеры, когда срок предыдущих истечет. Вам нужно проверить срок действия маркера перед его использованием и получить новый при необходимости. Пользователи могут оставаться вошедшими в систему, и они не должны снова соглашаться на разрешения, если они не выходят или не отменяют разрешения.

Получение нового маркера доступа после истечения его срока действия (корпоративные приложения)

Вы можете запросить новый маркер доступа, используя маркер обновления, либо повторив процесс авторизации с самого начала.

Если срок действия маркера доступа истек, запросы к API будут возвращать ответ 401 Unauthorized. Ваше приложение должно обработать этот ответ и проверить срок действия маркера перед отправкой запросов.

Отправьте следующий HTTP-запрос с правильно закодированной строкой URL-адреса в тексте сообщения.

URL-адрес в следующем примере использует общую конечную точку клиента, допустимую для любого приложения. 

POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}
&resource={resource-id}
Обязательный параметр текста сообщения Описание
grant_type Тип предоставления запроса. В этом случае refresh_token.
client_id Идентификатор клиента, созданный для приложения.
client_secret Только веб-приложения и веб-API. Секрет клиента, созданный для вашего приложения.
redirect_uri URL-адрес перенаправления для вашего приложения.
refresh_token Маркер обновления, полученный ранее.
resource Ресурс, доступ к которому вам нужен. В таком случае, https://onenote.com/

В случае успешного выполнения ответ на запрос POST содержит строку JSON, которая включает в себя access_token и refresh_token, как показано в следующем примере.

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "scope":"Group.Read.All Notes.ReadWrite",
  "expires_on":"1447656020",
  "not_before":"1447652120",
  "resource":"https://onenote.com/",
  "access_token":"eyJ0eX...Jww",
  "refresh_token":"AAABAAA...IAA"
}

Обновите сохраненные маркеры, чтобы убедиться, что у вашего приложения есть маркеры с максимальным сроком действия.

SDK для разработки OneNote

Приложения OneNote могут использовать SDK OneDrive API для получения маркеров доступа, необходимых для всех запросов API OneNote. SDK упрощает для вас проверку подлинности. Вы просто предоставляете свою идентификационную информацию и объединяете несколько вызовов, а SDK обрабатывает все, начиная с входа и соглашаясь на получение, хранение и обновление маркеров. Затем вы можете осуществить REST-вызовы к API OneNote. Наше руководство по iOS показывает, как вы можете использовать SDK в приложении OneNote.

Все версии SDK поддерживают проверку подлинности учетной записи Microsoft (для потребительских записных книжек), а некоторые также поддерживают Azure Active Directory (для корпоративных записных книжек). См. Документация OneDrive для текущего списка поддерживаемых платформ.

Примечание

SDK OneDrive API заменяет Live SDK. Live SDK устарел, но будет продолжать поддерживать существующие приложения OneNote, которые его используют. Для новой разработки используйте OneDrive API SDK.

В какой-то момент мы можем предоставить библиотеки, которые обрабатывают проверку подлинности и поддерживают собственные вызовы в OneNote API, но пока вы можете использовать OneDrive API SDK.

Или же, корпоративные приложения могут использовать Библиотеку проверки подлинности Active Directory (ADAL) для доступа к записным книжкам, размещенным на Office 365 и SharePoint. Вы можете использовать ADAL напрямую, если SDK не доступно для вашей платформы, или если вы хотите больше контролировать процесс проверки подлинности. Нашеруководство по ASP.NET MVCпоказывает, как вы можете использовать ADAL в приложении OneNote.

Важно!

Чтобы взаимодействовать с содержимым и ресурсами OneNote, вы всегда должны использовать API OneNote. Не используйте API OneDrive.

Ошибки

Если возникнут ошибки, связанные с проверкой подлинности, веб-браузер будет перенаправлен на страницу ошибки. На странице ошибки отображается сообщение, понятное для пользователя, однако URL-адрес страницы ошибки содержит дополнительные сведения, которые могут помочь вам в отладке кода, выполнение которого привело к ошибке. Параметры URL-адреса включены в качестве закладки, например, #error={error_code}&error_description={message}

Если администратор не даст согласие на ваше приложение, поток будет перенаправлен на ваш URL-адрес перенаправления и будет включать параметры ошибки.

Для ознакомления с более подробными сведениями об обработке ошибок см. статью Обработка ошибок в OAuth 2.0.

См. также