Microsoft365R: Interface to Microsoft 365

Authentication details

The first time you call one of the Microsoft365R functions (see below), it will use your Internet browser to authenticate you with Azure Active Directory, in a similar manner to other web apps. You will get a dialog box asking for permission to access your information.

For authentication purposes, the package is registered as an app in the ‘aicatr’ AAD tenant; depending on your organisation’s security policy, you may have to get an admin to grant it access to your tenant. Alternatively, if the environment variable CLIMICROSOFT365_AADAPPID is set, Microsoft365R will use its value as the app ID for authenticating to the Microsoft 365 Business services (SharePoint and OneDrive for Business). You can also specify the app ID as an argument when calling the functions below.

If creating your own app registration is impractical, it’s possible to work around access issues by piggybacking on the CLI for Microsoft365. By setting the R option microsoft365r_use_cli_app_id to a non-NULL value, authentication will be done using the CLI’s app ID. Technically this app still requires admin approval, but it is in widespread use and so may already be allowed in your organisation. Be warned that this solution may draw the attention of your admin!

OneDrive

To access your personal OneDrive, call the personal_onedrive() function. This returns an R6 client object of class ms_drive, which has methods for working with files and folders.

od <- personal_onedrive()

# or if you don't have a browser
od <- personal_onedrive(auth_type="device_code")

# list files and folders
od$list_items()
od$list_items("Documents")

# upload and download files
od$download_file("Documents/myfile.docx")
od$upload_file("somedata.xlsx")

# create a folder
od$create_folder("Documents/newfolder")

You can open a file or folder in your browser with the open_item() method. For example, a Word document or Excel spreadsheet will open in Word or Excel Online, and a folder will be shown in OneDrive.

od$open_item("Documents/myfile.docx")

To obtain a shareable link for a file or folder, use create_share_link():

# default: viewable link, expires in 7 days
od$create_share_link("Documents/myfile.docx", type="view")

# editable link, expires in 24 hours
od$create_share_link("Documents/myfile.docx", type="edit", expiry="24 hours")

# setting a password
od$create_share_link("Documents/myfile.docx", password="Use-strong-passwords!")

You can get and set the metadata properties for a file or folder with get_item_properties() and set_item_properties(). For the latter, provide the new properties as named arguments to the method. Not all properties can be changed; some, like the file size and last modified date, are read-only. You can also retrieve an object representing the file or folder with get_item(), which has methods appropriate for drive items.

od$get_item_properties("Documents/myfile.docx")

# rename a file -- version control via filename is bad, mmkay
od$set_item_properties("Documents/myfile.docx", name="myfile version 2.docx")

# alternatively, you can call the file object's update() method
item <- od$get_item("Documents/myfile.docx")
item$update(name="myfile version 2.docx")

To access OneDrive for Business call business_onedrive(). This also returns an object of class ms_drive, so the exact same methods are available as for personal OneDrive.

# by default, authenticate with the Microsoft365R internal app ID
odb <- business_onedrive()

# authenticating with the CLI for Microsoft 365 app ID: set a global option
options(microsoft365r_use_cli_app_id=TRUE)
odb <- business_onedrive()

odb$list_items()
odb$open_item("myproject/demo.pptx")

SharePoint

To access a SharePoint site, use the sharepoint_site() function and provide the site URL or ID.

site <- sharepoint_site("https://myaadtenant.sharepoint.com/sites/my-site-name")

The client object has methods to retrieve drives (document libraries) and lists. To show all drives in a site, use the list_drives() method, and to retrieve a specific drive, use get_drive(). Each drive is an object of class ms_drive, just like the OneDrive clients above.

# list of all document libraries under this site
site$list_drives()

# default document library
drv <- site$get_drive()

# same methods as for OneDrive
drv$list_items()
drv$open_item("teamproject/plan.xlsx")

To show all lists in a site, use the get_lists() method, and to retrieve a specific list, use get_list() and supply either the list name or ID.

site$get_lists()

lst <- site$get_list("my-list")

You can retrieve the items in a list as a data frame, with list_items(). This has arguments filter and select to do row and column subsetting respectively. filter should be an OData expression provided as a string, and select should be a string containing a comma-separated list of columns. Any column names in the filter expression must be prefixed with fields/ to distinguish them from item metadata.

# return a data frame containing all list items
lst$list_items()

# get subset of rows and columns
lst$list_items(
    filter="startsWith(fields/firstname, 'John')",
    select="firstname,lastname,title"
)

There are also get_item(), create_item(), update_item() and delete_item() methods for working directly with individual items.

item <- list$create_item(firstname="Mary", lastname="Smith")
iid <- item$properties$id
list$update_item(iid, firstname="Eliza")
list$delete_item(iid)

Finally, you can retrieve subsites with list_subsites() and get_subsite(). These also return SharePoint site objects, so all the methods above are available for a subsite.

Currently, Microsoft365R only supports SharePoint Online, the cloud-hosted version of the product. Support for SharePoint Server (the on-premises version) may come at a later stage.

Integration with AzureGraph

In addition to the client functions given above, Microsoft365R enhances the az_user and az_group classes that are part of AzureGraph, to let you access drives and sites directly from a user or group object.

az_user gains list_drives() and get_drive() methods. The first shows all the drives that the user has access to, including those that are shared from other users. The second retrieves a specific drive, by default the user’s OneDrive. Whether these are personal or business drives depends on the tenant that was specified in AzureGraph::get_graph_login()/create_graph_login(): if the tenant was “consumers”, it will be the personal OneDrive.

az_group gains list_drives(), get_drive() and get_sharepoint_site() methods. The first two do the same as for az_user: they retrieve the drive(s) for the group. The third method retrieves the SharePoint site associated with the group, if one exists.

Authentication troubleshooting

Microsoft365R’s default authentication flow leverages your Internet browser to provide the same login experience as other web apps. This may be a problem if your R session is taking place in a context where a browser is unavailable, for example in a text-only terminal in a VM or container. If so, you can switch to the device code flow, by adding auth_type="device_code" as an argument:

personal_onedrive(auth_type="device_code")

business_onedrive(auth_type="device_code")

sharepoint_site("https://site-url", auth_type="device_code")

When authenticating for SharePoint and OneDrive for Business, by default Microsoft365R will detect your Azure Active Directory tenant from your logged-in credentials in the browser. If this doesn’t work, specify your tenant name with the tenant argument:

business_onedrive(tenant="myaadtenant")

sharepoint_site("https://site-url", tenant="myaadtenant")