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:

  • 文件夹具有 folder facetFolders have a folder facet
  • 文件具有 file facetFiles have a file facet.
  • 除了 file facet 之外,图像还具有 image facetImages have an image facet in addition to their file facet.
  • 使用照相机拍摄的图像(照片)具有 photo 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.

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

属性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.
descriptiondescription 字符串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 StringString 项在驱动器中的唯一标识符。只读。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 StringString 项目名称(文件名和扩展名)。读写。The name of the item (filename and extension). Read-write.
packagepackage 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 rootroot 如果此属性为非 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 sharedshared 表示此项已与他人共享,并提供有关项目共享状态的信息。只读。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 videovideo 视频元数据(如果此项是一个视频)。只读。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
activitiesactivities itemActivity 集合itemActivity collection 最近发生在此项上的活动的列表。The list of recent activities that took place on this item.
分析analytics itemAnalytics 资源itemAnalytics resource 此项目上发生的查看活动的相关分析。Analytics about the view activities that took place on this item.
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 useruser 创建了项的用户的身份。Identity of the user who created the item. 只读。Read-only.
lastModifiedByUserlastModifiedByUser useruser 上次修改项的用户的标识。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.
订阅subscriptions 订阅集合subscription collection 项目上的订阅集。The set of subscriptions on the item. 仅在驱动器根目录上支持。Only supported on the root of a drive.
缩略图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.
工作簿workbook 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,不能缓存。Note: The @microsoft.graph.downloadUrl value is a short-lived URL and can't be cached. 此 URL 在失效前只能使用很短的时间(1 小时)。The URL will only be available for a short period of time (1 hour) before it is invalidated. 删除用户的文件权限可能不会立即使 URL 无效。Removing file permissions for a user may not immediately invalidate the URL.

JSON 表示形式JSON representation

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

\*\*driveItem\*\* 资源由 [\*\*baseItem\*\*][baseItem] 派生并继承该资源的属性。The **driveItem** resource is derived from [**baseItem**][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 */
  "activities": [{"@odata.type": "microsoft.graph.itemActivity"}],
  "analytics": {"@odata.type": "microsoft.graph.itemAnalytics"},
  "children": [{ "@odata.type": "microsoft.graph.driveItem" }],
  "createdByUser": { "@odata.type": "microsoft.graph.user" },
  "lastModifiedByUser": { "@odata.type": "microsoft.graph.user" },
  "permissions": [ {"@odata.type": "microsoft.graph.permission"} ],
  "subscriptions": [ {"@odata.type": "microsoft.graph.subscription"} ],
  "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"
}

方法Methods

方法Method 返回类型Return Type 说明Description
获取项目Get item driveItemdriveItem 在驱动器中检索 DriveItem 的元数据。Retrieve the metadata for a DriveItem in a Drive.
获取分析结果Get analytics itemAnalyticsitemAnalytics 对此资源可获取分析。Get analytics for this resource.
按间隔获取活动Get activities by interval itemActivityStatitemActivityStat 在指定的时间间隔内获取 itemActivityStats 的集合。Get a collection of itemActivityStats within the specified time interval.
列出子项List children driveItem 集合collection of driveItem 在 DriveItem 的子项关系中返回 DriveItems 集合。Return a collection of DriveItems in the children relationship of a DriveItem.
列出版本List versions DriveItemVersion 集合collection of DriveItemVersion 检索当前用户驱动器中的文件的版本。Retrieves the versions of a file in the current user's drive.
创建项目Create item driveItemdriveItem 在指定的驱动器中创建一个 driveItem。Creates a driveItem in the specified drive.
更新项目Update item driveItemdriveItem 更新驱动器中的 driveItem。Updates a driveItem in the drive.
上传内容Upload content driveItemdriveItem 将内容上传到 driveItem。Uploads content to the driveItem.
下载内容Download content 下载 Urldownload Url 下载 driveItem 的内容。Downloads content of a driveItem.
下载特定文件格式Download specific file format 下载 Urldownload Url 下载具有特定格式的 driveItem 的内容。Downloads content of a driveItem with a specific format.
删除项Delete item 无内容No Content 删除 DriveItem。Deletes a driveItem.
移动项目Move item driveItemdriveItem 将 DriveItem 移动到父项。Move a DriveItem to a new parent item.
复制项目Copy item 有关如何监视复制操作进度的详细信息。details about how to monitor the progress of the copy 创建 driveItem(包括任何子项)的副本。Creates a copy of an driveItem (including any children).
搜索项目Search items driveItem 集合collection of driveItem 在项目层次结构中搜索与查询匹配的项目。Search the hierarchy of items for items matching a query.
列出驱动器中的更改List changes in a drive 三角链接delta link 列出驱动器中的任何更改。List any changes in the drive.
列出缩略图List thumbnails driveItem 集合colletion of driveItem 使用缩略图列出 driveItems。List driveItems with their thumbnails.
创建共享链接Create sharing link 共享链接sharing link 创建共享 driveItem 的链接。Create a link to share the driveItem.
添加权限Add permissions 权限集合collection of permission 向用户发送共享邀请。Sends a sharing ivite to a user.
列出权限List permissions 权限集合collection of permission 检索 driveItem 上的权限集合。Retrieves the collection of permissions on an driveItem.
删除权限Delete permission 无内容No Content 从 driveItem 中删除权限。Removes the permission from the driveItem.
获取 WebSocket 频道Get WebSocket channel 订阅subscription 使用 socket.io 接收驱动器的近实时更改通知。Receives near-real-time change notifications for a drive using socket.io.
预览项目Preview item json objectjson object 获取项目的短期可嵌入URL以呈现临时预览。Obtain short-lived embeddable URLs for an item in order to render a temporary preview.