Node.js module for downloading files from SharePoint document libraries.
Files streaming download:
- Download files of any supported size
- Effective memmory consumption while fetching large files
Performance in SPO and HTTPS environments is improved. Download on multiple objects is x2 faster now!
Smart re-download mechanism. Existing files with no changes are ignored from the download.
- SharePoint Online
- SharePoint 2013
- SharePoint 2016
npm install sppull --save-dev
var sppull = require("sppull").sppull;
var context = {/*...*/};
var options = {/*...*/};
sppull(context, options)
.then(successHandler)
.catch(errorHandler);
siteUrl
- SharePoint site (SPWeb) url [string, required]creds
username
- user name for SP authentication [string, optional in case of some auth methods]password
- password [string, optional in case of some auth methods] ...
Additional authentication options:
Since communication module (sp-request), which is used in sppull, had received additional SharePoint authentication methods, they are also supported in sppull.
- SharePoint On-Premise (Add-In permissions)
clientId
issuerId
realm
rsaPrivateKeyPath
shaThumbprint
- SharePoint On-Premise (NTLM handshake - more commonly used scenario):
username
- username without domainpassword
domain
/workstation
- SharePoint Online (Add-In permissions):
clientId
clientSecret
- SharePoint Online (SAML based with credentials - more commonly used scenario):
username
- user name for SP authentication [string, required]password
- password [string, required]
- ADFS user credantials:
username
password
relyingParty
adfsUrl
For more information please check node-sp-auth credential options and wiki pages.
spRootFolder
- root folder in SharePoint to pull from [string, required]dlRootFolder
- local root folder where files and folders will be saved to [string, optional, default:./Downloads
]spBaseFolder
- base folder path which is omitted then saving files locally [string, optional, default: equals to spRootFolder]recursive
- to pull all files and folders recursively [boolean, optional, default:true
]ignoreEmptyFolders
- to ignore local creation of SharePoint empty folders [boolean, optional, default:true
]foderStructureOnly
- to ignore files, recreate only folders' structure [boolean, optional, default:false
]strictObjects
- array of files and folders relative paths within thespRootFolder
to proceed explicitly, [array of strings, optional]camlCondition
- SharePoint CAML conditions to use [string, optional]spDocLibUrl
- SharePoint document library URL [string, mandatory withcamlCondition
]metaFields
- array of internal field names to request along with the files [array of strings, optional]createEmptyFolders
- to create empty folders along with documents download task [boolean, optional, default:true
]omitFolderPath
- folder path pattern which is omitted from final downloaded files path [string, optional]muteConsole
- to mute console messages during transport queries to SharePoint API [boolean, optional, default:false
]
- All files with folder structure from spRootFolder
- Files from spRootFolder folder, first hierarchy level only
- Folders structure from spRootFolder without files
- Files based on array of paths provided strictly [works with array of files only right now]
- Files based on CAML query conditions
- Pull for documents metadata to use it in callback's custom logic
Use case scenarios can be found on the Scenarios page. This page suggests combinations of options which are optimal for certain use cases.
Callback gets called upon successful files download.
Callback gets executed in case of exception inside sppull
. Accepts error object as first argument for callback.
Refer to the Scenarios page for suggested options combinations available with sppull
.
var sppull = require("sppull").sppull;
var context = {
siteUrl: "http://contoso.sharepoint.com/subsite",
creds: {
username: "user@contoso.com",
password: "_Password_"
}
};
var options = {
spRootFolder: "Shared%20Documents/Contracts",
dlRootFolder: "./Downloads/Contracts"
};
/*
* All files will be downloaded from http://contoso.sharepoint.com/subsite/Shared%20Documents/Contracts folder
* to __dirname + /Downloads/Contracts folder.
* Folders structure will remain original as it is in SharePoint's target folder.
*/
sppull(context, options)
.then(function(downloadResults) {
console.log("Files are downloaded");
console.log("For more, please check the results", JSON.stringify(downloadResults));
})
.catch(function(err) {
console.log("Core error has happened", err);
});
To eliminate any local password storing if preferable to use any two-way hashing technique, like cpass.
This project was inspired by spsave by Sergei Sergeev and gulp-spsync by Wictor Wilén projects.
SPPull depends heavily on sp-request module and use it to send REST queries to SharePoint.