sharepointr

👉 A R package to work with SharePoint files using {Microsoft365R} methods

https://github.com/elipousson/sharepointr

Keywords

microsoft-365 r-package sharepoint-online

Last synced: 10 months ago · JSON representation

Repository

👉 A R package to work with SharePoint files using {Microsoft365R} methods

Basic Info

Host: GitHub
Owner: elipousson
License: other
Language: R
Default Branch: main
Homepage: https://elipousson.github.io/sharepointr/
Size: 6.25 MB

Statistics

Stars: 25
Watchers: 3
Forks: 3
Open Issues: 10
Releases: 0

Topics

microsoft-365 r-package sharepoint-online

Created over 2 years ago · Last pushed 10 months ago

Metadata Files

Readme Changelog License Codemeta

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# sharepointr



[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)



The goal of SharePointR is to make it easier to read, write, and work with files stored in SharePoint by extending the `{Microsoft365R}` package.

## Installation

You can install the development version of SharePointR like so:

``` r
# pak::pkg_install("elipousson/sharepointr")
```

## Requirements

To use this package (or `{Microsoft365}`) you must:

-   Have a work or school account with access to [Microsoft SharePoint](https://www.microsoft.com/en-us/microsoft-365/sharepoint/collaboration)
-   Have enabled permissions for the default `{Microsoft365}` app ID

See the `{Microsoft365}` [documentation on app registration for more information](https://github.com/Azure/Microsoft365R/blob/master/inst/app_registration.md).

## Usage

`{Microsoft365}` uses S6 methods for nearly everything which may be difficult for users (me included) who are less familiar with this interface.

The `{sharepointr}` package seeks to ease this challenge by wrapping the `{Microsoft365}` methods and adding support for the specification of SharePoint sites, drives, and items using SharePoint URLs instead of item or drive ID values.

```{r}
library(sharepointr)
```

### Reading and writing objects to and from SharePoint

The most useful functions for most users may be `read_sharepoint()` and `write_sharepoint()`.

`read_sharepoint()` downloads a SharePoint file to a temporary folder and then, based on the file extension, reads it into your environment using an appropriate function and package (e.g. using `officer::read_docx()` for Microsoft Word files or `sf::read_sf()` for common spatial data files):

```{r}
docx_shared_url <- "https://bmore.sharepoint.com/:w:/r/sites/MayorsOffice-DataGovernance/Shared%20Documents/General/Baltimore%20Data%20Academy/Baltimore%20Data%20Academy%20Announcement%20Content.docx?d=w0a50d3cd74ce4a8da6d82596037f0148&csf=1&web=1&e=cBURo2"

read_sharepoint(docx_shared_url)
```

`write_sharepoint()` saves an R object to local files and then uses `upload_sp_item()` to uploads the file to SharePoint.

See `vignette("read-write"")` for more information on reading and writing files to SharePoint with this package.

### Working with SharePoint items, lists, and plans

This package currently support three main categories of SharePoint objects:

-   **Items** (including **directories** and **files**) and **item properties**

-   **Lists and list items**

-   **Plans and tasks**

Typically these functions return a `ms_object` object, a list of `ms_object` objects, or a data frame. In some cases, the data frame is based on the object properties and includes a list column where the `ms_object` is stored.

For example, `get_sp_item()` returns a `ms_drive_item` object and supports parsing for shared file and folder URLs:

```{r}
get_sp_item(docx_shared_url)
```

Set `as_data_frame = TRUE` to return a data frame instead of a `ms_drive_item` object:

```{r}
get_sp_item(docx_shared_url, as_data_frame = TRUE)
```

These basic functions to "get" objects are extended by functions like `download_sp_item()` that adds support for downloading copies of your SharePoint files (this is the function that powers `read_sharepoint()`):

```{r}
withr::with_tempdir({
  docx_dest <- download_sp_item(docx_shared_url)

  file.exists(docx_dest)
})
```

See `vignette("read-write"")` for more on reading and writing items to SharePoint.

Some of the original `{Microsoft365R}` S6 object methods already return a data frame by default such as the `list_items` and `list_files` methods for `Microsoft365R::ms_drive` object. `sp_dir_info()` wraps this method to return a data frame similar to the output from `fs::dir_info()`:

```{r}
sp_dir_info("https://bmore.sharepoint.com/:w:/r/sites/MayorsOffice-DataGovernance/Shared%20Documents/General/Baltimore%20Data%20Academy")
```

Others functions use the `as_data_frame` parameter to convert a list into a data frame as a convenient alternative. Most functions that start with `list_` return a data frame by default but can return a list of `ms_object` class objects if `as_data_frame = FALSE`.

When creating, updating, or deleting a large number of list items, use `mirai::daemons()` to complete the operations in parallel. This feature uses the experimental `purrr::in_parallel()` function documented here: 

See `vignette("sp-lists"")` for more on reading and writing SharePoint list items.

### Helpers for SharePoint sites and drives

Most functions in the package rely on a pair of helper functions: `get_sp_site()`, `get_sp_drive()`, and `get_sp_item()`, that can parse a URL to determine the SharePoint site URL, drive name, and file path based on the URL.

`get_sp_site()` is a minimal wrapper for `Microsoft365R::get_sharepoint_site()`:

```{r}
site_url <- "https://bmore.sharepoint.com/sites/MayorsOffice-DataGovernance"

get_sp_site(site_url = site_url)
```

`get_sp_drive()` returns a `ms_drive` object but required a SharePoint URL that includes the name of the drive (otherwise it returns the drive named in the "sharepointr.default_drive_name" option):

```{r}
get_sp_drive(docx_shared_url)
```

See `vignette("sp_url"")` for more information on how the package handles URL parsing.

## Related packages

There are a few similar packages available:

-   [sharrpoint](https://gitlab.com/tolmay/sharrpoint): An R package to interact with Sharepoint API (files & lists).
-   [sharepointr](https://github.com/LukasK13/sharepointr): A R package for reading from and writing to SharePoint lists.
-   [msgraphr](https://github.com/davidski/msgraphr): A minimal R wrapper of the SharePoint Online (Office 365) APIs (last updated 3 years ago).

I know this package name conflicts with the existing sharepointr package. Unfortunately, I didn't notice find it until after I set up the repository. However, given that it appears that the sharepointr package may be no longer under development, I plan stick with the current name for the time being.

Owner

Name: Eli Pousson
Login: elipousson
Kind: user
Location: Baltimore, MD
Company: Baltimore City Department of Planning

Website: https://elipousson.github.io/
Twitter: elipousson
Repositories: 95
Profile: https://github.com/elipousson

I love old buildings and bicycles. Planner with the Baltimore City Department of Planning. Former preservationist @baltimoreheritage

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "sharepointr",
  "description": "A R package extending Microsoft365R to make it easier to read, write, and work with SharePoint items, lists, and plans.",
  "name": "sharepointr: Read and Write from SharePoint Sites",
  "relatedLink": "https://elipousson.github.io/sharepointr/",
  "codeRepository": "https://github.com/elipousson/sharepointr",
  "issueTracker": "https://github.com/elipousson/sharepointr/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "0.1.0",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.3.2 (2023-10-31)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Eli",
      "familyName": "Pousson",
      "email": "eli.pousson@gmail.com",
      "@id": "https://orcid.org/0000-0001-8280-1706"
    }
  ],
  "copyrightHolder": [
    {
      "@type": "Person",
      "givenName": "Eli",
      "familyName": "Pousson",
      "email": "eli.pousson@gmail.com",
      "@id": "https://orcid.org/0000-0001-8280-1706"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Eli",
      "familyName": "Pousson",
      "email": "eli.pousson@gmail.com",
      "@id": "https://orcid.org/0000-0001-8280-1706"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "fs",
      "name": "fs",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=fs"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "officer",
      "name": "officer",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=officer"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "openxlsx2",
      "name": "openxlsx2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=openxlsx2"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rappdirs",
      "name": "rappdirs",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rappdirs"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "readr",
      "name": "readr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=readr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "readxl",
      "name": "readxl",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=readxl"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "sf",
      "name": "sf",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=sf"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "withr",
      "name": "withr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=withr"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "cli",
      "name": "cli",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=cli"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "glue",
      "name": "glue",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=glue"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "httr2",
      "name": "httr2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=httr2"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "Microsoft365R",
      "name": "Microsoft365R",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=Microsoft365R"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "rlang",
      "name": "rlang",
      "version": ">= 1.1.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rlang"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "stringr",
      "name": "stringr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=stringr"
    },
    "7": {
      "@type": "SoftwareApplication",
      "identifier": "utils",
      "name": "utils"
    },
    "8": {
      "@type": "SoftwareApplication",
      "identifier": "vctrs",
      "name": "vctrs",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=vctrs"
    },
    "SystemRequirements": null
  },
  "fileSize": "202.49KB",
  "readme": "https://github.com/elipousson/sharepointr/blob/main/README.md",
  "developmentStatus": "https://lifecycle.r-lib.org/articles/stages.html#experimental",
  "keywords": [
    "microsoft-365",
    "r-package",
    "sharepoint-online"
  ]
}

GitHub Events

Total

Watch event: 1
Issue comment event: 1
Push event: 50
Fork event: 1

Last Year

Watch event: 1
Issue comment event: 1
Push event: 50
Fork event: 1

Issues and Pull Requests

Last synced: over 1 year ago

All Time

Total issues: 12
Total pull requests: 0
Average time to close issues: 4 months
Average time to close pull requests: N/A
Total issue authors: 2
Total pull request authors: 0
Average comments per issue: 1.42
Average comments per pull request: 0
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 8
Pull requests: 0
Average time to close issues: about 1 month
Average time to close pull requests: N/A
Issue authors: 2
Pull request authors: 0
Average comments per issue: 1.75
Average comments per pull request: 0
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Source Science

sharepointr

Science Score: 26.0%