OneDrive и SharePoint в Microsoft Graph

Статья
04/08/2023

REST API OneDrive — это часть API Microsoft Graph, позволяющая приложению подключаться к содержимому в OneDrive и SharePoint. REST API совместно используется в OneDrive, OneDrive для бизнеса, библиотеках документов SharePoint и группах Office, чтобы приложение могло считывать и хранить содержимое в любом из этих расположений, используя один и тот же код.

REST API входят в состав Microsoft Graph — общего API для служб Майкрософт.

Если у вас есть решения, использующие API OneDrive за пределами Microsoft Graph или предназначенные для SharePoint Server 2016, ознакомьтесь с различиями прямых конечных точек, чтобы получить дополнительный контекст для данной документации.

Начало работы

Чтобы быстро поэкспериментировать с Microsoft Graph и доступом к файлам, попробуйте песочницу Graph и краткое руководство по Microsoft Graph.

REST API OneDrive предоставляет несколько типов верхнего уровня, представляющих адресуемые ресурсы в API:

диск(объект верхнего уровня)
driveItem(файлы и папки)

Ниже представлен пример ресурса driveItem.

{
  "@microsoft.graph.downloadUrl":"http://public-sn3302.files.1drv.com/y2pcT7OaUEExF7EHOl",
  "createdDateTime": "2014-10-31T03:37:04.72Z",
  "eTag": "aRDQ2NDhGMDZDOTFEOUQzRCE1NDkyNy4w",
  "id":"D4648F06C91D9D3D!54927",
  "lastModifiedBy": {
    "user": {
      "displayName": "daron spektor",
      "id": "d4648f06c91d9d3d"
    }
  },
  "name":"BritishShorthair.docx",
  "size":35212,
  "file": {
    "hashes":{
      "sha1Hash":"cf23df2207d99a74fbe169e3eba035e633b65d94"
    }
  }
}

Данные о ресурсе предоставляются тремя способами:

Свойства (например, id и name) представляют простые значения.
Аспекты (например, file и photo) представляют сложные значения. Наличие аспектов в элементе обычно указывает на поведение и возможности элемента и связанных с ним свойств.
Ссылки (например, children) указывают на коллекции других ресурсов.

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

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

Дополнительные сведения о ресурсах и аспектах см. в статьях Ресурсы и Аспекты.

Корневые ресурсы Microsoft Graph

В Microsoft Graph функции OneDrive доступны из нескольких корневых ресурсов. Эти ресурсы соответствуют расположениям хранилищ OneDrive и библиотек документов SharePoint в Office 365. Отслеживаемые объекты в Microsoft Graph могут содержать один или несколько дисков:

Объект	Пример пути
User	`/v1.0/users/{id}` или `/v1.0/me`
Group	`/v1.0/groups/{id}`
Site	`/v1.0/sites/{id}`

Корневые ресурсы OneDrive

Ссылаясь на корневой ресурс Microsoft Graph, приложение может обращаться к ресурсам OneDrive по следующим путям:

Путь	Ресурс
`/drives`	Список ресурсов drive, доступных прошедшему аутентификацию пользователю.
`/drives/{drive-id}`	Доступ к определенному ресурсу drive по идентификатору.
`/drives/{drive-id}/root/children`	Список элементов в корне определенного ресурса drive.
`/drive/items/{item-id}`	Доступ к ресурсу driveItem по идентификатору.
`/drive/special/{special-id}`	Доступ к известной папке по ее известному имени.
`/shares/{share-id}`	Доступ к ресурсу driveItem по свойству shareId или URL-адресу общего доступа.

Адресация на основе пути в объекте drive

К ресурсу driveItem можно обращаться по уникальному идентификатору или его расположению в иерархии drive (т. е. пользовательскому пути). В запросе API можно переключаться между пространством путей API и пространством пользовательских путей с помощью двоеточия. Этот синтаксис допустим для ресурсов driveItem, к которым обращаются через пространство API.

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

Путь	Ресурс
`/drive/root:/path/to/file`	Доступ к ресурсу driveItem по пути относительно корня.
`/drive/items/{item-id}:/path/to/file`	Доступ к ресурсу driveItem по пути относительно другого элемента.
`/drive/root:/path/to/folder:/children`	Список дочерних элементов при доступе по пути относительно корня диска.
`/drive/items/{item-id}:/path/to/folder:/children`	Список дочерних элементов при доступе по пути относительно другого элемента.

Общие папки и удаленные элементы

Пользователи OneDrive персональный могут добавлять один или несколько общих элементов с одного диска в свое хранилище OneDrive. Эти общие элементы отображаются в коллекции children как ресурсы driveItem с аспектом remoteItem.

Кроме того, аспект remoteItem также используется в тех случаях, когда элементы возвращаются не с целевого диска. Эти элементы также могут возвращаться при поиске, а также из разделов Последние файлы и Мне предоставлен доступ.

Дополнительные сведения о работе с общими папками и удаленными элементами см. в этой статье.

Одно из самых распространенных действий для OneDrive и SharePoint — предоставление другим пользователям доступа к элементам. С помощью OneDrive ваше приложение может создавать ссылки для общего доступа, добавлять разрешения и отправлять приглашения для доступа к элементам на диске.

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

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

Веб-перехватчики и уведомления

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

Примечания по программированию

Совместимость API

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

Критическое изменение — это изменение формата запроса или ответа, при котором удаляется или меняется текущее документированное поведение либо удаляется элемент определения ресурса. Добавление действий, свойств, аспектов или ссылок на ресурсы не является критическим изменением.

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

Мы продолжим вносить в текущую версию API некритические изменения, включая добавление аспектов, свойств и ресурсов к API. Ниже перечислены требования к коду, вызывающему API.

Код должен быть устойчивым к добавлению свойств в ответы JSON. Их можно игнорировать.
Код не должен зависеть от порядка свойств, возвращаемых в ответах JSON.
Код должен использовать только задокументированные пути API, ресурсы, свойства и перечисляемые значения. Согласованность недокументированных значений не гарантируется.
Все URL-адреса, которые возвращает API OneDrive, должны рассматриваться как непрозрачные. Приложение не должно делать предположений о формате или параметрах в этих URL-адресах. Они могут быть изменены без предварительного уведомления.

Регулирование

В OneDrive есть ограничения, которые гарантируют, что пользователи и приложения не окажут негативного влияния на работу других пользователей. Если действие нарушает ограничения OneDrive, то в течение некоторого времени запросы API отклоняются. OneDrive также может возвращать заголовок Retry-After с временем (в секундах) ожидания приложения перед отправкой дополнительных запросов.

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

Работа с записными книжками OneNote

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

Непрерывная проверка документации

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

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

Сведения о последних сборках см. на странице состояния сборок AppVeyor для нашего репозитория документации.

Указанные ниже статьи содержат общие сведения о других понятиях, применимых к API OneDrive.