Копирование записных книжек, разделов и страниц

Статья
01/26/2016

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

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

POST ../notes/sections/{id}/copyToNotebook

Отправьте объект копирования JSON в тексте сообщения. Если запрос выполнен успешно, API OneNote возвращает код состояния HTTP 202 и заголовок Operation-Location. Затем вы можете опросить конечную точку операции для получения результата.

Примечание

Функции копирования в настоящий момент поддерживаются для персональных, размещенных на сайте и записных книжек 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/
Затем добавьте соответствующую конечную точку действия copy:

Копировать страницу в раздел

../pages/{id}/copyToSection

Копировать раздел в записную книжку

../sections/{id}/copyToNotebook

Копировать раздел в группу разделов

../sections/{id}/copyToSectionGroup

Копировать записную книжку

../notebooks/{id}/copyNotebook

Записная книжка копируется в папку "Записные книжки" в библиотеке назначения "Документы". Если папка "Записные книжки" отсутствует, она будет создана.

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

https://www.onenote.com/api/v1.0/me/notes/sections/{id}/copyToNotebook

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

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

https://www.onenote.com/api/v1.0/groups/{id}/notes/notebooks/{id}/copyNotebook

Примечание

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

Составление текста сообщения

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

Параметр	Описание
id	Идентификатор записной книжки или группы разделов назначения (для разделов) или идентификатор раздела назначения (для страниц). Используется только с copyToNotebook, copyToSectionGroup и copyToSection.
siteCollectionId	Идентификатор семейства веб-узлов SharePoint, содержащий сайт для копирования элемента. Используется с siteId и только при копировании на сайт SharePoint.
siteId	Идентификатор сайта SharePoint, на который будет скопирован элемент. Используется с siteCollectionId и только при копировании на сайт SharePoint.
groupId	Идентификатор группы, в которую будет скопирован элемент. Используется только при копировании в единую группу.
renameAs	Имя копии. Используется только с copyNotebook, copyToNotebookи copyToSectionGroup. По умолчанию используется имя существующего элемента.

Узнайте, как получить записную книжку, группу разделов и идентификаторы разделов, а также семейство веб-узлов и идентификаторы сайтов. Информацию о получении идентификаторов групп см. в документации по API Azure AD Graph.

Пример последовательности для операции копирования

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

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

POST https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923/copyNotebook
Authorization: Bearer {token}
Content-Type: application/json 

{
  "siteCollectionId":"0f6dbd5d-d179-49c6-aabd-15830ea90ca8",
  "siteId":"3ba679cf-4470-466e-bc20-053bdfec75bf"
}

Примечание

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

Если вызов выполнен успешно, API OneNote возвращает код состояния 202 и заголовок Operation-Location. Вот выдержка из ответа:

HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923
X-CorrelationId: 8a211d7c-220b-413d-8022-9a946499fcfb
Operation-Location: https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
...

Затем вы опросите конечную точку Operation-Location, чтобы получить состояние операции копирования:

GET https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
Authorization: Bearer {token}
Accept: application/json

API OneNote возвращает объект OperationModel, который показывает текущее состояние. Следующий пример ответа возвращается при состоянии "Выполненные".

{
  "@odata.context":"https://www.onenote.com/api/beta/$metadata#myOrganization/siteCollections('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/sites('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/notes/operations/$entity",
  "id":"copy-1c5be75c-e7db-4219-8145-a2d6c3f171a33ec9f3da-2b24-4fb1-a776-fe8c8cd1410f",
  "status":"completed",
  "createdDateTime":"2015-09-16T17:32:07.048Z",
  "lastActionDateTime":"2015-09-16T17:32:17.7777639Z",
  "resourceLocation":"https://www.onenote.com/api/v1.0/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/3ba679cf-4470-466e-bc20-053bdfec75bf/notes/notebooks/1-bde29eeb-66e2-4fed-8d48-51cd1bf32511",
  "resourceId":null,"
  "error":null
}

Состояние может быть следующим: выполненные, выполняются или не выполнены.

Если состояние выполненные, то свойство resourceLocation содержит конечную точку ресурса для новой копии.
Если состояние выполняются, то в свойстве percentComplete показан приблизительный процент выполнения.
Если состояние не выполнены, то в свойствах error и @api.diagnostics предоставляется информация об ошибке.

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

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

Данные запроса	Описание
Протокол	Все запросы используют протокол SSL/TLS для HTTPS.
Заголовок Authorization	`Bearer {token}`, где {token} — это действительный маркер доступа OAuth 2.0 для зарегистрированного приложения. Если он отсутствует или является недействительным, запрос завершится ошибкой с кодом состояния 401. См. статью Проверка подлинности и разрешения.
Заголовок Content-Type	`application/json`
Заголовок Accept	`application/json`

Данные ответа	Описание
Код успешного завершения действия	Код состояния HTTP 202.
Заголовок Operation-Location	URL-адрес для опроса состояния операции. Опрос конечной точки операции возвращает объект OperationModel, который содержит состояние операции и другую информацию.
Заголовок X-CorrelationId	GUID, уникальный идентификатор запроса. Это значение можно использовать вместе со значением заголовка Date при устранении неполадок совместно со службой поддержки Майкрософт.

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

Платформа	Область разрешений
Потребитель	office.onenote_create, office.onenote_update_by_app, office.onenote_update
Корпоративный	Notes.Create, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, Notes.ReadWrite.All

Дополнительные сведения об областях разрешений и принципе их работы см. в разделе Области разрешений OneNote.

Копирование записных книжек, разделов и страниц

Конструирование URI запроса

Составление текста сообщения

Пример последовательности для операции копирования

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

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

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

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

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

Разрешения

См. также

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