OneDrive и SharePoint в Microsoft GraphOneDrive and SharePoint in Microsoft Graph

Проверка документации и состояние сборкиDocumentation validation and build status

REST API OneDrive — это часть API Microsoft Graph, позволяющая приложению подключаться к содержимому в OneDrive и SharePoint.The OneDrive REST API is a portion of the Microsoft Graph API which allows your app to connect to content stored in OneDrive and SharePoint. REST API совместно используется в OneDrive, OneDrive для бизнеса, библиотеках документов SharePoint и группах Office, чтобы приложение могло считывать и хранить содержимое в любом из этих расположений, используя один и тот же код.The REST API is shared between OneDrive, OneDrive for Business, SharePoint document libraries, and Office Groups, to allow your app the flexibility to read and store content in any of these locations with the same code.

REST API входят в состав Microsoft Graph — общего API для служб Майкрософт.These REST APIs are a part of the Microsoft Graph, a common API for Microsoft services.

Если у вас есть решения, использующие API OneDrive за пределами Microsoft Graph или предназначенные для SharePoint Server 2016, ознакомьтесь с различиями прямых конечных точек, чтобы получить дополнительный контекст для данной документации.For existing solutions using OneDrive API outside of Microsoft Graph, or solutions targeting SharePoint Server 2016, see direct endpoint differences for more context on reading this documentation.

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

Чтобы быстро поэкспериментировать с Microsoft Graph и доступом к файлам, попробуйте песочницу Graph и краткое руководство по Microsoft Graph.To quickly experiment with Microsoft Graph and accessing files, check out the Graph Explorer and the Microsoft Graph Quick Start.

REST API OneDrive предоставляет несколько типов верхнего уровня, представляющих адресуемые ресурсы в API:OneDrive's REST API provides a few top-level types that represent addressable resources in the API:

  • drive (объект верхнего уровня);drive (top-level object)
  • driveItem (файлы и папки).driveItem (files and folders)

Ниже представлен пример ресурса driveItem.The following is an example of a DriveItem resource:

{
  "@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"
    }
  }
}

Данные о ресурсе предоставляются тремя способами:Data about a resource is provided in three ways:

  • Свойства (например, id и name) представляют простые значения.Properties (like id and name) expose simple values.
  • Аспекты (например, file и photo) представляют сложные значения.Facets (like file and photo) expose complex values. Наличие аспектов в элементе обычно указывает на поведение и возможности элемента и связанных с ним свойств.The presence of facets on an item generally indicate behaviors or capabilities of an item and related properties.
  • Ссылки (например, children) указывают на коллекции других ресурсов.References (like items) point to collections of other resources.

Многие запросы можно настраивать, включая дополнительные данные или удаляя неиспользуемые свойства из ответов.Many requests can be tailored to include additional data or remove unused properties from the responses. Эти возможности реализуются в OneDrive с помощью необязательных параметров запросов.OneDrive uses optional query parameters to enable this functionality. Для каждого запроса в документации предоставлены дополнительные сведения о поддерживаемых параметрах.Throughout the documentation, each request provides more context about which parameters are supported.

По умолчанию большинство свойств и аспектов возвращаются, когда все ссылки скрыты.By default, most properties and facets are returned while all references are hidden. Для эффективности рекомендуем указывать параметры select и expand для важных данных.For efficiency, we recommend that you specify select and expand to only return the data you care about.

Дополнительные сведения о ресурсах и аспектах см. в статьях Ресурсы и Аспекты.For details about resources and facets, see Resources and Facets.

Корневые ресурсы Microsoft GraphMicrosoft Graph root resources

В Microsoft Graph функции OneDrive доступны из нескольких корневых ресурсов.Within the Microsoft Graph, the OneDrive functionality is available from several root resources. Эти ресурсы соответствуют расположениям хранилищ OneDrive и библиотек документов SharePoint в Office 365.These resources correspond to where OneDrive and SharePoint document libraries are available within Office 365. Отслеживаемые объекты в Microsoft Graph могут содержать один или несколько дисков:The follow entities in Microsoft Graph may contain one or more drives:

ОбъектEntity Пример путиExample (path)
UserUser /v1.0/users/{id} или /v1.0/me/v1.0/users/{id} or /v1.0/me
GroupGroup /v1.0/groups/{id}
SiteSite /v1.0/sites/{id}

Корневые ресурсы OneDriveOneDrive root resources

Ссылаясь на корневой ресурс Microsoft Graph, приложение может обращаться к ресурсам OneDrive по следующим путям:When addressing a Microsoft Graph root resource, your app can address OneDrive resources using the following paths:

ПутьPath РесурсResource
/drives Список ресурсов drive, доступных прошедшему аутентификацию пользователю.List drive resources available to the authenticated user.
/drives/{drive-id} Доступ к определенному ресурсу drive по идентификатору.Access a specific site by its ID.
/drives/{drive-id}/root/children Список элементов в корне определенного ресурса drive.List items in the root of a specific drive.
/drive/items/{item-id} Доступ к ресурсу driveItem по идентификатору.Access a specific site by its ID.
/drive/special/{special-id} Доступ к известной папке по ее известному имени.Access a special (named) folder in the user's OneDrive by its known name.
/shares/{share-id} Доступ к ресурсу driveItem по свойству shareId или URL-адресу общего доступа.Access a driveItem by its shareId or a sharing URL.

Адресация на основе пути в объекте drivePath-based addressing within a drive

К ресурсу driveItem можно обращаться по уникальному идентификатору или его расположению в иерархии drive (т. е. пользовательскому пути).A driveItem can be addressed by either a unique identifier or where that item exists in the drive's hierarchy (i.e. user path). В запросе API можно переключаться между пространством путей API и пространством пользовательских путей с помощью двоеточия.Within an API request, a colon can be used to shift between API path space and user path space. Этот синтаксис допустим для ресурсов driveItem, к которым обращаются через пространство API.This syntax is valid for any driveItem addressed via the API space.

Вы также можете переключиться на пространство путей API, добавив двоеточие в конце пространства путей файловой системы.You can also transition back to API path space by using a colon at the end of the file system path space. Убедитесь, что пользовательские данные в URL-адресе соответствуют требованиям к адресации и кодированию пути.Ensure user data within the URL follows the addressing and path encoding requirements.

ПутьPath РесурсResource
/drive/root:/path/to/file Доступ к ресурсу driveItem по пути относительно корня.Access a driveItem by path under the root.
/drive/items/{item-id}:/path/to/file Доступ к ресурсу driveItem по пути относительно другого элемента.Access a driveItem by its path relative to another item.
/drive/root:/path/to/folder:/children Список дочерних элементов при доступе по пути относительно корня диска.List children when accessing by path relative to the drive root.
/drive/items/{item-id}:/path/to/folder:/children Список дочерних элементов при доступе по пути относительно другого элемента.List the children of a DriveItem by path relative to another item.

Общие папки и удаленные элементыShared folders and remote items

Пользователи OneDrive персональный могут добавлять один или несколько общих элементов с одного диска в свое хранилище OneDrive.OneDrive personal users can add one or more shared items from another drive to their own OneDrive. Эти общие элементы отображаются в коллекции children как ресурсы driveItem с аспектом remoteItem.These shared items appear as a DriveItem in the children collection with a remoteItem facet.

Кроме того, аспект remoteItem также используется в тех случаях, когда элементы возвращаются не с целевого диска.In addition, scenarios where items are returned from outside the target drive will also include a remoteItem facet. Эти элементы также могут возвращаться при поиске, а также из разделов Последние файлы и Мне предоставлен доступ.These items may also be returned from search, recent files, shared with me.

Дополнительные сведения о работе с общими папками и удаленными элементами см. в этой статье.For more information about working with shared folders and remote items, see Remote items and shared folders.

Предоставление доступа и разрешенияSharing and permissions

Одно из самых распространенных действий для OneDrive и SharePoint — предоставление другим пользователям доступа к элементам.One of the most common actions for OneDrive and SharePoint document libraries is sharing content with other people. С помощью OneDrive ваше приложение может создавать ссылки для общего доступа, добавлять разрешения и отправлять приглашения для доступа к элементам на диске.Microsoft Graph allows your app to create sharing links, add permissions and send invitations to items in a drive.

Кроме того, с помощью OneDrive ваше приложение может получать доступ к общему содержимому непосредственно по ссылке для общего доступа.Microsoft Graph also provides a way for your app to access shared content directly from a sharing link.

Дополнительные сведения о том, как предоставлять доступ к содержимому и использовать его, см. в этой статье.For more details on how to share and consume shared content, see Sharing items in OneDrive.

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

OneDrive поддерживает отправку push-уведомлений в стиле веб-перехватчиков при изменении содержимого OneDrive.OneDrive supports sending webhook-style push notifications when the contents of a OneDrive is changed. Приложение может использовать эти уведомления, чтобы отслеживать изменения практически в реальном времени, а не запрашивать изменения с сервера.Your app can use these notifications to track changes in near real-time instead of polling the server for changes.

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

Совместимость APIAPI compatibility

Служба OneDrive продолжит развиваться, и в нее будут добавляться новые функции.OneDrive will continue to evolve and gain additional functionality. Путь к API включает номер версии, который защитит ваше приложение от критических изменений.The API path includes a version number to protect your app against breaking changes. Если критическое изменение необходимо, номер версии API будет увеличен.When a breaking change is required, the API version number will be incremented. Изменение не затронет существующие приложения, вызывающие исходную версию.Existing apps calling the original version number will remain unaffected by the change. Сведения о продолжительности поддержки API см. в политике поддержки Microsoft Graph.See the Microsoft Graph support policy for information about how long a version of the API is supported.

Критическое изменение — это изменение формата запроса или ответа, при котором удаляется или меняется текущее документированное поведение либо удаляется элемент определения ресурса.A breaking change is a change in the format of a request or response that removes or alters an existing documented behavior or removes an element of a resource's definition. Добавление действий, свойств, аспектов или ссылок на ресурсы не является критическим изменением.It is not a breaking change to add additional actions, properties, facets, or references to a resource.

Возможно, время от времени API будет предоставлять дополнительные недокументированные функции.It is possible that the API will expose additional undocumented features from time to time. Эти функции не следует использовать, пока они не будут документированы.These features should not be utilized until they are documented. Не ожидайте, что текущее поведение, не соответствующее документации, останется без изменений.Do not assume that current behavior that deviates from the documentation will persist.

Мы продолжим вносить в текущую версию API некритические изменения, включая добавление аспектов, свойств и ресурсов к API.We will continue to make non-breaking changes to the existing version of the API, including adding facets, properties, and resources to the API. Ниже перечислены требования к коду, вызывающему API.As such, any code calling the API needs to:

  • Код должен быть устойчивым к добавлению свойств в ответы JSON.Be resilient to additional properties being added to JSON responses. Их можно игнорировать.Ignoring them is OK.
  • Код не должен зависеть от порядка свойств, возвращаемых в ответах JSON.Have no dependency on the order of properties returned in JSON responses.
  • Код должен использовать только задокументированные пути API, ресурсы, свойства и перечисляемые значения.Use documented API paths, resources, properties, and enumerated values only. Согласованность недокументированных значений не гарантируется.Non-documented values are not guaranteed to remain consistent.
  • Все URL-адреса, которые возвращает API OneDrive, должны рассматриваться как непрозрачные.All URLs returned by OneDrive API should be treated as opaque URLs. Приложение не должно делать предположений о формате или параметрах в этих URL-адресах.Your app should not make any assumptions about format or parameters in these URLs. Они могут быть изменены без предварительного уведомления.Features are subject to change without notice.

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

В OneDrive есть ограничения, которые гарантируют, что пользователи и приложения не окажут негативного влияния на работу других пользователей.OneDrive has limits in place to make sure that individuals and apps do not adversely affect the experience of other users. Если действие нарушает ограничения OneDrive, то в течение некоторого времени запросы API отклоняются.When an activity exceeds OneDrive's limits, API requests will be rejected for a period of time. OneDrive также может возвращать заголовок Retry-After с временем (в секундах) ожидания приложения перед отправкой дополнительных запросов.OneDrive may also return a Retry-After header with the number of seconds your app should wait before sending more requests.

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

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

Примечание. В OneDrive хранятся записные книжки OneNote, но не следует использовать API OneDrive для работы с ними.Note: Although OneDrive stores OneNote notebooks, you shouldn't use the OneDrive API to work with OneNote notebooks. Вместо этого используйте API OneNote.Instead, use the OneNote API.

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

Стремясь обеспечить неизменно высокое качество нашей документации, мы разработали процесс тестирования примеров при каждой отправке материалов.As part of our commitment to high quality documentation, we've developed a process through which the samples and examples in our documentation are tested for validity as part of every check-in. Мы называем это непрерывной проверкой документации.We call this continuous documentation validation.

При каждом изменении документации мы проверяем, все ли работает так, как описано в документации к службе.Each time a change to our documentation is made, we validate that everything works as documented in the service. При создании новой сборки службы мы также проверяем работоспособность примеров в нашей документации.When we create a new build of the service, we validate that the examples in our documentation also continue to work. Это помогает нам гарантировать, что все документированные возможности работают надлежащим образом, по мере выхода новых обновлений.This helps us ensure that everything we document works and works as expected even as new updates are made available.

Сведения о последних сборках см. на странице состояния сборок AppVeyor для нашего репозитория документации.For the latest build details, check out the AppVeyor build status page for our documentation repository.

Указанные ниже статьи содержат общие сведения о других понятиях, применимых к API OneDrive.The following topics contain high-level overviews of other concepts that apply to the OneDrive API.