Class representing a list in a SharePoint site.

Format

An R6 object of class ms_list, 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 "list" for a SharePoint list object.

  • properties: The item properties (metadata).

Methods

  • new(...): Initialize a new object. Do not call this directly; see 'Initialization' below.

  • delete(confirm=TRUE): Delete this list. By default, ask for confirmation first.

  • update(...): Update the list's properties in Microsoft Graph.

  • do_operation(...): Carry out an arbitrary operation on the list.

  • sync_fields(): Synchronise the R object with the list metadata in Microsoft Graph.

  • list_items(filter, select, all_metadata, as_data_frame, pagesize): Queries the list and returns items as a data frame. See 'List querying' below.

  • get_column_info(): Return a data frame containing metadata on the columns (fields) in the list.

  • get_item(id): Get an individual list item.

  • create_item(...): Create a new list item, using the named arguments as fields.

  • update_item(id, ...): Update the data fields in the given item, using the named arguments. To update the item's metadata, use get_item() to retrieve the item object, then call its update() method.

  • delete_item(confirm=TRUE): Delete a list item. By default, ask for confirmation first.

  • bulk_import(data): Imports a data frame into the list.

Initialization

Creating new objects of this class should be done via the get_list method of the ms_site 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.

List querying

list_items supports the following arguments to customise results returned by the query.

  • filter: A string giving an OData expression to filter the rows to return. Note that column names used in the expression must be prefixed with fields/ to distinguish them from item metadata.

  • n: The maximum number of (filtered) results to return. If this is NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

  • select: A string containing comma-separated column names to include in the returned data frame. If not supplied, includes all columns.

  • all_metadata: If TRUE, the returned data frame will contain extended metadata as separate columns, while the data fields will be in a nested data frame named fields. This is always set to FALSE if n=NULL or as_data_frame=FALSE.

  • as_data_frame: If FALSE, return the result as a list of individual ms_list_item objects, rather than a data frame.

  • pagesize: The number of results to return for each call to the REST endpoint. You can try reducing this argument below the default of 5000 if you are experiencing timeouts.

Note that the Graph API currently doesn't support retrieving item attachments.

Examples

if (FALSE) {

site <- get_sharepoint_site("My site")
lst <- site$get_list("mylist")

lst$get_column_info()

lst$list_items()
lst$list_items(filter="startswith(fields/firstname, 'John')", select="firstname,lastname")

lst$create_item(firstname="Mary", lastname="Smith")
lst$get_item("item-id")
lst$update_item("item_id", firstname="Eliza")
lst$delete_item("item_id")

df <- data.frame(
    firstname=c("Satya", "Mark", "Tim", "Jeff", "Sundar"),
    lastname=c("Nadella", "Zuckerberg", "Cook", "Bezos", "Pichai")
)
lst$bulk_import(df)

}