ms_drive_item {Microsoft365R}R Documentation

File or folder in a drive

Description

Class representing an item (file or folder) in a OneDrive or SharePoint document library.

Format

An R6 object of class ms_drive_item, inheriting from ms_object.

Fields

Methods

Initialization

Creating new objects of this class should be done via the get_item method of the ms_drive class. Calling the new() method for this class only constructs the R object; it does not call the Microsoft Graph API to retrieve or create the actual item.

File and folder operations

This class exposes methods for carrying out common operations on files and folders. Note that for the methods below, any paths to child items are relative to the folder's own path.

open opens this file or folder in your browser. If the file has an unrecognised type, most browsers will attempt to download it.

list_items(path, info, full_names, filter, n, pagesize) lists the items under the specified path. It is the analogue of base R's dir/list.files. Its arguments are

list_files is a synonym for list_items.

download downloads the item to the local machine. If this is a file, it is downloaded; in this case, the dest argument can be the path to the destination file, or NULL to return the downloaded content in a raw vector. If the item is a folder, all its files are downloaded, including subfolders if the recursive argument is TRUE.

upload uploads a file or folder from the local machine into the folder item. The src argument can be the path to the source file, a rawConnection or a textConnection object. If src is a folder, all its files are uploaded, including subfolders if the recursive argument iS TRUE. An ms_drive_item object is returned invisibly.

Uploading is done in blocks of 32MB by default; you can change this by setting the blocksize argument. For technical reasons, the block size must be a multiple of 320KB.

Uploading and downloading folders can be done in parallel, which can result in substantial speedup when transferring a large number of small files. This is controlled by the parallel argument to upload and download, which can have the following values:

get_item retrieves the file or folder with the given path, as another object of class ms_drive_item.

For copying and moving, the destination folder must exist beforehand. When copying/moving a large number of files, it's much more efficient to supply the destination folder in the dest_folder_item argument rather than as a path.

create_folder creates a folder with the specified path. Trying to create an already existing folder is an error. This returns an ms_drive_item object, invisibly.

create_share_link(path, type, expiry, password, scope) returns a shareable link to the item. Its arguments are

This method returns a URL to access the item, for type="view" or "⁠type=edit"⁠. For type="embed", it returns a list with components webUrl containing the URL, and webHtml containing a HTML fragment to embed the link in an IFRAME. The default is a viewable link, expiring in 7 days.

Saving and loading data

The following methods are provided to simplify the task of loading and saving datasets and R objects.

List methods

All ⁠list_*⁠ methods have filter and n arguments to limit the number of results. The former should be an OData expression as a string to filter the result set on. The latter should be a number setting the maximum number of (filtered) results to return. The default values are filter=NULL and n=Inf. If n=NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

Support in the underlying Graph API for OData queries is patchy. Not all endpoints that return lists of objects support filtering, and if they do, they may not allow all of the defined operators. If your filtering expression results in an error, you can carry out the operation without filtering and then filter the results on the client side.

See Also

ms_graph, ms_site, ms_drive

Microsoft Graph overview, OneDrive API reference

Examples

## Not run: 

# personal OneDrive
mydrv <- get_personal_onedrive()

docs <- mydrv$get_item("Documents")
docs$list_files()
docs$list_items()

# this is the file 'Documents/myfile.docx'
myfile <- docs$get_item("myfile.docx")
myfile$properties

# rename a file
myfile$update(name="newname.docx")

# copy a file (destination folder must exist)
myfile$copy("/Documents/folder2/myfile_copied.docx")

# alternate way of copying: supply the destination folder
destfolder <- docs$get_item("folder2")
myfile$copy("myfile_copied.docx", dest_folder_item=destfolder)

# move a file (destination folder must exist)
myfile$move("Documents/folder2/myfile_moved.docx")

# open the file in the browser
myfile$open()

# download the file to the working directory
myfile$download()

# shareable links
myfile$create_share_link()
myfile$create_share_link(type="edit", expiry="24 hours")
myfile$create_share_link(password="Use-strong-passwords!")

# delete the file (will ask for confirmation first)
myfile$delete()

# saving and loading data
myfolder <- mydrv$get_item("myfolder")
myfolder$save_dataframe(iris, "iris.csv")
iris2 <- myfolder$get_item("iris.csv")$load_dataframe()
identical(iris, iris2)  # TRUE

myfolder$save_rds(iris, "iris.rds")
iris3 <- myfolder$get_item("iris.rds")$load_rds()
identical(iris, iris3)  # TRUE


## End(Not run)
[Package Microsoft365R version 2.4.0 Index]