ShareFile recently released the PowerShell SDK for their v3 API to the open source community.  You can find the full project here https://github.com/citrix/ShareFile-PowerShell  PowerShell is an extremely useful tool for IT admins, so in this blog, I will talk about some basic functions of the SDK and some useful ways to use it in PowerShell.  In future posts, I will go further in depth, but this is more a guide for those just getting used to PowerShell and want to use ShareFile’s API to perform useful tasks.

You can find installation instructions on the GitHub page as well as some commands to get you started,  I will review a few of those commands before going further into the SDK’s capabilities.

Once you install the files using the installer and open up your PowerShell environment the first command you must execute is

Add-PSSnapin ShareFile

This will load the ShareFile dlls into your environment and allow you to utilize them.

Authentication

Once you have the ShareFile snapin installed in your PowerShell environment you can quickly get started with a very simple authentication method

New-SfClient

This command will call a web pop which will allow you to login into ShareFIle using your standard credentials.  The request generates oAuth and session tokens which are then passed back into PowerShell where they need to be stored for further requests.

You can do this in one of two ways:

The first way is to assign the authentication credentials to a variable in memory like so:

$sfLogin = New-SfClient

This will temporarily store the credentials as long as you have your PowerShell environment active.

A more permanent solution is to save the credentials to a file like this.

New-SfClient –Name "c:\tmp\sflogin.sfps"

I prefer to use a temporary directory, but you can use any directory you have read/write access to.

Once you create this file, you will no longer have to use the web form to login, and you can instead use Get-SfClient to retrieve the login information.

$sfLogin = Get-SfClient –Name "c:\tmp\sflogin.sfps"

This allows you to run scripts uninterrupted once you pass through the initial authentication.

Executing Requests

Now that we’ve gotten past authentication, we can discuss the good stuff – actually executing requests and getting back response data.

A sample request can look like this:

$sfItems = Send-SFRequest –Client $sfLogin –Method GET –Entity Items

This request will retrieve all the items the user has access to.  Items can include files, folders, notes and links.  The result set will be saved to the variable $sfItems which can be used later.

Let’s break down the above request.

-Client – this is the variable you saved your oAuth Login token to, in our case we are saving it to $sfLogin

-Method – this is the HTTP verb you are using for this request. The available verbs are

  • GET – Gets an entity
  • POST – Create an entity
  • PATCH – Update an entity
  • DELETE – Deletes an entity

-Entity – This is the actual API Object we are working with, you can find a full list of API entities at api.sharefile.com

Advanced Requests

We can take this a similar request and go a step further with some of the new OData capabilities

Send-SFRequest –Client $sfLogin -Method GET –Entity Users –Id 33ryh56h-fgh4 –Expand Security

You’ll notice 2 new parameters on this request, Id and Expand.

-Id – This parameter allows us to specify an Id for an Entity, in this case I am looking for a User with an Id of 33ryh56h-fgh4

-Expand – This parameter is one of the new OData query parameters, it allows us to retrieve entities related to our base entity.  In my example I am also retrieving the Security information for this particular User.

Let’s look at one last example

Send-SFRequest –Client $sfLogin –Entity Items –Expand Children –Select Children/FileName

This last request will retrieve just the FileNames of all the Children items in your Root Folder.  You’ll also notice I don’t have a Method this time,  this is because GET is the default method, so when you do a get you can actually skip this parameter if you wish.

-Expand Children – This special expand parameter retrieves all of the Children of whatever your primary item is.  You can define this primary item using –Id, but it will default to your primary ShareFile folder.

-Select – This OData parameter lets you limit the result set if you are only looking for specific data.  In the example we select Children/FileName, which means we are only looking for the FileName attribute of the Children object.

The / lets you Select the attributes of related entities.  For example the Children object also has a related Info object with an attribute CanDownload.

If you only wanted to see which Children objects are able to be downloaded you can create a –Select like this

-Select Children/FileName, Children/Info/CanDownload

This would only pull back the name of the child objects and the info of whether or not they can be downloaded.

With this information you can make basic calls to the API from your PowerShell client.  I am posting a second blog, where I will be talking about using PowerShell’s programming capabilities with the ShareFile SDK to create simple scripts.