A while back ago we already discussed how to consume SharePoint Online (SPO) REST in PowerShell. Here is a brief recap:
This time I would like demonstrate another approach, in particular how PowerShell can gain authorization to SharePoint resources by passing an access token to SharePoint with each HTTP request. To issue an access token from Microsoft Azure Access Control Service (ACS) that allows the app access to the resources in the SharePoint tenancy we will implement the corresponding PowerShell function. Let’s get started.
Getting Access Token from Microsoft Azure Access Control Service
The Get-SPOAccessToken function demonstrates how to obtain the access token from a Microsoft Azure Access Control Service (ACS) account that is associated with the customer’s Microsoft Office 365 tenancy:
Get-SPOAccessToken function is intended for requesting an access token from Azure ACS, it accepts Client Id and Client Secret parameters that are generated while App registration with Azure ACS (see “How to register App” for a more details).
Using Invoke-RestMethod in Office 365
Invoke-SPORestMethod function demonstrates how to include the access token to make a REST API call to SharePoint, passing the OAuth access token in the HTTP Authorization header:
The following example demonstrates how to retrieve List resource properties:
But before running the specified script we need to perform one more step in order to grant permissions to the app principal otherwise the unauthorized error will occur as shown on picture below:
- Navigate to http://<SharePointWebsite>/_layouts/15/AppInv.aspx
- Look up the app based on the Client ID that you just generated and click Lookup, it will find the app principal. Then paste the AppPermissionRequests XML into the Permissions text box and click Create
Once you click Create, the Trust dialog will appear, click Trust
That’s it. Now, after executing the specified script, the output will look like shown below
How to register App
Below is provided a step by step instruction how to register an App, for a complete guide follow this article:
- To create the app identity, navigate to http://<SharePointWebsite>/_layouts/15/AppRegNew.aspx on the tenancy or farm
- Enter values for the form fields as shown below on picture
App ID: App ID, also known as client ID, is a GUID that can be generated (when you click Generate) or pasted into AppRegNew.aspx. The value must be unique for each app, and must be lower case
App Secret: The app secret, also known as the client secret, is an opaque string. It is generated on the AppRegNew.aspx page by using the Generate button. The following is an example of an app secret: Ywjaoz7DJBGhoLQ2t0IbVCA5pfqqI722ZIVt+ENLk0g=
Title: Choose your own user-friendly title; for example, PowerShell Console
App Domain: The host name of the remote component of the app for SharePoint
Redirect URI: The endpoint in your remote application or service to which ACS sends an authentication code
- Click Create on the form. The page will reload and show a confirmation of the values you entered as shown on picture below
- Save Client Id and Client Secret values. After that you could verify whether Get-SPOAccessToken function returns access token. The picture below shows the output after executing the command:
Get-SPOAccessToken -ClientId “1523cf05-b437-4e73-9ad1-a652da8f2ae5” -ClientSecret “Ywjaoz7DJBGhoLQ2t0IbVCA5pfqqI722ZIVt+ENLk0g=” -WebUri “https://contoso.sharepoint.com/”
In the previous post we’ve already discussed how to perform CRUD operations by sending HTTPS requests to SharePoint RESTful web services in PoweShell. The Invoke-RestSPO function was introduced for that purpose since Invoke-RestMethod cmdlet does not support claims based authentication and it makes this cmdlet impossible to use in O365 and SharePoint Online scenarios.
This time I am going to demonstrate how to perform basic create, read, update, and delete (CRUD) operations on folders and files with the SharePoint 2013 REST interface using Invoke-RestSPO function.
SharePoint 20123 Files and Folders REST syntax
Working with folders
Folder resource: represents a folder on a SharePoint Web site
Endpoint URI: http://<site url>/_api/web/getfolderbyserverrelativeurl(‘/<folder name>‘)
Supported HTTP methods: GET | POST | DELETE | MERGE | PUT
The following examples demonstrates how to perform basic CRUD operations with Folder resource.
Working with files
Folder resource: represents a file in a SharePoint Web site that can be a Web Part Page, an item in a document library, or a file in a folder.
Endpoint URI: http://<site url>/_api/web/getfilebyserverrelativeurl(‘/<folder name>/<file name>‘)
Supported HTTP methods: GET | DELETE | POST (File resource)
The following examples demonstrates how to perform basic operations with File resource including:
- upload file into SharePoint
- download file from a SharePoint
To summarize, it was demonstrates how to perform basic operations with files and folders, in particular how to download and upload files via REST. For that purpose we utilized Invoke-RestSPO function that is intended for sending HTTPS requests to O365/SharePoint Online REST service.
SharePoint 2013 introduces a Representational State Transfer (REST) service that is comparable to the SharePoint CSOM and in addition to CSOM, REST API opens up a huge capabilities, in particular for administering and automating SharePoint Online when used with PowerShell.
Sending REST requests to a SharePoint Online
In the previous post we’ve already covered how to perform read operations by sending HTTPS requests to SharePoint RESTful web services. This time we are going to extend PowerShell script in order to support all the CRUD operations.
The Invoke-RestSPO function sends HTTPS requests to SharePoint REST web services that returns richly structured data (JSON)
Since SharePoint requires the user to include a request digest value with each create, update and delete operation, an additional request is invoked using Get-SPOContextInfo function to request Context Info entity that contains request digest value.
In order to avoid an additional request, “*” eTag value is used to match any eTag value resulting in the operation being performed regardless of the actual value.
Lists manipulation using REST API in PowerShell
This section contains sample code for all of the CRUD operations.
When it comes to using SharePoint 2010 Client Object Model (CSOM) we need to be ready for certain kind of limitations in PowerShell. First of all, it concerns the usage of Generics Methods, for the example ClientRuntimeContext.Load<T> method:
An attempt to call the method ClientRuntimeContext.Load<T> directly will result in the following error
This is a limitation of PowerShell (V1, V2) AFIK. There are several options how to bypass this limitation but in this post I would like to concentrate only on one technique that was originally described in the post Invoking Generic Methods on Non-Generic Classes in PowerShell. The basic idea is to replace the call for ClientRuntimeContext.Load<T> method with the following one:
For invoking a generic methods we utilize MethodInfo.MakeGenericMethod method. Below are demonstrated some examples of usage SharePoint 2010 Client Object Model (CSOM) in PowerShell.
Example: load Web client object
Let’s start with a simple example for loading Web Client Object:
Example: create Wiki page via CSOM
The example below demonstrates how to create wiki page via CSOM.
In contrary to article Using PowerShell to Get Data from a SharePoint 2010 List that explains how to execute generic methods via inline C# in PowerShell, this post demonstrates how to utilize Generics Methods in PowerShell natively.