Since SharePoint 2013 became part of the Office365 offering we now have the ability to use PowerShell to manipulate our SharePoint Site Collections in the cloud. The capabilities are somewhat limited compared to our on-prem solution as we cannot really manipulate Site Collections. This article outlines some of the available cmdlets and detail some examples of how to use them.
First of all, you need to download the cmdlets. Make sure you have PowerShell V3 installed along with the .NET Framework v4 or greater. Once you have these prerequisites download and install the cmdlets from Microsoft: http://www.microsoft.com/en-us/download/details.aspx?id=35588.
Once installed open the SharePoint Online Management Shell by clicking Start > All Programs > SharePoint Online Management Shell > SharePoint Online Management Shell. Just like with the SharePoint Management Shell for on-premises deployments the SharePoint Online Management Shell is just a standard PowerShell window.
Once the SharePoint Online Management Shell is installed you now need to connect to your tenant administration site. This initial connection is necessary to establish a connection context which stores the URL of the tenant administration site. To connect we use the Connect-SPOService cmdlet and then enter your credentials:
Connect-SPOService -Url https://tennantname-admin.sharepoint.com
If you want to log in as a different user or to a different site you can run the Disconnect-SPOService cmdlet.
Below I have outlined the cmdlets available for SharePoint online.
Add-SPOUser – Add a user to an existing Site Collection Site Group.
Get-SPOUser – Get an existing user.
Remove-SPOUser – Remove an existing user from the Site Collection or from an existing Site Collection Group.
Set-SPOUser – Set whether an existing Site Collection user is a Site Collection administrator or not.
Get-SPOExternalUser – Returns external users from the tenant’s folder.
Remove-SPOExternalUser – Removes a collection of external users from the tenancy’s folder.
Get-SPOSite – Retrieve an existing Site Collection.
New-SPOSite – Create a new Site Collection.
Remove-SPOSite – Move an existing Site Collection to the recycle bin.
Repair-SPOSite – If any failed Site Collection scoped health check rules can perform an automatic repair then initiate the repair.
Set-SPOSite – Set the Owner, Title, Storage Quota, Storage Quota Warning Level, Resource Quota, Resource Quota Warning Level, Locale ID, and/or whether the Site Collection allows Self Service Upgrade.
Test-SPOSite – Run all Site Collection health check rules against the specified Site Collection.
Upgrade-SPOSite – Upgrade the Site Collection. This can do a build-to-build (e.g., RTM to SP1) upgrade or a version-to-version (e.g., 2010 to 2013) upgrade. Use the -VersionUpgrade parameter for a version-to-version upgrade.
Get-SPODeletedSite – Get a Site Collection from the recycle bin.
Remove-SPODeletedSite – Remove a Site Collection from the recycle bin (permanently deletes it).
Restore-SPODeletedSite – Restores an item from the recycle bin.
Request-SPOUpgradeEvaluationSite – Creates a copy of the specified Site Collection and performs an upgrade on that copy.
Get-SPOWebTemplate – Get a list of all available web templates.
Get-SPOTenant – Retrieves information about the subscription tenant. This includes the Storage Quota size, Storage Quota Allocated (used), Resource Quota size, Resource Quota Allocated (used), Compatibility Range (14-14, 14-15, or 15-15), whether External Services are enabled, and the No Access Redirect URL.
Get-SPOTenantLogEntry – Retrieves company logs (as of B2 only BCS logs are available).
Get-SPOTenantLogLastAvailableTimeInUtc – Returns the time when the logs are collected.
Set-SPOTenant – Sets the Minimum and Maximum Compatibility Level, whether External Services are enabled, and the No Access Redirect URL.
Get a Site Collection
To see the list of Site Collections associated with a subscription or to see the details for a specific Site Collection use the Get-SPOSite cmdlet. This cmdlet has two parameter sets:
Get-SPOSite [[-Identity] <SpoSitePipeBind>] [-Limit <string>] [-Detailed] [<CommonParameters>]
Get-SPOSite [-Filter <string>] [-Limit <string>] [-Detailed] [<CommonParameters>]
The parameter that you’ll want to pay the most attention to is the -Detailed parameter. If this optional switch parameter is omitted then the SPOSite objects that will be returned will only have their properties partially set. Now you might think that this is in order to reduce the traffic between the server and the client, however, all the properties are still sent over the wire, they simply have default values for everything other than a couple core properties (so I would assume the only performance improvement would be in the query on the server). You can see the difference in the values that are returned by looking at a Site Collection with and without the details:
PS C:\> Get-SPOSite https://tennantname.sharepoint.com/ | select *
PS C:\> Get-SPOSite https://tennantname.sharepoint.com/ -Detailed | select *
Create a Site Collection
When we’re ready to create a Site Collection we can use the New-SPOSite cmdlet. This cmdlet is very similar to the New-SPSite cmdlet that we have for on-premises deployments. The following shows the syntax for the cmdlet:
New-SPOSite [-Url] <UrlCmdletPipeBind> -Owner <string> -StorageQuota <long> [-Title <string>] [-Template <string>] [-LocaleId <uint32>] [-CompatibilityLevel <int>] [-ResourceQuota <double>] [-TimeZoneId <int>] [-NoWait] [<CommonParameters>]
The following example demonstrates how we would call the cmdlet to create a new Site Collection called “Demo”:
New-SPOSite -Url https://tennantname.sharepoint.com/sites/Test -Title “Demo” -Owner “email@example.com” -Template “STS#0” -TimeZoneId 10 -StorageQuota 100
Note that the cmdlet also takes in a -NoWait parameter; this parameter tells the cmdlet to return immediately and not wait for the creation of the Site Collection to complete. If not specified then the cmdlet will poll the environment until it indicates that the Site Collection has been created. Using the -NoWait parameter is useful, however, when creating batches of Site Collections thereby allowing the operations to run asynchronously.
One issue you might bump into is in knowing which templates are available for your use. In the preceding example we are using the “STS#0” template, however, there are other templates available for our use and we can discover them using the Get-SPOWebTemplate cmdlet, as shown below:
PS C:\> Get-SPOWebTemplate
Name Title LocaleId CompatibilityLevel
—- —– ——– ——————
STS#0 Team Site 1033 15
BLOG#0 Blog 1033 15
BDR#0 Document Center 1033 15
DEV#0 Developer Site 1033 15
DOCMARKETPLACESITE#0 Academic Library 1033 15
OFFILE#1 Records Center 1033 15
EHS#1 Team Site – SharePoint Onl… 1033 15
BICenterSite#0 Business Intelligence Center 1033 15
SRCHCEN#0 Enterprise Search Center 1033 15
BLANKINTERNETCONTAINER#0 Publishing Portal 1033 15
ENTERWIKI#0 Enterprise Wiki 1033 15
PROJECTSITE#0 Project Site 1033 15
COMMUNITY#0 Community Site 1033 15
COMMUNITYPORTAL#0 Community Portal 1033 15
SRCHCENTERLITE#0 Basic Search Center 1033 15
visprus#0 Visio Process Repository 1033 15
Give Access to a Site Collection
Once your Site Collection has been created you may wish to grant users access to the Site Collection. First you may want to create a new SharePoint group (if an appropriate one is not already present) and then you may want to add users to that group (or an existing one). To accomplish these tasks you use the New-SPOSiteGroup cmdlet and the Add-SPOUser cmdlet, respectively.
Looking at the New-SPOSiteGroup cmdlet you can see that it takes only three parameters, the name of the group to create, the permissions to add to the group, and the Site Collection within which to create the group:
New-SPOSiteGroup [-Site] <SpoSitePipeBind> [-Group] <string> [-PermissionLevels] <string> [<CommonParameters>]
In the following example I’m creating a new group named “Designers” and giving it the “Design” permission:
$site = Get-SPOSite https://tennantname.sharepoint.com/sites/Test -Detailed
$group = New-SPOSiteGroup -Site $site -Group “Designers” -PermissionLevels “Design”
(Note that I’m seeing the Site Collection to a variable just to keep the commands a little shorter, you could just as easily provide the string URL directly).
Once the group is created we can then use the Add-SPOUser cmdlet to add a user to the group. Like the New-SPOSiteGroup cmdlet this cmdlet takes three parameters:
Add-SPOUser [-Site] <SpoSitePipeBind> [-LoginName] <string> [-Group] <string> [<CommonParameters>]
In the following example I’m adding a new user to the previously created group:
Add-SPOUser -Site $site -Group $group.LoginName -LoginName “firstname.lastname@example.org”
Delete and Recover a Site Collection
If you’ve created a Site Collection that you now wish to delete you can easily accomplish this by using the Remove-SPOSite cmdlet. When this cmdlet finishes the Site Collection will have been moved to the recycle bin and not actually deleted. If you wish to permanently delete the Site Collection (and thus remove it from the recycle bin) then you must use the Remove-SPODeletedSite cmdlet. So to do a permanent delete it’s actually a two step process, as shown in the example below where I first move the “Test” Site Collection to the recycle bin and then delete it from the recycle bin:
Remove-SPOSite “http://tennantname.sharepoint.com/sites/demo” -Confirm:$false
Remove-SPODeletedSite -Identity “http://tennantname.sharepoint.com/sites/demo” -Confirm:$false
If you decide that you’d actually like to restore the Site Collection from the recycle bin you can simply use the Restore-SPODeletedSite cmdlet:
Both the Remove-SPOSite and the Restore-SPODeletedSite cmdlets accept a –NoWait parameter which you can provide to tell the cmdlet to return immediately.