Microsoft Graph 中的 OneDrive 和 SharePointOneDrive and SharePoint in Microsoft Graph

文档验证和生成状态Documentation validation and build status

OneDrive REST API 是 Microsoft Graph API 的一部分,它允许应用程序连接到存储在 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 for Business、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 服务 API Microsoft GraphOneDrive APIs are a part of the Microsoft Graph, a common API for Microsoft services.

对于在 Microsoft Graph 外使用 OneDrive API 的现有解决方案,或定位 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.

OneDrive REST API 提供几个顶级类型在 API 中表示可寻址资源:OneDrive's REST API provides a few top-level types that represent addressable resources in the API:

下面的示例展示了 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:

  • 属性(如 idname)公开简单值。Properties (like id and name) expose simple values.
  • Facet(如 FilePhoto)公开复杂值。 如果项具有 Facet,通常用于指明项的行为或功能以及相关属性。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 children) point to collections of other resources.

可以将许多请求定制为添加其他数据,或从响应中删除未使用的属性。 OneDrive 使用可选查询参数启用此功能。 在整个文档中,每个请求都提供了支持参数的更多上下文。Many requests can be tailored to include additional data or remove unused properties from the responses. OneDrive uses optional query parameters to enable this functionality. Throughout the documentation, each request provides more context about which parameters are supported.

默认情况下,虽然大部分属性和 Facet 都会返回,但所有引用都会被隐藏。 为了提高效率,建议为关注的数据指定 selectexpandBy default, most properties and facets are returned while all references are hidden. For efficiency, we recommend that you specify select and expand for the data you care about.

有关资源和 Facet 的详细信息,请参阅资源FacetFor details about resources and facets, see Resources and Facets.

Microsoft Graph 根资源Microsoft Graph root resources

在 Microsoft Graph 中,可以通过多个根资源实现 OneDrive 功能。 这些资源对应于 OneDrive 和 SharePoint 文档库在 Office 365 中的位置。 Microsoft Graph 中的以下实体可能包含一个或多个驱动器:Within the Microsoft Graph, the OneDrive functionality is available from several root resources. These resources correspond to where OneDrive and SharePoint document libraries are available within Office 365. The follow entities in Microsoft Graph may contain one or more drives:

EntityEntity 示例路径Example Path
用户User /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}

OneDrive 根资源OneDrive 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} 按 ID 访问特定 driveAccess a specific drive by its ID.
/drives/{drive-id}/root/children 列出特定 drive 的根中的项。List items in the root of a specific drive.
/drive/items/{item-id} 按 ID 访问 driveItemAccess a driveItem by its ID.
/drive/special/{special-id} 按已知名称访问已知文件夹Access a known folder by its known name.
/shares/{share-id} shareId 或共享 URL 访问 driveItemAccess a driveItem by its shareId or a sharing URL.

驱动器中基于路径的寻址Path-based addressing within a drive

可以使用唯一标识符或项在驱动器层次结构中的位置(即用户路径)寻址 driveItem 。 在 API 请求中,可以使用冒号转换 API 路径空间用户路径空间。 此语法对可通过 API 空间寻址的所有 driveItem 都有效。A driveItem can be addressed by either a unique identifier or where that item exists in the drive's hierarchy (i.e. user path). Within an API request, a colon can be used to shift between API path space and user path space. This syntax is valid for any driveItem addressed via the API space.

也可以在文件系统路径空间的末尾使用冒号,转换回 API 路径空间。 请确保 URL 中的用户数据符合寻址和路径编码要求。You can also transition back to API path space by using a colon at the end of the file system path space. Ensure user data within the URL follows the addressing and path encoding requirements.

PathPath 资源Resource
/drive/root:/path/to/file 按根下路径访问 driveItemAccess a driveItem by path under the root.
/drive/items/{item-id}:/path/to/file 按相对其他项的路径访问 driveItemAccess 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 children when accessing by path relative to another item.

共享文件夹和远程项Shared folders and remote items

OneDrive 个人版允许用户将其他驱动器中的一个或多个共享项添加到自己的 OneDrive。这些共享项在 children 集合中显示为具有 remoteItem FacetdriveItemOneDrive personal allows a user to add one or more shared items from another drive to their OneDrive. These shared items appear as a driveItem in the children collection with a remoteItem facet.

此外,从目标驱动器外返回的项也具有 remoteItem Facet。 这些项还可以通过搜索最近使用过的文件与我共享的内容方法返回。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 on working with shared folders and remote items, see Remote items and shared folders.

共享和权限Sharing and permissions

OneDrive 和 SharePoint 的最常见操作之一便是与其他人共享项。OneDrive 允许应用创建共享链接向驱动器中存储的项添加权限并发送邀请One of the most common actions for OneDrive and SharePoint is sharing items with other people. OneDrive allows your app to create sharing links, add permissions, and send invitations to items stored in a drive.

OneDrive 还允许应用直接通过共享链接访问共享内容OneDrive also provides a way for your app to access shared content directly from the sharing link.

若要详细了解如何共享和使用共享内容,请参阅共享 OneDrive 中的项For more details on how to share and consume shared content, see Sharing items in OneDrive.

Webhook 和通知Webhooks and notifications

OneDrive 支持在 OneDrive 内容发生变化时发送 webhook 推送通知。 应用可以使用这些通知近乎实时地跟踪更改,而不用轮询服务器来发现更改。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

API 兼容性API compatibility

OneDrive 将不断发展并增添更多功能。 API 路径中包含版本号,旨在保护应用不受重大更改影响。 如果重大更改为必需,API 版本号将会递增。 调用原始版本号 API 的现有应用将不受更改影响。 若要了解 API 版本的受支持期限,请参阅 Microsoft Graph 支持策略OneDrive will continue to evolve and gain additional functionality. The API path includes a version number to protect your app against breaking changes. 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. See the Microsoft Graph support policy for information about how long a version of the API is supported.

重大更改是指请求或响应的格式发生更改,删除或更改了现有的_记录_行为,或删除了资源的定义元素。 添加其他操作、属性、Facet 或资源引用不属于重大更改。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 添加 Facet、属性和资源。 因此,调用 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. 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.
  • 应将 OneDrive API 返回的所有 URL 都视为非跳转 URL。 应用不得对这些 URL 中的格式或参数做出任何假设。 它们可能会发生变更,恕不另行通知。All URLs returned by OneDrive API should be treated as opaque URLs. Your app should not make any assumptions about format or parameters in these URLs. They are subject to change without notice.

限制Throttling

为了确保个人和应用不会对其他用户的体验造成不利影响,OneDrive 设定了限制。 当活动超出 OneDrive 设定的限制时,API 请求将在一段时间内遭拒。 OneDrive 可能还会返回 Retry-After 头,其中包含应用在发送更多请求前应等待的秒数。OneDrive has limits in place to make sure that individuals and apps do not adversely affect the experience of other users. When an activity exceeds OneDrive's limits, API requests will be rejected for a period of time. 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

处理 OneNote 笔记本Working with OneNote Notebooks

注意: 虽然 OneDrive 存储 OneNote 笔记本,但不得使用 OneDrive API 处理 OneNote 笔记本。Note: Although OneDrive stores OneNote notebooks, you shouldn't use the OneDrive API to work with OneNote notebooks. 应改用 OneNote APIInstead, 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.

下列主题简要概述了 OneDrive API 的其他概念。The following topics contain high level overviews of other concepts that apply to the OneDrive API.