Sharepoint API Client

Quick tool to manage cloud sharepoint up/downloads vi Add-Ins Oauth credentials

Sharepoint API Client

Build Status Coverage Status PyPI version

This is a quick tool for interfacing with Sharepoint APIs without user credentials. It includes a library to be used as well as a basic tool

NOTE: this is only known to work with MS/Cloud hosted instance, i.e. instances that have urls in form of https://<tenant>.sharepoint.com/. It may work with self-hosted sharepoint, but currently the domain is hardcoded into the lib

Changelog

Installation

Quickest way to install is via PyPi

pip3 install sharepoint-tool

Known Issues

When creating folders using add_folder_path() or upload_file(), the library will attempt to create all parent folders, and it may not have permissions at certain level - causing 403 errors in the logs like these:

sp_tool.sharepoint.connector:E:API ERROR: 403: '{"error":{"code":"-2147024891, System.UnauthorizedAccessException","message":{"lang":"en-US","value":"Access denied."}}}'

These are usually safe to ignore, assuming folder already exists. In the future we will handle this better.

Pre-Requisites

This library leverages “AppOnly” Add-In OAuth authentication. Before you can use this API, you will need to register your “app” and get a client_id and a security token for authentication.

To do this you need to be admin on the space you are going to use.

TIP: You can generate these urls by running the app with register command like so:

sp-tool --tenant mycompany --site MyTeam register

Step 1 - Register your “App”

Go to URI _layouts/15/appregnew.aspx relative to your site - so if your tenant id is mycompany and your site is MyTeam it will be:

https://mycompany.sharepoint.com/sites/MyTeam/_layouts/15/appregnew.aspx

Fill in:

Step 2 - Grant Permissions

Now, go to uri _layouts/15/appinv.aspx. Going with example above it will be:

https://mycompany.sharepoint.com/sites/MyTeam/_layouts/15/appinv.aspx

Once there, enter the client id from step 1 and do a lookup If all went well, it will populate all the fields except permissions from values you set in the app.

For Permission Request XML enter something like (specific permissions depend on your needs):

<AppPermissionRequests AllowAppOnlyPolicy="true">  
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" 
    Right="Write" />
</AppPermissionRequests>

See these links to better understand permissions:

Step 3 - Accept Trust Confirmation

Using as binary

This library comes with a simple implementation as a tool to publish a directory of files to a SharePoint.

Current help screen:

Usage: sp_tool [OPTIONS] ACTION

  Microsoft-hosted Sharepoint API interface tool

Options:
  --version                   Show the version and exit.
  --dry-run / --no-dry-run    If set, do not actually upload
  --debug                     Debug mode
  --site TEXT                 Number of greetings.
  --tenant TEXT               Sharepoint Tenant id
  --recurse / --no-recurse    If true, recurse into subdirectories
  --checkout / --no-checkout  If true, recurse into subdirectories
  --base-path TEXT            Base for uploading to sharepoint
  --path TEXT                 Path relative to base for uploading to
                              sharepoint
  --client_id TEXT            Sharepoint Client ID
  --secret TEXT               Sharepoint Secret Token
  -h                          Show this message and exit.
  --help                      Show this message and exit.

Commands:
  config   Show effective config and exit
  publish  Publish command

Every parameter above can be set via env variables as such:

Using as library

To use this as a library in your code all you need to do is to import and create SharepointConnection object:

from sp_tool.sharepoint import SharepointConnector

# Create Client
sharepoint = SharepointConnector(
    tenant=TENANT,
    client_id=CLIENT_ID,
    client_secret=SECRET,
    site_name=SITE
)

Available APIs

Here is a quick dump of available commands as of right now:

TODO: More documentation