Управление разрешениями для объектов OneNote

Статья
05/24/2016

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

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

POST ../permissions

GET ../permissions

GET ../permissions/{permission-id}

DELETE ../permissions/{permission-id}

Примечание

Управление разрешениями поддерживается для персональных, размещенных на сайте и записных книжек Office 365 для объединенных групп, но не для потребительских записных книжек в OneDrive.

Создание URI запроса

Чтобы создать URI запроса, начните с корневого URL-адреса службы для своей платформы:

Записные книжки OneDrive для бизнеса

https://www.onenote.com/api/v1.0/me/notes/

https://www.onenote.com/api/v1.0/users/{id}/notes/

Записные книжки на сайте SharePoint

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

Записные книжки объединенной группы

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/
Добавьте путь к целевой записной книжке, группе раздела или объекту раздела, а затем к разрешениям или конечной точке разрешений/{id} .

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

https://www.onenote.com/api/v1.0/me/notes/notebooks/{id}/permissions/{id}

https://www.onenote.com/api/v1.0/users/{id}/notes/sectiongroups/{id}/permissions

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/notebooks/{id}/permissions

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/sections/{id}/permissions/{id}

Примечание

Узнайте больше о корневом URL-адресе службы.

Создание и обновление разрешений

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

Разрешения применяются ко всем сущностям OneNote вниз по цепочке наследования.

Вы можете обновлять разрешения с целью предоставления расширенного доступа. Однако для ограничения доступа вы должны удалить существующее разрешение и создать новое. См. статью Наследование разрешения и приоритет.

Создать или обновить разрешения для записной книжки

POST ../notebooks/{notebook-id}/permissions

Создать или обновить разрешения для группы раздела

POST ../sectiongroups/{sectiongroup-id}/permissions

Создать или обновить разрешения для раздела

POST ../sections/{section-id}/permissions

В тексте сообщения отправьте объект JSON с требуемыми параметрами.

{
    "userRole": "user-role", 
    "userId": "user-login-id"
}

Параметр	Описание
userRole	Шрифт разрешения: `Owner`, `Contributor`, или `Reader`.
userId	Логин пользователя или группы для назначения разрешения. API принимает формат утверждений, который включает имя поставщика членства (`i:0#.f\|membership\|username@domainname.com`) или только имя пользователя-участника (`username@domainname.com`).

Пример

Следующий запрос создает разрешение для указанной записной книжки.

Запрос

POST ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "userRole": "Owner", 
    "userId": "i:0#.f|membership|alexd@domainname.com"
}

Ответ

HTTP/1.1 201 Created

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions/$entity",
  "userRole":"Owner",
  "userId":"i:0#.f|membership|alexd@domainname.com",
  "name":"Alex Darrow",
  "id":"1-23",
  "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
}

Информация о запросах и ответах

Следующая информация относится к запросам POST /permissions.

Данные запроса Описание

Протокол Все запросы используют протокол SSL/TLS для HTTPS.

Заголовок Authorization

Данные запроса	Описание
Протокол	Все запросы используют протокол SSL/TLS для HTTPS.
Заголовок Authorization	`Bearer {token}`, где {token} — это действительный маркер доступа OAuth 2.0 для зарегистрированного приложения. Если отсутствует или недействительно, при выполнении запроса будет возвращена ошибка с кодом состояния 401. См. статью Аутентификация с использованием Azure AD (корпоративные приложения).
Область разрешений	Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, или Notes.ReadWrite.All

Bearer {token}, где {token} — это действительный маркер доступа OAuth 2.0 для зарегистрированного приложения.

Если отсутствует или недействительно, при выполнении запроса будет возвращена ошибка с кодом состояния 401. См. статью Аутентификация с использованием Azure AD (корпоративные приложения).

Область разрешений Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, или Notes.ReadWrite.All

Данные в ответе	Описание
Код успешного завершения	Код состояния HTTP 201
Текст ответа	Представление OData разрешения в формате JSON. Описание объекта разрешений см. в разделе Получение разрешений.
Ошибки	В случае сбоя запроса API возвращает ошибки в тексте ответа.
Заголовок X-CorrelationId	GUID, уникальный идентификатор запроса. Это значение можно использовать вместе со значением заголовка Date при устранении неполадок совместно со службой поддержки Майкрософт.

Получение разрешений

Чтобы получить разрешения для записной книжки, группы раздела или раздела, отправьте запрос GET в соответствующую конечную точку.

Получить разрешения для записной книжки

GET ../notebooks/{notebook-id}/permissions

Получить специальное разрешение для записной книжки

GET ../notebooks/{notebook-id}/permissions/{permission-id}

Получить разрешения для группы раздела

GET ../sectiongroups/{sectiongroup-id}/permissions

Получить специальное разрешение для группы раздела

GET ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

Получить разрешения для раздела

GET ../sections/{section-id}/permissions

Получить специальное разрешение для раздела

GET ../sections/{section-id}/permissions/{permission-id}

Запросы GET выдают наивысшее разрешение для роли пользователя в целевом объекте. Для получения дополнительной информации см. статью Наследование разрешения и приоритет.

GET /permissions запросы поддерживают параметры запроса OData, а именно:

GET ../permissions[?filter,orderby,select,top,skip,count]

GET ../permissions/{permission-id}[?select]

Примечание

Конечная точка разрешений не поддерживает expand параметр запроса.

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

Объект разрешений

Разрешение содержит следующие свойства.

Свойство	Описание
name	Отображаемое имя пользователя или участника группы. Пример: `"name":"Everyone"`
id	Уникальный идентификатор разрешения в форме `1-{principal-member-id}`. Пример: `"id":"1-4"`
self	URL-адрес объекта разрешений.
userId	Логин пользователя или группы, которым назначено разрешение. Это значение всегда выдается в формате утверждения, например: `i:0#.f\|membership\|username@domainname.com`.
userRole	Шрифт разрешения: `Owner`, `Contributor`, или `Reader`.

Пример

Следующий запрос получает все разрешения для указанной записной книжки.

Запрос

GET ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Accept: application/json

Ответ

HTTP/1.1 200

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions",
  "value":[
  {
    "userRole":"Owner",
    "userId":"c:0(.s|true",
    "name":"Everyone",
    "id":"1-4",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/1-4"
  },
  {
    "userRole":"Owner",
    "userId":"c:0-.f|rolemanager|spo-grid-all-users/8461cbdd-15a6-45c8-b177-ac24f48a8bee",
    "name":"Everyone except external users",
    "id":"1-5",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-5"
  },
  {
    "userRole":"Owner",
    "userId":"i:0#.f|membership|alexd@domainname.com",
    "name":"Alex Darrow",
    "id":"1-23",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
  }]
}

Информация о запросах и ответах

Следующая информация относится к запросам GET /permissions.

Данные запроса Описание

Протокол Все запросы используют протокол SSL/TLS для HTTPS.

Заголовок Authorization

Данные запроса	Описание
Протокол	Все запросы используют протокол SSL/TLS для HTTPS.
Заголовок Authorization	`Bearer {token}`, где {token} — это действительный маркер доступа OAuth 2.0 для зарегистрированного приложения. Если отсутствует или недействительно, при выполнении запроса будет возвращена ошибка с кодом состояния 401. См. статью Аутентификация с использованием Azure AD (корпоративные приложения).
Область разрешений	Notes.Read, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite или Notes.ReadWrite.All

Bearer {token}, где {token} — это действительный маркер доступа OAuth 2.0 для зарегистрированного приложения.

Область разрешений Notes.Read, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite или Notes.ReadWrite.All

Данные в ответе	Описание
код успешного завершения действия;	Код состояния HTTP 200 и запрошенные разрешения.
Текст ответа	Представление OData разрешений в формате JSON.
Ошибки	В случае сбоя запроса API возвращает ошибки в тексте ответа.
Заголовок X-CorrelationId	GUID, уникальный идентификатор запроса. Это значение можно использовать вместе со значением заголовка Date при устранении неполадок совместно со службой поддержки Майкрософт.

Удаление разрешений

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

Когда вы удаляете разрешение, оно удаляется из всех объектов OneNote вниз по цепочке наследования.

Удаление разрешений для записной книжки

DELETE ../notebooks/{notebook-id}/permissions/{permission-id}

Удаление разрешения для группы раздела

DELETE ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

Удаления разрешения для раздела

DELETE ../sections/{section-id}/permissions/{permission-id}

Пример

Следующий запрос удаляет разрешение для указанной записной книжки.

DELETE ../v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23
Authorization: Bearer {token}
Accept: application/json

Информация о запросах и ответах

Следующая информация относится к запросам DELETE /permissions.

Данные запроса Описание

Протокол Все запросы используют протокол SSL/TLS для HTTPS.

Заголовок Authorization

Данные запроса	Описание
Протокол	Все запросы используют протокол SSL/TLS для HTTPS.
Заголовок Authorization	`Bearer {token}`, где {token} — это действительный маркер доступа OAuth 2.0 для зарегистрированного приложения. Если отсутствует или недействительно, при выполнении запроса будет возвращена ошибка с кодом состояния 401. См. статью Аутентификация с использованием Azure AD (корпоративные приложения).
Область разрешений	Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, или Notes.ReadWrite.All

Bearer {token}, где {token} — это действительный маркер доступа OAuth 2.0 для зарегистрированного приложения.

Область разрешений Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, или Notes.ReadWrite.All

Данные в ответе	Описание
код успешного завершения действия;	Код состояния HTTP 204.
Ошибки	В случае сбоя запроса API возвращает ошибки в тексте ответа.
Заголовок X-CorrelationId	GUID, уникальный идентификатор запроса. Это значение можно использовать вместе со значением заголовка Date при устранении неполадок совместно со службой поддержки Майкрософт.

Разрешения, наследование и приоритет

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

Разрешение	Описание
Читатель	Доступ только для чтения к записным книжкам, группам раздела и разделам.
Участник	Может добавлять, редактировать и удалять записные книжки, группы раздела и разделы.
Владелец	Все вышеуказанные разрешения, также может управлять разрешениями (получать, создавать и удалять).

При управлении разрешениями для объектов OneNote вы должны понимать наследование разрешения и приоритет.

Наследование. Объекты наследуют родительские разрешения. Таким образом, записные книжки наследуют разрешения библиотеки документов, которая содержит записную книжку. И, в свою очередь, такие разрешения наследуются группами дочерних разделов и разделами в записной книжке. Когда вы устанавливаете прямые разрешения для записной книжки, группы раздела или раздела, разрешения также распространяются на их дочерние объекты.
Приоритет. Когда в объекте OneNote устанавливаются конфликтующие разрешения, применяется самое высокое (самое расширенное) разрешение. Пользователям и группам могут предоставляться конфликтующие уровни доступа, когда к объекту (явно или унаследовано) применяются несколько разрешений, или когда пользователь или группа принадлежат нескольким ролям.

Такие принципы определяют, как API OneNote управляет разрешениями. Примеры:

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

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

Создание корневого URL-адреса службы OneNote

Для всех вызовов API OneNote используется следующий формат корневого URL-адреса службы OneNote.

https://www.onenote.com/api/{version}/{location}/notes/

СегментversionURL-адреса представляет собой версию API OneNote, которую вы хотите использовать.

Используйте значение v1.0 для стабильного кода в рабочей среде.
Используйте значение beta, чтобы опробовать функцию, находящуюся на стадии разработки. Функции бета-версии могут меняться, поэтому не следует использовать их в производственном коде.

Сегмент location URL-адреса представляет собой местоположение записных книжек, к которым вы хотите получить доступ:

Записные книжки OneDrive для бизнеса
- Использованиеmeдля содержимого OneNote, принадлежащего текущему пользователю.
- Используйте значение users/{id} для содержимого OneNote, которым указанный (в URL-адресе) пользователь поделился с текущим пользователем. ИспользуйтеAzure AD Graph API для получения идентификаторов пользователей.
Записные книжки на сайте SharePoint
- Сайты групп и другие сайты SharePoint могут содержать записные книжки OneNote в своих библиотеках документов.
- Используйте myOrganization/siteCollections/{id}/sites/{id} для содержимого OneNote на сайте в клиенте, к которому подключен текущий пользователь. Поддерживается только текущий клиент, доступ к которому осуществляется с помощью ключевого слова myOrganization. Узнайте, как получить Идентификаторы сайта.
Записные книжки объединенной группы
- Объединенные группы (также называемые группами Office 365) являются частью взаимодействия, связанного с Office 365. Участники группы могут делиться записными книжками, файлами и электронной почтой.
- Использование myOrganization/groups/{id} для содержимого OneNote в указанной группе, членом которой является текущий пользователь. Объединенные группы являются единственным поддерживаемым типом группы. ИспользуйтеAzure AD Graph API для получения идентификаторов группы.

Используйте метод FromUrlдля получения семейства сайтов и идентификаторов сайта

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

Формат URL-адреса сайта зависит от вашей конфигурации, например, https://domain.sharepoint.com/site-a или https://domain.com/sites/site-a.

Пример запроса

GET https://www.onenote.com/api/v1.0/myOrganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')

Authorization: Bearer {token}

Accept: application/json

Пример ответа

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

Требования к использованию FromUrl и работа с записными книжками сайта SharePoint:

Вы можете создавать только записные книжки OneNote, группы разделов, разделы и страницы на сайтах с библиотекой документов по умолчанию. (Некоторые шаблоны сайтов не создают библиотеку документов по умолчанию.) Однако, запросы GET возвращают содержимое OneNote из всех библиотек документов на сайте.
URL-адрес корневого каталога для обслуживания OneNote неизменяем, что означает, что вы не можете использовать путь сайта REST API и затем добавить на него notes конечную точку.
Пользователь, от имени которого вы осуществляете вызов, должен быть участником сайта.
FromUrl работает только с проиндексированными сайтами. Для индексации нового сайта может потребоваться несколько часов.

Управление разрешениями для объектов OneNote

Создание URI запроса

Создание и обновление разрешений

Пример

Запрос

Ответ

Информация о запросах и ответах

Получение разрешений

Объект разрешений

Пример

Запрос

Ответ

Информация о запросах и ответах

Удаление разрешений

Пример

Информация о запросах и ответах

Разрешения, наследование и приоритет

Создание корневого URL-адреса службы OneNote

Используйте метод FromUrlдля получения семейства сайтов и идентификаторов сайта

Пример запроса

Пример ответа

См. также

Дополнительные ресурсы