driveItem resource type

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Represents a file, folder, or other item stored in a drive.

All file system objects in OneDrive and SharePoint are returned as driveItem resources. Items in SharePoint document libraries can be represented as listItem or driveItem resources.

There are two primary ways of addressing a driveItem resource:

  • By the driveItem unique identifier using drive/items/{item-id}
  • By file system path using /drive/root:/path/to/file

For more information, see addressing driveItems.

DriveItem resources have facets modeled as properties that provide data about the driveItem's identities and capabilities. For example:

  • Folders have a folder facet
  • Files have a file facet.
  • Images have an image facet in addition to their file 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.

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.

Note: In OneDrive for Business or SharePoint document libraries, the cTag property isn't returned, if the driveItem has a folder facet.

Methods

Method REST Path
Get item GET /drive/items/{item-id}
List activities GET /drive/items/{item-id}/activities
Get analytics GET /drive/items/{item-id}/analytics
Get activities by interval GET /drive/items/{item-id}/getActivitiesByInterval
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 (deprecated) GET /drive/items/{item-id}/content
Download content GET /drive/items/{item-id}/contentStream
Download specific file format GET /drive/items/{item-id}/content?format={format}
Delete item DELETE /drive/items/{item-id}
PermanentDelete item POST /drives/{driveId}/items/{itemId}/permanentDelete
Restore item POST /drive/items/{item-id}/restore
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
Follow item POST /drives/{drive-id}/items/{item-id}/follow
Unfollow item POST /drives/{drive-id}/items/{item-id}/unfollow
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}
Get WebSocket channel GET /drive/root/subscriptions/socketIo
Preview item POST /drive/items/{item-id}/preview
Check in POST /drives/{driveId}/items/{itemId}/checkin
Check out POST /drives/{driveId}/items/{itemId}/checkout
Revoke grants PATCH /drive/items/{item-id}/permissions/{perm-id}/revokeGrants
Extract sensitivity labels POST /drive/items/{item-id}/extractSensitivityLabels
Assign sensitivity label POST /drive/items/{item-id}/assignSensitivityLabel
Get retention label GET /drives/{drive-id}/items/{id}/retentionLabel
Set retention label PATCH /drives/{drive-id}/items/{id}/retentionLabel
Remove retention label DELETE /drives/{drive-id}/items/{id}/retentionLabel
Lock or unlock record PATCH /drives/{drive-id}/items/{id}/retentionLabel

Properties

Property Type Description
audio audio Audio metadata, if the item is an audio file. Read-only. Only on OneDrive Personal.
bundle bundle Bundle metadata, if the item is a bundle. Read-only.
content (deprecated) Stream The content stream, if the item represents a file. The content property will have a potentially breaking change in behavior in the future. It will stream content directly instead of redirecting. To proactively opt in to the new behavior ahead of time, use the contentStream property instead.
contentStream Stream The content stream, if the item represents a file.
createdBy identitySet Identity of the user, device, and application, which created the item. Read-only.
createdDateTime DateTimeOffset Date and time of item creation. Read-only.
cTag String An eTag for the content of the item. This eTag isn't changed if only the metadata is changed. Note This property isn't returned if the item is a folder. Read-only.
deleted deleted Information about the deleted state of the item. Read-only.
description String Provides a user-visible description of the item. Read-write. Only on OneDrive Personal.
eTag String eTag for the entire item (metadata + content). Read-only.
file file File metadata, if the item is a file. Read-only.
fileSystemInfo fileSystemInfo File system information on client. Read-write.
folder folder Folder metadata, if the item is a folder. Read-only.
id String The unique identifier of the item within the Drive. Read-only.
image image Image metadata, if the item is an image. Read-only.
lastModifiedBy identitySet Identity of the user, device, and application, which last modified the item. Read-only.
lastModifiedDateTime DateTimeOffset Date and time at which the item was last modified. Read-only.
location geoCoordinates Location metadata, if the item has location data. Read-only.
malware malware Malware metadata, if the item was detected to contain malware. Read-only.
media media Information about the media (audio or video) item. Read-write. Only on OneDrive for Business and SharePoint.
name String The name of the item (filename and extension). Read-write.
package package 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.
parentReference itemReference Parent information, if the item has a parent. Read-write.
pendingOperations pendingOperations If present, indicates that indicates that one or more operations that might affect the state of the driveItem are pending completion. Read-only.
photo photo Photo metadata, if the item is a photo. Read-only.
publication publicationFacet Provides information about the published or checked-out state of an item, in locations that support such actions. This property isn't returned by default. Read-only.
remoteItem remoteItem Remote item data, if the item is shared from a drive other than the one being accessed. Read-only.
root root If this property is non-null, it indicates that the driveItem is the top-most driveItem in the drive.
searchResult searchResult Search metadata, if the item is from a search result. Read-only.
shared shared Indicates that the item was shared with others and provides information about the shared state of the item. Read-only.
sharepointIds sharepointIds Returns identifiers useful for SharePoint REST compatibility. Read-only.
size Int64 Size of the item in bytes. Read-only.
specialFolder specialFolder If the current item is also available as a special folder, this facet is returned. Read-only.
source driveItemSource Information about the drive item source. Read-only. Only on OneDrive for Business and SharePoint.
video video Video metadata, if the item is a video. Read-only.
webDavUrl String WebDAV compatible URL for the item.
webUrl String URL that displays the resource in the browser. Read-only.

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
activities itemActivity collection The list of recent activities that took place on this item.
analytics itemAnalytics resource Analytics about the view activities that took place on this item.
children driveItem collection Collection containing Item objects for the immediate children of Item. Only items representing folders have children. Read-only. Nullable.
createdByUser user Identity of the user who created the item. Read-only.
lastModifiedByUser user Identity of the user who last modified the item. Read-only.
listItem listItem For drives in SharePoint, the associated document library list item. Read-only. Nullable.
permissions permission collection The set of permissions for the item. Read-only. Nullable.
retentionLabel itemRetentionLabel Information about retention label and settings enforced on the driveItem. Read-write.
subscriptions subscription collection The set of subscriptions on the item. Only supported on the root of a drive.
thumbnails thumbnailSet collection Collection of thumbnailSet objects associated with the item. For more information, see getting thumbnails. Read-only. Nullable.
versions driveItemVersion collection The list of previous versions of the item. For more info, see getting previous versions. Read-only. Nullable.
workbook workbook For files that are Excel spreadsheets, access to the workbook API to work with the spreadsheet's contents. Nullable.

Instance Attributes

Instance attributes are properties with special behaviors. These properties are temporary and either define behavior the service should perform or provide short-term property values, like a download URL for an item that expires.

Property name Type Description
@microsoft.graph.conflictBehavior string 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 is never returned with this annotation. Write-only.
@microsoft.graph.downloadUrl string A URL that can be used to download this file's content. Authentication isn't required with this URL. Read-only.
@microsoft.graph.sourceUrl string This instance annotation can be used to instruct the service to download the contents of the URL when issuing a PUT request, and stores it as the file. Write-only.

Notes: The parameter @microsoft.graph.conflictBehavior should be included in the URL instead of the body of the request.

The @microsoft.graph.downloadUrl value is a short-lived URL and can't be cached. The URL is invalidated after for a short period of time (1 hour). Removing file permissions for a user might not immediately invalidate the URL.

Using the @microsoft.graph.sourceUrl property for file uploading is not supported in OneDrive for Business, SharePoint Online, and SharePoint Server 2016.

JSON representation

The following JSON representation shows the resource type.

The driveItem resource is derived from baseItem and inherits properties from that resource.

{
  "audio": { "@odata.type": "microsoft.graph.audio" },
  "bundle": { "@odata.type": "microsoft.graph.bundle" },
  "content": { "@odata.type": "Edm.Stream" },
  "contentStream": { "@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" },
  "malware": { "@odata.type": "microsoft.graph.malware" },
  "media": { "@odata.type": "microsoft.graph.media" },
  "package": { "@odata.type": "microsoft.graph.package" },
  "pendingOperations": { "@odata.type": "microsoft.graph.pendingOperations" },
  "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,
  "source": { "@odata.type": "microsoft.graph.driveItemSource" },
  "specialFolder": { "@odata.type": "microsoft.graph.specialFolder" },
  "video": { "@odata.type": "microsoft.graph.video" },
  "webDavUrl": "string",

  /* relationships */
  "activities": [{"@odata.type": "microsoft.graph.itemActivity"}],
  "children": [{ "@odata.type": "microsoft.graph.driveItem" }],
  "createdByUser": { "@odata.type": "microsoft.graph.user" },
  "itemRetentionLabel": [{ "@odata.type": "microsoft.graph.itemRetentionLabel" }],
  "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"
}