ms_drive_item: File or folder in a drive
In Microsoft365R: Interface to the 'Microsoft 365' Suite of Cloud Services

ms_drive_item

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

token: The token used to authenticate with the Graph host.
tenant: The Azure Active Directory tenant for the parent drive.
type: always "drive item" for a drive item object.
properties: The item properties (metadata).

Methods

new(...): Initialize a new object. Do not call this directly; see 'Initialization' below.
delete(confirm=TRUE, by_item=FALSE): Delete this item. By default, ask for confirmation first. For personal OneDrive, deleting a folder will also automatically delete its contents; for business OneDrive or SharePoint document libraries, you may need to set by_item=TRUE to delete the contents first depending on your organisation's policies. Note that this can be slow for large folders.
update(...): Update the item's properties (metadata) in Microsoft Graph.
do_operation(...): Carry out an arbitrary operation on the item.
sync_fields(): Synchronise the R object with the item metadata in Microsoft Graph.
open(): Open the item in your browser.
copy(dest, dest_folder_item=NULL): Copy the item to the given location.
move(dest, dest_folder_item=NULL): Move the item to the given location.
⁠list_items(...), list_files(...)⁠: List the files and folders under the specified path.
download(dest, overwrite, recursive, parallel): Download the file or folder. See below.
create_share_link(type, expiry, password, scope): Create a shareable link to the file or folder.
upload(src, dest, blocksize, , recursive, parallel): Upload a file or folder. See below.
create_folder(path): Create a folder. Only applicable for a folder item.
get_item(path): Get a child item (file or folder) under this folder.
get_parent_folder(): Get the parent folder for this item, as a drive item object. Returns the root folder for the root. Not supported for remote items.
get_path(): Get the absolute path for this item, as a character string. Not supported for remote items.
is_folder(): Information function, returns TRUE if this item is a folder.
load_dataframe(delim=NULL, ...): Download a delimited file and return its contents as a data frame. See 'Saving and loading data' below.
load_rds(): Download a .rds file and return the saved object.
load_rdata(envir): Load a .RData or .Rda file into the specified environment.
save_dataframe(df, file, delim=",", ...) Save a dataframe to a delimited file.
save_rds(object, file): Save an R object to a .rds file.
save_rdata(..., file): Save the specified objects to a .RData file.

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

path: The path.
info: The information to return: either "partial", "name" or "all". If "partial", a data frame is returned containing the name, size, ID and whether the item is a file or folder. If "name", a vector of file/folder names is returned. If "all", a data frame is returned containing all the properties for each item (this can be large).
full_names: Whether to prefix the folder path to the names of the items.
⁠filter, n⁠: See 'List methods' below.
pagesize: The number of results to return for each call to the REST endpoint. You can try reducing this argument below the default of 1000 if you are experiencing timeouts.

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:

TRUE: A cluster with 5 workers is created
A number: A cluster with this many workers is created
A cluster object, created via the parallel package
FALSE: The transfer is done serially

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

copy and move can take the destination location as either a full pathname (in the dest argument), or a name plus a drive item object (in the dest_folder_item argument). If the latter is supplied, any path in dest is ignored with a warning. Note that copying is an asynchronous operation, meaning the method returns before the copy is complete.

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

path: The path.
type: Either "view" for a read-only link, "edit" for a read-write link, or "embed" for a link that can be embedded in a web page. The last one is only available for personal OneDrive.
expiry: How long the link is valid for. The default is 7 days; you can set an alternative like "15 minutes", "24 hours", "2 weeks", "3 months", etc. To leave out the expiry date, set this to NULL.
password: An optional password to protect the link.
scope: Optionally the scope of the link, either "anonymous" or "organization". The latter allows only users in your AAD tenant to access the link, and is only available for OneDrive for Business or SharePoint.

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.

load_dataframe downloads a delimited file and returns its contents as a data frame. The delimiter can be specified with the delim argument; if omitted, this is "," if the file extension is .csv, ";" if the file extension is .csv2, and a tab otherwise. If the readr package is installed, the readr::read_delim function is used to parse the file, otherwise utils::read.delim is used. You can supply other arguments to the parsing function via the ... argument.
save_dataframe is the inverse of load_dataframe: it uploads the given data frame to a folder item. Specify the delimiter with the delim argument. The readr::write_delim function is used to serialise the data if that package is installed, and utils::write.table otherwise.
load_rds downloads a .rds file and returns its contents as an R object. It is analogous to the base readRDS function but for OneDrive/SharePoint drive items.
save_rds uploads a given R object as a .rds file, analogously to saveRDS.
load_rdata downloads a .RData or .Rda file and loads its contents into the given environment. It is analogous to the base load function but for OneDrive/SharePoint drive items.
save_rdata uploads the given R objects as a .RData file, analogously to save.

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.

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)

Microsoft365R documentation built on May 31, 2023, 6:10 p.m.