DriveItem 资源类型DriveItem resource type

driveItem 资源代表文件、文件夹或存储在驱动器中的 其他项。OneDrive 和 SharePoint 中的所有文件系统对象将作为 driveItem 资源返回。The driveItem resource represents a file, folder, or other item stored in a drive. All file system objects in OneDrive and SharePoint are returned as driveItem resources.

driveItem 资源的寻址方式主要有两种:There are two primary ways of addressing a driveItem resource:

  • 通过 driveItem 唯一标识符使用 drive/items/{item-id} 的方式By the driveItem unique identifier using drive/items/{item-id}
  • 通过使用文件系统路径 /drive/root:/path/to/file 的方式By file system path using /drive/root:/path/to/file

DriveItem 资源拥有作为属性进行模块化的多个 Facet,用于提供 driveItem 的标识和功能相关数据。例如:DriveItem resources have facets modeled as properties that provide data about the driveItem's identities and capabilities. For example:

  • 文件夹具有文件夹 facetFolders have a folder facet
  • 文件具有文件 facetFiles have a file facet.
  • 除了文件 facet,图像还具有图像 facetImages have an image facet in addition to their file facet.
  • 使用照相机拍摄的图像(照片)具有照片 facet,用于将项标识为照片,并提供照片的拍摄时间和拍摄所用设备等属性。Images taken with a camera (photos) have a photo facet that identifies the item as a photo and provides the properties of when the photo was taken and with what device.

具有文件夹 Facet 的项目充当项目的容器,因此具有指向文件夹下的 driveItems 集合的 children 引用。Items with the folder facet act as containers of items and therefore have a children reference pointing to a collection of driveItems under the folder.

JSON 表示形式JSON representation

下面是 driveItem 资源的 JSON 表示形式。Here is a JSON representation of a driveItem resource.

driveItem 资源由 baseItem 派生并继承该资源的属性。The driveItem resource is derived from baseItem and inherits properties from that resource.

{
  "audio": { "@odata.type": "microsoft.graph.audio" },
  "content": { "@odata.type": "Edm.Stream" },
  "cTag": "string (etag)",
  "deleted": { "@odata.type": "microsoft.graph.deleted"},
  "description": "string",
  "file": { "@odata.type": "microsoft.graph.file" },
  "fileSystemInfo": { "@odata.type": "microsoft.graph.fileSystemInfo" },
  "folder": { "@odata.type": "microsoft.graph.folder" },
  "image": { "@odata.type": "microsoft.graph.image" },
  "location": { "@odata.type": "microsoft.graph.geoCoordinates" },
  "package": { "@odata.type": "microsoft.graph.package" },
  "photo": { "@odata.type": "microsoft.graph.photo" },
  "publication": {"@odata.type": "microsoft.graph.publicationFacet"},
  "remoteItem": { "@odata.type": "microsoft.graph.remoteItem" },
  "root": { "@odata.type": "microsoft.graph.root" },
  "searchResult": { "@odata.type": "microsoft.graph.searchResult" },
  "shared": { "@odata.type": "microsoft.graph.shared" },
  "sharepointIds": { "@odata.type": "microsoft.graph.sharepointIds" },
  "size": 1024,
  "specialFolder": { "@odata.type": "microsoft.graph.specialFolder" },
  "video": { "@odata.type": "microsoft.graph.video" },
  "webDavUrl": "string",

  /* relationships */
  "children": [{ "@odata.type": "microsoft.graph.driveItem" }],
  "createdByUser": { "@odata.type": "microsoft.graph.user" },
  "lastModifiedByUser": { "@odata.type": "microsoft.graph.user" },
  "permissions": [ {"@odata.type": "microsoft.graph.permission"} ],
  "thumbnails": [ {"@odata.type": "microsoft.graph.thumbnailSet"}],
  "versions": [ {"@odata.type": "microsoft.graph.driveItemVersion"}],

  /* inherited from baseItem */
  "id": "string (identifier)",
  "createdBy": {"@odata.type": "microsoft.graph.identitySet"},
  "createdDateTime": "String (timestamp)",
  "eTag": "string",
  "lastModifiedBy": {"@odata.type": "microsoft.graph.identitySet"},
  "lastModifiedDateTime": "String (timestamp)",
  "name": "string",
  "parentReference": {"@odata.type": "microsoft.graph.itemReference"},
  "webUrl": "string",

  /* instance annotations */
  "@microsoft.graph.conflictBehavior": "string",
  "@microsoft.graph.downloadUrl": "url",
  "@microsoft.graph.sourceUrl": "url"
}

属性Properties

属性Property 类型Type 说明Description
audioaudio audioaudio 音频元数据(如果此项是一个音频文件)。只读。Audio metadata, if the item is an audio file. Read-only.
contentcontent Stream 内容流(如果此项表示一个文件)。The content stream, if the item represents a file.
createdBycreatedBy identitySetidentitySet 识别创建项目的用户、设备和应用程序。只读。Identity of the user, device, and application which created the item. Read-only.
createdDateTimecreatedDateTime DateTimeOffsetDateTimeOffset 创建项的日期和时间。只读。Date and time of item creation. Read-only.
cTagcTag StringString 项目内容的 eTag。如果只有元数据更改,此 eTag 不会更改。注意 如果项目是文件夹,则不返回此属性。只读。An eTag for the content of the item. This eTag is not changed if only the metadata is changed. Note This property is not returned if the item is a folder. Read-only.
deleteddeleted deleteddeleted 有关项目删除状态的信息。只读。Information about the deleted state of the item. Read-only.
说明description 字符串String 提供项的用户可见的说明。读写。仅在 OneDrive 个人版上Provides a user-visible description of the item. Read-write. Only on OneDrive Personal
eTageTag StringString 整个项目(元数据和内容)的 eTag。只读。eTag for the entire item (metadata + content). Read-only.
filefile filefile 文件元数据(如果此项是一个文件)。只读。File metadata, if the item is a file. Read-only.
fileSystemInfofileSystemInfo fileSystemInfofileSystemInfo 客户端上的文件系统信息。读写。File system information on client. Read-write.
folderfolder folderfolder 文件夹元数据(如果此项是一个文件夹)。只读。Folder metadata, if the item is a folder. Read-only.
idid 字符串String 项在驱动器中的唯一标识符。只读。The unique identifier of the item within the Drive. Read-only.
imageimage imageimage 图像元数据(如果此项是一个图像)。只读。Image metadata, if the item is an image. Read-only.
lastModifiedBylastModifiedBy identitySetidentitySet 上次修改项目的用户、设备和应用程序的标识。只读。Identity of the user, device, and application which last modified the item. Read-only.
lastModifiedDateTimelastModifiedDateTime DateTimeOffsetDateTimeOffset 上次修改项目的日期和时间。只读。Date and time the item was last modified. Read-only.
locationlocation geoCoordinatesgeoCoordinates 位置元数据(如果此项包含位置数据)。只读。Location metadata, if the item has location data. Read-only.
namename 字符串String 项目名称(文件名和扩展名)。读写。The name of the item (filename and extension). Read-write.
package packagepackage 如果存在,则表示此项是一个包,而不是文件夹或文件。包被视为某些上下文中的文件和其他上下文中的文件夹。只读。If present, indicates that this item is a package instead of a folder or file. Packages are treated like files in some contexts and folders in others. Read-only.
parentReferenceparentReference itemReferenceitemReference 父信息(如果此项具有父级)。读写。Parent information, if the item has a parent. Read-write.
photophoto [照片][]photo 照片元数据(如果此项包含照片)。只读。Photo metadata, if the item is a photo. Read-only.
publicationpublication publicationFacetpublicationFacet 在支持此类操作的位置提供有关某个项目的已发布或签出状态信息。Provides information about the published or checked-out state of an item, in locations that support such actions. 默认情况下,不会返回此属性。This property is not returned by default. 只读。Read-only.
remoteItemremoteItem remoteItemremoteItem 远程项目数据(如果此项是从驱动器共享的项目,而不是被访问的项目)。只读。Remote item data, if the item is shared from a drive other than the one being accessed. Read-only.
rootroot [根][]root 如果此属性为非 NULL,则表明 driveItem 是驱动器中最上面的 driveItem。If this property is non-null, it indicates that the driveItem is the top-most driveItem in the drive.
searchResultsearchResult searchResultsearchResult 搜索元数据(如果此项目来自搜索结果)。只读。Search metadata, if the item is from a search result. Read-only.
sharedshared [共享][]shared 表示此项已与他人共享,并提供有关项目共享状态的信息。只读。Indicates that the item has been shared with others and provides information about the shared state of the item. Read-only.
sharepointIdssharepointIds sharepointIdssharepointIds 返回对 SharePoint REST 兼容性有用的标识符。只读。Returns identifiers useful for SharePoint REST compatibility. Read-only.
sizesize Int64Int64 项目大小,以字节为单位。只读。Size of the item in bytes. Read-only.
specialFolderspecialFolder specialFolderspecialFolder 如果当前项同时也是一个特殊的文件夹,则返回此 facet。只读。If the current item is also available as a special folder, this facet is returned. Read-only.
videovideo [视频][]video 视频元数据(如果此项是一个视频)。只读。Video metadata, if the item is a video. Read-only.
WebDavUrlwebDavUrl StringString 项的可兼容 WebDAV 的 URL。WebDAV compatible URL for the item.
WebUrlwebUrl StringString 在浏览器中显示此资源的 URL。只读。URL that displays the resource in the browser. Read-only.

注意: ETag 和 cTag 属性在容器(文件夹)中以不同的方式工作。更改任意文件夹后代的内容或元数据时,也会修改 CTag 值。除了从后代派生的属性(例如 childCountlastModifiedDateTime),仅在更改文件夹的属性时修改 eTag 值。Note: The eTag and cTag properties work differently on containers (folders). The cTag value is modified when content or metadata of any descendant of the folder is changed. The eTag value is only modified when the folder's properties are changed, except for properties that are derived from descendants (like childCount or lastModifiedDateTime).

关系Relationships

关系Relationship 类型Type 说明Description
childrenchildren driveItem 集合driveItem collection 包含项目直接子项的 Item 对象的集合。仅表示文件夹的项目包含子项。只读。可为 Null。Collection containing Item objects for the immediate children of Item. Only items representing folders have children. Read-only. Nullable.
createdByUsercreatedByUser [用户][]user 创建了项的用户的身份。Identity of the user who created the item. 只读。Read-only.
lastModifiedByUserlastModifiedByUser [用户][]user 上次修改项的用户的身份。Identity of the user who last modified the item. 只读。Read-only.
listItemlistItem listItemlistItem 在 SharePoint 中,关联的文档库列表项的驱动器。For drives in SharePoint, the associated document library list item. 只读。Read-only. 可为 Null。Nullable.
permissionspermissions permission 集合permission collection 项目的权限集。只读。可为 Null。The set of permissions for the item. Read-only. Nullable.
缩略图thumbnails thumbnailSet 集合thumbnailSet collection 包含与项目关联的 ThumbnailSet 对象的集合。有关详细信息,请参阅 获取缩略图只读。可为 Null。Collection containing ThumbnailSet objects associated with the item. For more info, see getting thumbnails. Read-only. Nullable.
版本versions driveItemVersion集合driveItemVersion collection 早期版本的项目列表。The list of previous versions of the item. 有关详细信息,请参阅获取早期版本For more info, see getting previous versions. 只读。Read-only. 可为 Null。Nullable.
workbookworkbook workbookworkbook 对于的 Excel 电子表格文件,访问工作簿 API 来处理电子表格的内容。For files that are Excel spreadsheets, accesses the workbook API to work with the spreadsheet's contents. 可为 Null。Nullable.

实例属性Instance Attributes

实例属性是具有特殊行为的属性。这些属性是临时的,并且 a) 定义服务应执行的行为或 b) 提供短期的属性值,例如过期项目的下载 URL。Instance attributes are properties with special behaviors. These properties are temporary and either a) define behavior the service should perform or b) provide short-term property values, like a download URL for an item that expires.

属性名称Property name 类型Type 说明Description
@microsoft.graph.conflictBehavior@microsoft.graph.conflictBehavior stringstring 为创建新项目的操作解决冲突的行为。你可以使用值 failreplacerename。PUT 的默认值是replace。绝不会返回包含该批注的项目。只写。The conflict resolution behavior for actions that create a new item. You can use the values fail, replace, or rename. The default for PUT is replace. An item will never be returned with this annotation. Write-only.
@microsoft.graph.downloadUrl@microsoft.graph.downloadUrl stringstring 一个可用于下载此文件的内容的 URL。不需要使用此 URL 进行身份验证。只读。A URL that can be used to download this file's content. Authentication is not required with this URL. Read-only.
@microsoft.graph.sourceUrl@microsoft.graph.sourceUrl stringstring 发出 PUT 请求时,此实例批注可用于指示服务下载 URL 内容并将其存储为文件。只写。When issuing a PUT request, this instance annotation can be used to instruct the service to download the contents of the URL, and store it as the file. Write-only.

注意:@microsoft.graph.downloadUrl 值是一个短期 URL,不能缓存。此 URL 在失效前只能使用很短的时间(1 小时)。Note: The @microsoft.graph.downloadUrl value is a short-lived URL and can't be cached. The URL will only be available for a short period of time (1 hour) before it is invalidated.

方法Methods

方法Method REST 路径REST Path
获取项目Get item GET /drive/items/{item-id}
列出子项List children GET /drive/items/{item-id}/children
列出版本List versions GET /drive/items/{item-id}/versions
创建项目Create item POST /drive/items/{item-id}/children
更新项目Update item PATCH /drive/items/{item-id}
上载内容Upload content PUT /drive/items/{item-id}/content
下载内容Download content GET /drive/items/{item-id}/content
下载特定格式文件Download specific file format GET /drive/items/{item-id}/content?format={format}
删除项Delete item DELETE /drive/items/{item-id}
移动项目Move item PATCH /drive/items/{item-id}
复制项目Copy item POST /drive/items/{item-id}/copy
搜索项目Search items GET /drive/items/{item-id}/search(q='text')
列出驱动器中的更改List changes in a drive GET /drive/root/delta
列出缩略图List thumbnails GET /drive/items/{item-id}/thumbnails
创建共享链接Create sharing link POST /drive/items/{item-id}/createLink
添加权限Add permissions POST /drive/items/{item-id}/invite
列出权限List permissions GET /drive/items/{item-id}/permissions
删除权限Delete permission DELETE /drive/items/{item-id}/permissions/{perm-id}
预览项Preview item POST /drive/items/{item-id}/preview

注解Remarks

在 OneDrive for Business 或 SharePoint 文档库中,如果 driveItem 具有folder Facet,则不返回 cTag 属性。In OneDrive for Business or SharePoint document libraries, the cTag property is not returned, if the driveItem has a folder facet.