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

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

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

POST ../permissions

GET ../permissions

GET ../permissions/{permission-id}

DELETE ../permissions/{permission-id}

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

1. Чтобы создать 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/

2. Добавьте путь к целевой записной книжке, группе раздела или объекту раздела, а затем к разрешениям или конечной точке разрешений/{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}

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

Чтобы создать или обновить разрешения для записной книжки, группы раздела или раздела, отправьте запрос 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"
}

Пример

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

Запрос

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.

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

Чтобы получить разрешения для записной книжки, группы раздела или раздела, отправьте запрос 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]

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

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

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

Пример

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

Запрос

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.

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

Чтобы удалить разрешение для записной книжки, группы раздела или раздела, отправьте запрос 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.

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

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

При управлении разрешениями для объектов 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
• Центр разработчиков OneNote
• Блог разработчиков OneNote
• Вопросы разработки OneNote на сайте Stack Overflow
• Репозитории GitHub OneNote