Getting Started
The PowerShell SDK requires .NET 4.5 or later. This Microsoft article explains how to check which version you currently have installed or you can go to this site that will detect what version you have automatically.
The PowerShell SDK requires PowerShell 4 or later. You can check your current version by running the following command from within PowerShell (make sure the number under Major is > 4):
$PSVersionTable.PSVersion
Once you have the pre-requisites, you can install the ShareFile SDK from here.
To use the snap-in with your scripts, you will need to load it into a session. The best way to do this and get all the built-in formatting would be with this command:
Add-PSSnapIn ShareFile
To login to your ShareFile account, you can use this command:
New-SfClient -Name "C:\Users\Username\Documents\MySubdomain.sfps"
Note: The name provided here will be used to save the oAuth token for this connection. If you don't want to specify a full path, the file will be automatically created in "C:\Windows\System32\WindowsPowerShell\v1.0" (assuming you have access.) Subsequent scripts can access this user session without requiring an interactive user login or putting a password in your script. You should protect this token file as if it were credentials, though it can be revoked in the ShareFile application independent of a password if there is ever a concern of inappropriate access.
You can load this token file in scripts with a command like this (saving the session into a variable called $sfClient for use in other calls):
$sfClient = Get-SfClient –Name "C:\Users\Username\Documents\MySubdomain.sfps"
Once you have an authenticated session, you can make calls to the API as follows:
Send-SFRequest –Client $sfClient –Method GET –Entity Users
or
Send-SFRequest –Client $sfClient –Method GET –Entity Items
That is all you need to get started with accessing ShareFile via Powershell. Documentation for the ShareFile API entity model is available here: https://api.sharefile.com
ShareFile leverages a standards-based protocol called OData for accessing objects. You can learn more about OData here and there is a page on details specific to ShareFile here. Using the OData System Query Options, you can get fine-grained control over the data returned to you. Here are some examples:
$expand - This command retrieves related entities in addition to the entity requested. A good example of this can be seen when working with Groups. This call retrieves all the distribution groups:
Send-SfRequest -Client $sfClient -Entity Groups
...but what if you want to know who the owner is? That data is not retrieved by default, so you have to request it:
Send-SfRequest -Client $sfClient -Entity Groups -Expand Owner
...now when you are looking at your results, you will see the Owner details filled in as well. Here is an example of printing out the group name and owner for all groups:
$groups = Send-SfRequest -Client $sfClient -Entity Groups -Expand Owner
foreach ($group in $groups) {
Write-Host ("Group: {0} Owner: {1}" -f $group.Name, $group.Owner.FullName)
}
$Navigation - This parameter retrieves a related entity. Unlike $expand, sometimes you only want to retrieve the related entity and don't need the primary details at all. A good example of using this is with navigating your folder structure. This command retrieves the root of your home folder:
Send-SfRequest -Client $sfClient -Entity Items
...while this will retrieve the list of child items in your home folder:
Send-SfRequest -Client $sfClient -Entity Items -Navigation Children
$select - Sometimes you don't need all the data returned by an API call and for performance reasons would like to limit the amount of data that is returned. This parameter lets you specify exactly what data you are interested in. For example, this will only return the ID for the items in your home folder:
Send-SfRequest -Client $sfClient -Entity Items -Navigation Children -Select Id
$filter - Sometimes you want to filter the results on the server before they are sent to your client. An example of this might be extending the command from above that retrieves all items in your home folder so that it only retrieves the items that are of type folder:
Send-SfRequest -Client $sfClient -Entity Items -Navigation Children -Parameters @{'$filter'="__type eq 'ShareFile.Api.Models.Folder'"}
$top - This parameter allows you to retrieve a subset of results and is useful when you want to list items in batches (i.e. showing a page of users or files.) This command isn't directly integrated but you can still call it with -Parameters. Here is an example of retrieving the first 10 items in your Home Folder.
Send-SfRequest -Client $sfClient -Entity Items -Navigation Children -Parameters @{'$top' = '10'}
$skip - This parameter works together with $top to navigate through a large result. While $top determines how many to retrieve, $skip determines where in the list to start. This example would grab the next 10 items from your home folder.
Send-SfRequest -Client $sfClient -Entity Items -Navigation Children -Parameters @{'$top' = '10'; '$skip' = '10'}
This snap-in also includes a provider that will allow you to access ShareFile content from within your scripts. This is useful for scripting out sync tasks that need to run unattended or to sync specific folders or in specific ways (like unidirectional sync or to access network shares.)
Create the provider:
New-PSDrive -Name sf -PSProvider ShareFile -Root / -Client $sfClient
Access the provider:
Set-Location sf:
Copy files to/from ShareFile:
Copy-SFItem sf:/Folder/Folder C:\LocalFolder
Copy-SFItem C:\LocalFolder\* sf:/Folder
Note: You can also use del (Remove-Item), cd (Set-Location), and dir (Get-ChildItem) once the provider is created.