在 Microsoft Graph 中使用文件Working with files in Microsoft Graph

可以使用 Microsoft Graph 创建一个跨 OneDrive、OneDrive for Business 和 SharePoint 文档库与文件连接的应用程序。You can use Microsoft Graph to create an app that connects with files across OneDrive, OneDrive for Business, and SharePoint document libraries. 通过 Microsoft Graph,可以使用存储在 Office 365 中的文件构建各种体验,从仅存储用户文档到复杂的文件共享方案均可。With Microsoft Graph, you can build a variety of experiences with files stored in Office 365, from simply storing user documents to complex file sharing scenarios.

Microsoft Graph 公开可用于文件的两个资源类型:Microsoft Graph exposes two resource types for working with files:

  • 驱动器 - 表示文件的逻辑容器,例如文档库或用户的 OneDrive。Drive - Represents a logical container of files, like a document library or a user's OneDrive.
  • DriveItem - 表示驱动器中的项目,例如文档、照片、视频或文件夹。DriveItem - Represents an item within a drive, like a document, photo, video, or folder.

大部分与文件的交互通过与 DriveItem 资源的交互实现。以下是一个 DriveItem 资源示例:Most of the interaction with files occurs through interaction with DriveItem resources. The following is an example of a DriveItem resource:

{
  "@content.downloadUrl":"https://public-sn3302.files.1drv.com/y2pcT7OaUEExF7EHOlpTjCE55mIUoiX7H3sx1ff6I-nP35XUTBqZlnkh9FJhWb_pf9sZ7LEpEchvDznIbQig0hWBeidpwFkOqSKCwQylisarN6T0ecAeMvantizBUzM2PA1",
  "createdDateTime": "2016-09-16T03:37:04.72Z",
  "cTag": "aYzpENDY0OEYwNkM5MUQ5RDNEITU0OTI3LjI1Ng",
  "eTag": "aRDQ2NDhGMDZDOTFEOUQzRCE1NDkyNy4w",
  "id":"D4648F06C91D9D3D!54927",
  "lastModifiedBy": {
    "user": {
      "displayName": "Daron Spektor",
      "id": "d4648f06c91d9d3d"
    }
  },
  "name":"BritishShorthair.jpg",
  "size":35212,
  "image":{
    "height":398,
    "width":273
  },
  "file": {
    "hashes":{
      "sha1Hash":"wmgPQ6jrSeMX7JP1XmstQEGM2fc="
    }
  }
}

驱动器DriveItem 资源通过三种不同的方式公开数据:Drive and DriveItem resources expose data in three different ways:

  • 属性(像 idname)公开简单的值(字符串、数字、布尔值)。Properties (like id and name) expose simple values (strings, numbers, Booleans).
  • Facet(像文件照片)公开复杂的值。存在的文件文件夹 Facet 表示 DriveItem 的行为和属性。Facets (like file and photo) expose complex values. The presence of file or folder facets indicates behaviors and properties of a DriveItem.
  • 引用(像子项缩略图)指向其他资源的集合。References (like children and thumbnails) point to collections of other resources.

经常访问的资源Commonly accessed resources

文件交互的大多数 API 请求将使用以下其中一种基础资源来访问驱动器DriveItemMost API requests for file interactions will use one of these base resources to access a Drive or DriveItem.

路径Path 资源Resource
/me/drive 用户的 OneDriveUser's OneDrive
/me/drives 枚举用户可用的 OneDrive 资源。Enumerate OneDrive resources available to the user.
/drives/{drive-id} 通过驱动器 ID 访问特定驱动器Access a specific Drive by the drive's ID.
/drives/{drive-id}/root/children 枚举特定驱动器根目录中的 DriveItem 资源。Enumerate the DriveItem resources in the root of a specific Drive.
/me/drive/items/{item-id} 通过其唯一 ID 访问用户 OneDrive 中的 DriveItemAccess a DriveItem in the user's OneDrive by its unique ID.
/me/drive/special/{special-id} 通过其已知名称访问用户 OneDrive 中的特殊(命名)文件夹。Access a special (named) folder in the user's OneDrive by its known name.
/users/{user-id}/drive 通过使用用户的唯一标识符访问另一个用户的 OneDrive 。Access another user's OneDrive by using the user's unique ID.
/groups/{group-id}/drive 通过组的唯一 ID 访问组的默认文档库。Access the default document library for a group by the group's unique ID.
/shares/{share-id} 通过其 sharedId 或共享 URL 访问 DriveItemAccess a DriveItem by its sharedId or sharing URL.
/sites/{site-id}/drive 访问给定 SharePoint 网站的默认驱动器(文档库)Access the default drive (document library) for the given site.
/sites/{site-id}/drives 枚举给定 SharePoint 网站下的驱动器(文档库)Enumerate the Drives (document libraries) under the given SharePoint site

除了通过唯一 ID 在驱动器内查找 DriveItem,应用还可以通过已知资源中的相对路径查找 DriveItem。要使用路径进行查找,请使用冒号 (:) 字符对相对路径转义。此表提供了通过不同的方法使用冒号字符来按路径查找项目的示例。In addition to addressing a DriveItem within a Drive by unique ID, your app can also address a DriveItem by relative path from a known resource. To address using a path, the colon (:) character is used to escape the relative path. This table provides an example of different ways to use the colon character to address an item by path.

路径Path 资源Resource
/me/drive/root:/path/to/file 通过相对于用户的 OneDrive 根文件夹的路径访问 DriveItemAccess a DriveItem by path relative to the user's OneDrive root folder.
/me/drive/items/{item-id}:/path/to/file 通过相对于另一项的路径访问 DriveItem(具有文件夹 facet 的 DriveItem)。Access a DriveItem by path relative to another item (a DriveItem with a folder facet).
/me/drive/root:/path/to/folder:/children 通过相对于用户的 OneDrive 根文件夹的路径列出 DriveItem 的子项。List the children of a DriveItem by path relative to the root of the user's OneDrive.
/me/drive/items/{item-id}:/path/to/folder:/children 按照相对于另一项的路径列出 DriveItem 的子项。List the children of a DriveItem by path relative to another item.

驱动器资源Drive resource

驱动器资源 是用户的 OneDrive 或 SharePoint 文档库内的顶级对象。The Drive resource is the top-level object within a user's OneDrive or a SharePoint document library. 几乎所有的文件操作都从查找特定驱动器资源开始。Nearly all files operations will start by addressing a specific drive resource.

可以通过驱动器的唯一 ID 或 用户 或组织的默认驱动器查找驱动器资源。 A drive resource can be addressed either by the drive's unique ID or by the default drive for a User, Group, or organization.

DriveItem 资源DriveItem resource

DriveItems 是驱动器文件系统内的对象。访问方法有:使用 /items/{item-id} 语法通过其 id 访问,或使用 /root:/path/to/item/ 语法通过其文件系统路径访问。DriveItems are the objects inside a drive's file system. They can be accessed by their id by using /items/{item-id} syntax, or by their file system path using the /root:/path/to/item/ syntax.

DriveItems 拥有多个 Facet,可提供有关项目标识和功能的数据。DriveItems have facets that provide data about the item's identity and capabilities.

具有文件夹 Facet 的 DriveItem 充当项目的容器,并且具有指向文件夹下的项目集合的子项引用。DriveItems with a folder facet act as containers of items, and have a children reference, which points to a collection of items under the folder.

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

OneDrive 个人版用户可以向他们自己的 OneDrive 中添加其他驱动器的一个或多个共享项目。这些共享项目在具有 remoteItem facet 的子项集合中显示为 DriveItemOneDrive personal users can add one or more shared items from another drive to their own OneDrive. These shared items appear as a DriveItem in the children collection with a remoteItem facet.

有关使用共享文件夹和远程项目的详细信息,请参阅 Remote items and shared folders(远程项目和共享文件夹)。For more information about working with shared folders and remote items, see Remote items and shared folders.

共享和权限Sharing and permissions

OneDrive 和 SharePoint 文档库最常见的操作之一是与其他人共享内容。Microsoft Graph 使你的应用程序可以创建 共享链接添加权限并发送邀请 到驱动器中的项目。One of the most common actions for OneDrive and SharePoint document libraries is sharing content with other people. Microsoft Graph allows your app to create sharing links, add permissions and send invitations to items in a drive.

Microsoft Graph 还为应用提供了一种直接从共享链接 访问共享内容 的方法。Microsoft Graph also provides a way for your app to access shared content directly from a sharing link.