Microsoft Graph 中的 OneDrive 和 SharePoint

项目
04/08/2023

OneDrive REST API 是 Microsoft Graph API 的一部分，它允许应用程序连接到存储在 OneDrive 和 SharePoint 中的内容。 REST API 在 OneDrive、OneDrive for Business、SharePoint 文档库和 Office 组之间共享，以便应用程序在其中任一位置使用同一代码灵活读取和存储内容。

这些 REST API 属于常见 Microsoft 服务 API Microsoft Graph。

对于在 Microsoft Graph 外使用 OneDrive API 的现有解决方案，或定位 SharePoint Server 2016 的解决方案，请参阅直接终结点差异，获取更多上下文，以便于阅读本文档。

入门

若要快速试用 Microsoft Graph 并访问文件，请参阅 Graph 浏览器和 Microsoft Graph 快速入门。

OneDrive REST API 提供几个顶级类型在 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）公开简单值。
Facet（如 File 和 Photo）公开复杂值。如果项具有 Facet，通常用于指明项的行为或功能以及相关属性。
资源（如 children）指向其他资源的集合。

可以将许多请求定制为添加其他数据，或从响应中删除未使用的属性。 OneDrive 使用可选查询参数启用此功能。在整个文档中，每个请求都提供了支持参数的更多上下文。

默认情况下，虽然大部分属性和 Facet 都会返回，但所有引用都会被隐藏。为了提高效率，建议为关注的数据指定 select 和 expand。

有关资源和 Facet 的详细信息，请参阅资源和 Facet。

Microsoft Graph 根资源

在 Microsoft Graph 中，可以通过多个根资源实现 OneDrive 功能。这些资源对应于 OneDrive 和 SharePoint 文档库在 Office 365 中的位置。 Microsoft Graph 中的以下实体可能包含一个或多个驱动器：

实体	示例路径
用户	`/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}`	按 ID 访问特定 drive。
`/drives/{drive-id}/root/children`	列出特定 drive 的根中的项。
`/drive/items/{item-id}`	按 ID 访问 driveItem。
`/drive/special/{special-id}`	按已知名称访问已知文件夹。
`/shares/{share-id}`	按 shareId 或共享 URL 访问 driveItem。

驱动器中基于路径的寻址

可以使用唯一标识符或项在驱动器层次结构中的位置（即用户路径）寻址 driveItem 。在 API 请求中，可以使用冒号转换 API 路径空间和用户路径空间。此语法对可通过 API 空间寻址的所有 driveItem 都有效。

也可以在文件系统路径空间的末尾使用冒号，转换回 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 Facet。这些项还可以通过搜索、最近使用过的文件、与我共享的内容方法返回。

若要详细了解如何使用共享文件夹和远程项，请参阅远程项和共享文件夹。

OneDrive 和 SharePoint 的最常见操作之一便是与其他人共享项。 OneDrive 允许应用创建共享链接、向驱动器中存储的项添加权限并发送邀请。

OneDrive 还允许应用直接通过共享链接访问共享内容。

若要详细了解如何共享和使用共享内容，请参阅共享 OneDrive 中的项。

Webhook 和通知

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

编程注意事项

API 兼容性

OneDrive 将不断发展并增添更多功能。 API 路径中包含版本号，旨在保护应用不受重大更改影响。如果重大更改为必需，API 版本号将会递增。调用原始版本号 API 的现有应用将不受更改影响。若要了解 API 版本的受支持期限，请参阅 Microsoft Graph 支持策略。

重大更改是指请求或响应的格式发生更改，删除或更改了现有的记录行为，或删除了资源的定义元素。添加其他操作、属性、Facet 或资源引用不属于重大更改。

API 可能会不时地公开其他未记录功能。不得使用这些未记录功能。请不要想当然地认为当前偏离文档的行为将会一直存在。

我们将继续对现有版本的 API 进行非重大更改，包括向 API 添加 Facet、属性和资源。因此，调用 API 的任何代码都需要：

应变处理 JSON 响应中添加的其他属性。可忽略它们。
不依赖 JSON 响应中返回的属性顺序。
仅使用记录的 API 路径、资源、属性和枚举值。未记录的值无法保证一致性。
应将 OneDrive API 返回的所有 URL 都视为非跳转 URL。应用不得对这些 URL 中的格式或参数做出任何假设。它们可能会发生变更，恕不另行通知。

限制

为了确保个人和应用不会对其他用户的体验造成不利影响，OneDrive 设定了限制。当活动超出 OneDrive 设定的限制时，API 请求将在一段时间内遭拒。 OneDrive 可能还会返回 Retry-After 头，其中包含应用在发送更多请求前应等待的秒数。

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

处理 OneNote 笔记本

注意：虽然 OneDrive 存储 OneNote 笔记本，但不得使用 OneDrive API 处理 OneNote 笔记本。应改用 OneNote API。

持续文档验证

为了兑现我们的高质量文档承诺，我们制定了一个流程，以测试我们文档中的样本和示例是否有效，能否纳入每次签入。我们将此流程称为“持续文档验证”。

每当文档有更改时，我们都会确认服务中的一切是否像记录一样正常运行。创建服务的新内部版本时，我们会验证文档中的示例是否继续有效。这有助于我们确保所记录的一切内容按预期方式正常运行，即使有新的更新，也不例外。

有关最新内部版本的详细信息，请查看我们文档存储库的 AppVeyor 生成状态页。

下列主题简要概述了 OneDrive API 的其他概念。

通过