One of the great features of ShareFile’s v3 API are the OData Query Parameters; these are handy tools that can really improve the speed and quality of your code. Even better, they are available when using the PowerShell SDK.

In this post I will show examples of how you can easily add these parameters to your current PowerShell requests to optimize your scripts, improving execution time and preventing issues with bulk data manipulation.

The -Expand Parameter

The –Expand parameter allows you to retrieve both your primary entity as well as a related entity. For example if you wanted to get Zone information on an item, you could use:

Send-SfRequest –Client $sfClient –Entity Items -Expand Zone

This request would pull back both the original item as well as the related Zone information.

Now it is important to note the difference between –Navigation and –Expand parameters. You may already be familiar with the –Navigation parameter in PowerShell, this parameter allows you retrieve sub entities with your request, but does not bring back the primary entity.

For example, this request will return both your root Item as well as the related Children items.

Send-SfRequest –Client $sfClient –Entity Items –Expand Children

This request will ONLY return the related Children items
Send-SfRequest –Client $sfClient –Entity Items –Navigation Children

The -Select Parameter

The -Select parameter is another very handy tool to use and can significantly improve your scripts execution time.  –Select allows you to pull back only the information you need and there are many cases where you really only need an Item’s Id and Name and the extra data simply slows your script down. I’ve seen test cases with a 5x faster response time when limiting the data using -Select

Using –Select is as simple as writing which fields you would like to get back.  For example this request will bring back just the Id and Name of your root folder.

Send-SfRequest –Client $sfClient –Entity Items –Select "Id,FileName"

It is interesting to note the difference when using –Select with the –Expand and –Navigation parameters.

This request will return just the Id and Name of the root item, but the entire related Children items

Send-SfRequest –Client $sfClient –Entity Items –Expand Children –Select "Id,FileName"

If you want to get just the Id and Name of the Children items as well you will have to add the related Entity to the –Select parameter.
Send-SfRequest –Client $sfClient –Entity Items –Expand Children –Select "Id,FileName, Children/Id,Children/FileName"

Note that Children/Id this is the required format when limiting the fields of this specific related entity.  If you were doing a request for -Expand Zone for example it would be -Select “Zone/Id”.

This is easier when using –Navigation since this request only returns the Children items. Id and Filename work here without having to add in the related entity to the -Select

Send-SfRequest –Client $sfClient –Entity Items –Navigation Children –Select "Id,FileName"

The $Top and $Skip Parameters

The last OData parameters we will explore are related to limiting the amount of data you are using.  If you’re dealing with large amounts of items it is often easier to break down the request so you can manipulate the objects a few at a time.

$Top will return you X many items in the result set

$Skip will skip over the first X items in the result set.

Note: $Top and $Skip aren’t integrated into the PowerShell SDK at the current time, but the can be utilized as url Paramteters

This example code runs a loop that retrieves 1000 files at a time and only selects the Id.  This makes it very efficient for bulk item manipulation.   You can see how Top and Skip are used in conjunction to retrieve 1000 items at a time and then skips the items that are already retrieved.

$filesAtOnce = 1000;
for($x=0; $x -le $parentFolder.FileCount; $x+=$filesAtOnce){

      #We only need the file ID and the type in order to move so we make a minimal query adding in the top to grab only 1000 files at a time
      $files += Send-SfRequest -Client $sfClient -Entity Items -Id $parentID -Navigation Children -Select "Id" -Parameters @{'$top' = "$filesAtOnce"; '$skip' = "$x"}


Happy Scripting!

For more information on

ShareFile’s v3 API

PowerShell SDK and some sample scripts