April 4, 2015

Consume SharePoint Online REST service using .NET

Overview

Since the introduction of REST interface in SharePoint 2010 you have probably used WebClient or HttpWebRequest in .NET applications.
HttpClient is a modern HTTP client for .NET, it provides a flexible and extensible API for accessing resources via HTTP(S).
HttpClient offers some advantages over WebClient/HttpWebRequest such as:

An HttpClient instance is the place to configure extensions, set default headers, cancel outstanding requests and more.
You can issue as many requests as you like through a single HttpClient instance.
HttpClients are not tied to particular HTTP server or host; you can submit any HTTP request using the same HttpClient instance.
You can derive from HttpClient to create specialized clients for particular sites or patterns
HttpClient uses the new Task-oriented pattern for handling asynchronous requests making it dramatically easier to manage and coordinate multiple outstanding requests.

HttpClient for SharePoint Online

The solution consists of:

SPHttpClient class that inherits from HttpClient and provides some additional SharePoint specific functionaly such as getting request digest
SPHttpClientHandler class that basically hides all the intricacies related to SharePoint Online authentication

SharePoint Online client implementation

	using System;
	using System.Collections.Generic;
	using System.Net.Http;
	using System.Net.Http.Headers;
	using Newtonsoft.Json;
	using Newtonsoft.Json.Linq;

	namespace SharePoint.Client
	{
	/// <summary>
	/// Http client for SharePoint Online
	/// </summary>
	public class SPHttpClient : HttpClient
	{

	public SPHttpClient(Uri webUri, string userName, string password) : base(new SPHttpClientHandler(webUri, userName, password))
	{
	BaseAddress = webUri;
	}


	/// <summary>
	/// Execure request method
	/// </summary>
	/// <param name="requestUri"></param>
	/// <param name="method"></param>
	/// <param name="headers"></param>
	/// <param name="payload"></param>
	/// <returns></returns>
	public JObject ExecuteJson<T>(string requestUri, HttpMethod method, IDictionary<string, string> headers, T payload)
	{
	HttpResponseMessage response;
	switch (method.Method)
	{
	case "POST":
	var requestContent = new StringContent(JsonConvert.SerializeObject(payload));
	requestContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json;odata=verbose");
	DefaultRequestHeaders.Add("X-RequestDigest", RequestFormDigest());
	if (headers != null)
	{
	foreach (var header in headers)
	{
	DefaultRequestHeaders.Add(header.Key, header.Value);
	}
	}
	response = PostAsync(requestUri, requestContent).Result;
	break;
	case "GET":
	response = GetAsync(requestUri).Result;
	break;
	default:
	throw new NotSupportedException(string.Format("Method {0} is not supported", method.Method));
	}

	response.EnsureSuccessStatusCode();
	var responseContent = response.Content.ReadAsStringAsync().Result;
	return String.IsNullOrEmpty(responseContent) ? new JObject() : JObject.Parse(responseContent);
	}

	public JObject ExecuteJson<T>(string requestUri, HttpMethod method, T payload)
	{
	return ExecuteJson(requestUri, method, null, payload);
	}

	public JObject ExecuteJson(string requestUri)
	{
	return ExecuteJson(requestUri, HttpMethod.Get, null, default(string));
	}


	/// <summary>
	/// Request Form Digest
	/// </summary>
	/// <returns></returns>
	public string RequestFormDigest()
	{
	var endpointUrl = string.Format("{0}/_api/contextinfo", BaseAddress);
	var result = this.PostAsync(endpointUrl, new StringContent(string.Empty)).Result;
	result.EnsureSuccessStatusCode();
	var content = result.Content.ReadAsStringAsync().Result;
	var contentJson = JObject.Parse(content);
	return contentJson["d"]["GetContextWebInformation"]["FormDigestValue"].ToString();
	}
	}
	}

view raw

SPHttpClient.cs

hosted with ❤ by GitHub

SharePoint Online HTTP handler implementation

	using System;
	using System.Net;
	using System.Net.Http;
	using System.Net.Http.Headers;
	using System.Security;
	using System.Threading;
	using System.Threading.Tasks;
	using Microsoft.SharePoint.Client;

	namespace SharePoint.Client
	{
	public class SPHttpClientHandler : HttpClientHandler
	{
	public SPHttpClientHandler(Uri webUri, string userName, string password)
	{
	CookieContainer = GetAuthCookies(webUri, userName, password);
	FormatType = FormatType.JsonVerbose;
	}


	protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
	{
	request.Headers.Add("X-FORMS_BASED_AUTH_ACCEPTED", "f");
	if (FormatType == FormatType.JsonVerbose)
	{
	//request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json;odata=verbose"));
	request.Headers.Add("Accept", "application/json;odata=verbose");
	}
	return base.SendAsync(request, cancellationToken);
	}


	/// <summary>
	/// Retrieve SPO Auth Cookies
	/// </summary>
	/// <param name="webUri"></param>
	/// <param name="userName"></param>
	/// <param name="password"></param>
	/// <returns></returns>
	private static CookieContainer GetAuthCookies(Uri webUri, string userName, string password)
	{
	var securePassword = new SecureString();
	foreach (var c in password) { securePassword.AppendChar(c); }
	var credentials = new SharePointOnlineCredentials(userName, securePassword);
	var authCookie = credentials.GetAuthenticationCookie(webUri);
	var cookieContainer = new CookieContainer();
	cookieContainer.SetCookies(webUri, authCookie);
	return cookieContainer;
	}


	public FormatType FormatType { get; set; }
	}

	public enum FormatType
	{
	JsonVerbose,
	Xml
	}
	}

view raw

SPHttpClientHandler.cs

hosted with ❤ by GitHub

Working with list items with REST

The following example shows how to retrieve all of a list’s items:

	using (var client = new SPHttpClient(webUri, userName, password))
	{
	var listTitle = "Tasks";
	var endpointUrl = string.Format("{0}/_api/web/lists/getbytitle('{1}')/items",webUri,listTitle);
	var data = client.ExecuteJson(endpointUrl);
	foreach (var item in data["value"])
	{
	Console.WriteLine(item["Title"]);
	}
	}

view raw

Example.GetListItems.cs

hosted with ❤ by GitHub

The following example shows how to retrieve a specific list item:

	using (var client = new SPHttpClient(webUri, userName, password))
	{
	var listTitle = "Tasks";
	var itemId = 1;
	var endpointUrl = string.Format("{0}/_api/web/lists/getbytitle('{1}')/items({2})",webUri,listTitle,itemId);
	var data = client.ExecuteJson(endpointUrl);
	Console.WriteLine(data["Title"]);
	}

view raw

Example.GetListItem.cs

hosted with ❤ by GitHub

The following example shows how to create a list item:

	using (var client = new SPHttpClient(webUri, userName, password))
	{
	var listTitle = "Tasks";
	var itemPayload = new { __metadata = new { type = "SP.Data.TasksListItem" }, Title = "Approval Task"};
	var endpointUrl = string.Format("{0}/_api/web/lists/getbytitle('{1}')/items",webUri,listTitle);
	var data = client.ExecuteJson(endpointUrl,HttpMethod.Post,itemPayload);
	Console.WriteLine("Task item '{0}' has been created",data["Title"]);
	}

view raw

Example.CreateItem.cs

hosted with ❤ by GitHub

The following example shows how to update a list item:

	using (var client = new SPHttpClient(webUri, userName, password))
	{
	var listTitle = "Tasks";
	var itemId = 1;
	var itemPayload = new { __metadata = new { type = "SP.Data.TasksListItem" }, Title = "Approval Task"};
	var endpointUrl = string.Format("{0}/_api/web/lists/getbytitle('{1}')/items({2})",webUri,listTitle,itemId);
	var headers = new Dictionary<string,string>();
	headers["IF-MATCH"] = "*";
	headers["X-HTTP-Method"] = "MERGE";
	client.ExecuteJson(endpointUrl,HttpMethod.Post,headers, itemPayload);
	Console.WriteLine("Task item has been updated");
	}

view raw

Example.UpdateListItem.cs

hosted with ❤ by GitHub

The following example shows how to delete a list item:

	using (var client = new SPHttpClient(webUri, userName, password))
	{
	var listTitle = "Tasks";
	var itemId = 2;
	var endpointUrl = string.Format("{0}/_api/web/lists/getbytitle('{1}')/items({2})",webUri,listTitle,itemId);
	var headers = new Dictionary<string,string>();
	headers["IF-MATCH"] = "*";
	headers["X-HTTP-Method"] = "DELETE";
	client.ExecuteJson(endpointUrl,HttpMethod.Post,null,headers);
	Console.WriteLine("Task item has been deleted");
	}

view raw

Example.DeleteListItem.cs

hosted with ❤ by GitHub

January 27, 2015

Consuming the SharePoint Online REST API from PowerShell: Part 2

Introduction

A while back ago we already discussed how to consume SharePoint Online (SPO) REST in PowerShell. Here is a brief recap:

it was stated that Invoke-RestMethod cmdlet could not be utilized for performing REST requests since it does not support claims-based authentication
a custom Invoke-RestSPO function has been implemented that sends HTTPS requests to SPO RESTful web services. A SharePointOnlineCredentials class from SharePoint Client Component SDK was utilized for authentication which represents an object that provides credentials to access SharePoint Online resources.

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:

	<#
	.Synopsis
	Obtain an app-only access token from ACS.
	.DESCRIPTION
	Retrieves an app-only access token from ACS to call the specified principal
	at the specified targetHost. The targetHost must be registered for target principal. If specified realm is
	null, the "Realm" setting in web.config will be used instead
	.EXAMPLE
	Get-SPOAccessToken -Url "https://contoso.sharepoint.com/_api/web" -ClientId "" -ClientSecret ""
	#>
	Function Get-SPOAccessToken([string]$ClientId,[string]$ClientSecret,[Uri]$WebUri){
	$SharePointPrincipal = "00000003-0000-0ff1-ce00-000000000000"
	$realm = GetRealmFromTargetUrl –TargetApplicationUri $WebUri
	$accessToken = GetAppOnlyAccessToken –ClientId $ClientId –ClientSecret $ClientSecret –TargetPrincipalName $SharePointPrincipal –TargetHost $WebUri.Authority –TargetRealm $realm
	return $accessToken.access_token
	}

	function GetRealmFromTargetUrl([Uri]$TargetApplicationUri)
	{

	$url = $WebUrl + "/_vti_bin/client.svc"
	$headers = @{}
	$headers.Add('Authorization','Bearer')
	try {
	$response = Invoke-WebRequest –Uri $TargetApplicationUri –Headers $headers –Method Get
	}
	catch [Net.WebException] {
	$authResponseHeader = $_.Exception.Response.Headers["WWW-Authenticate"]
	#$bearerKey = "Bearer realm="
	$bearer = $authResponseHeader.Split(",")[0]
	$targetRealm = $bearer.Split("=")[1]
	return $targetRealm.Substring(1,$targetRealm.Length–2)
	}
	return $null
	}


	Function GetAppOnlyAccessToken([string]$ClientId,[string]$ClientSecret,[string]$TargetPrincipalName,[string]$TargetHost,[string]$TargetRealm)
	{
	$resource = GetFormattedPrincipal –PrincipalName $TargetPrincipalName –HostName $TargetHost –Realm $TargetRealm
	$ClientId = GetFormattedPrincipal –PrincipalName $ClientId –Realm $TargetRealm
	$contentType = 'application/x-www-form-urlencoded'
	$stsUrl = GetSecurityTokenServiceUrl –Realm $TargetRealm
	$oauth2Request = CreateAccessTokenRequestWithClientCredentials –ClientId $ClientId –ClientSecret $ClientSecret –Scope $resource
	$oauth2Response = Invoke-RestMethod –Method Post –Uri $stsUrl –ContentType $contentType –Body $oauth2Request
	return $oauth2Response
	}


	Function GetSecurityTokenServiceUrl([string]$Realm)
	{
	return "https://accounts.accesscontrol.windows.net/$Realm/tokens/OAuth/2"
	}


	Function CreateAccessTokenRequestWithClientCredentials([string]$ClientId,[string]$ClientSecret,[string]$Scope)
	{
	$oauth2Request = @{
	'grant_type' = 'client_credentials';
	'client_id' = $ClientId;
	'client_secret' = $ClientSecret;
	'scope' = $Scope;
	'resource' = $Scope
	}
	return $oauth2Request
	}

	function GetFormattedPrincipal([string]$PrincipalName, [string]$HostName, [string]$Realm)
	{
	if ($HostName)
	{
	return "$PrincipalName/$HostName@$Realm"
	}
	return "$PrincipalName@$Realm"
	}

view raw

Get-SPOAccessToken.ps1

hosted with ❤ by GitHub

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:

	.\Get-SPOAccessToken.ps1

	<#
	.Synopsis
	Sends an HTTP or HTTPS request to a SharePoint Online REST-compliant web service.
	.DESCRIPTION
	This function sends an HTTP or HTTPS request to a Representational State
	Transfer (REST)-compliant ("RESTful") SharePoint Online web service.
	.EXAMPLE
	Invoke-SPORestMethod -Uri "https://contoso.sharepoint.com/_api/web" -AccessToken $accessToken
	#>
	Function Invoke-SPORestMethod()
	{
	Param(
	[Uri]$Uri,
	[Object]$Body,
	[Hashtable]$Headers,
	[Microsoft.PowerShell.Commands.WebRequestMethod]$Method = [Microsoft.PowerShell.Commands.WebRequestMethod]::Get,
	[string]$AccessToken
	)
	$contentType = 'application/json;odata=verbose'
	if(-not $Headers) {
	$Headers = @{}
	}
	$Headers["Accept"] = "application/json;odata=verbose"
	$Headers.Add('Authorization','Bearer ' + $AccessToken)
	Invoke-RestMethod –Method $Method –Uri $Uri –ContentType $contentType –Headers $Headers –Body $Body
	}

view raw

Invoke-SPORestMethod.ps1

hosted with ❤ by GitHub

Examples

The following example demonstrates how to retrieve List resource properties:

	param (
	$ClientId,
	$ClientSecret,
	$WebUri,
	$ListTitle
	)

	.\Get-SPOAccessToken.ps1




	Function Get-SPOList([Uri]$WebUri,[string]$ClientId,[string]$ClientSecret,[Uri]$ListTitle)
	{
	$accessToken = Get-SPOAccessToken –ClientId $ClientId –ClientSecret $ClientSecret –WebUri $WebUri
	$endpointUri = "$WebUri/_api/web/lists/getbytitle('$ListTitle')"
	$data = Invoke-SPORestMethod –Uri $endpointUri –AccessToken $accessToken
	return $data.d
	}


	Get-SPOList –WebUri $WebUri –ClientId $ClientId –ClientSecret $ClientSecret –ListTitle $ListTitle

view raw

Get-SPOList.ps1

hosted with ❤ by GitHub

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

where
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/”

References

Posted in Office 365, PowerShell, SharePoint Online
Tagged ACS, OAuth, PowerShell, REST
3 Comments

January 9, 2015

Enterprise Keywords management in Office 365 via CSOM

Overview

SharePoint 2013 has introduced Microsoft.SharePoint.Client.Taxonomy namespace for metadata management via CSOM. Since Taxonomy API also allows to manage Keywords, i would like to demonstrate how to get/set Enterprise Keywords field values in this post.

Adding Enterprise Keywords column into List

The first example demonstrates how to add Enterprise Keywords column into List:

	private static void AddTaxkeywordFieldInList(List list)
	{
	var ctx = list.Context as ClientContext;
	var taxKeywordField = ctx.Site.RootWeb.Fields.GetByInternalNameOrTitle("TaxKeyword");
	var taxKeywordFieldInList = list.Fields.Add(taxKeywordField);
	ctx.ExecuteQuery();
	}

view raw

AddTaxkeywordFieldInList.cs

hosted with ❤ by GitHub

Setting Enterprise Keywords field value

The below example demonstrates how to set Enterprise Keywords field value:

	using System;
	using System.Collections.Generic;
	using System.Linq;
	using Microsoft.SharePoint.Client;
	using Microsoft.SharePoint.Client.Taxonomy;

	namespace SharePoint.Client.Taxonomy
	{
	/// <summary>
	/// Enterpise Keyword Manager
	/// </summary>
	public class KeywordsManager
	{

	/// <summary>
	/// Set Enterprise Keyword Value
	/// </summary>
	/// <param name="item">List Item</param>
	/// <param name="values">Keyword values</param>
	public static void SetTaxKeywordValue(ListItem item,string[] values)
	{
	var ctx = item.Context;
	var list = item.ParentList;
	var field = list.Fields.GetByInternalNameOrTitle(TaxKeywordFieldName);
	var taxKeywordField = ctx.CastTo<TaxonomyField>(field);
	var keywords = values.Select(value => EnsureKeyword(taxKeywordField, value)).ToList();
	taxKeywordField.SetFieldValueByValueCollection(item, new TaxonomyFieldValueCollection(ctx, GetTermsString(keywords), taxKeywordField));
	}


	/// <summary>
	/// Ensure Keyword
	/// </summary>
	/// <param name="taxField"></param>
	/// <param name="name"></param>
	/// <returns></returns>
	private static Term EnsureKeyword(TaxonomyField taxField, string name)
	{
	var ctx = taxField.Context;
	var taxSession = TaxonomySession.GetTaxonomySession(ctx);
	var termStore = taxSession.GetDefaultKeywordsTermStore();
	var keywords = termStore.KeywordsTermSet.GetAllTerms();
	var result = ctx.LoadQuery(keywords.Where(k => k.Name == name));
	ctx.ExecuteQuery();
	var keyword = result.FirstOrDefault();
	if (keyword != null)
	{
	return keyword;
	}
	keyword = termStore.KeywordsTermSet.CreateTerm(name, DefaultLanguage, Guid.NewGuid());
	ctx.Load(keyword);
	ctx.ExecuteQuery();
	return keyword;
	}

	/// <summary>
	/// Retrieve formatted Term string
	/// </summary>
	/// <param name="term"></param>
	/// <returns></returns>
	private static string GetTermString(Term term)
	{
	return string.Format("-1;#{0}{1}{2}", term.Name, TaxonomyGuidLabelDelimiter,term.Id);
	}

	private static string GetTermsString(IEnumerable<Term> terms)
	{
	var termsString = terms.Select(GetTermString).ToList();
	return string.Join(";#", termsString);
	}



	private const string TaxKeywordFieldName = "TaxKeyword";

	private const int DefaultLanguage = 1033;

	private const string TaxonomyGuidLabelDelimiter = "\|";
	}
	}

view raw

KeywordsManager.cs

hosted with ❤ by GitHub

Key points:

The operation of setting Enterprise Keywords field value consists of two steps, first one to resolve Keyword in Managed Metadata service application (MMS), this what EnsureKeyword method is intended for. After Keyword has been retrieved or created if it not existed, the value of Enterprise Keyword field is set (TaxonomyFieldValueCollection type).

Usage

	using (var ctx = new ClientContext(webUri))
	{
	ctx.Credentials = CreateSPOCredentials(userName, password);
	var list = ctx.Web.Lists.GetByTitle(listTitle);
	var item = list.GetItemById(itemId);
	KeywordsManager.SetTaxKeywordValue(item,new []{"2013","2010"});
	item.Update();
	ctx.ExecuteQuery();
	}

	public static SharePointOnlineCredentials CreateSPOCredentials(string userName,string password)
	{
	var securePassword = new SecureString();
	foreach (var ch in password)
	{
	securePassword.AppendChar(ch);
	}
	return new SharePointOnlineCredentials(userName, securePassword);
	}

view raw

KeywordsManager.SetTaxKeywordValue.cs

hosted with ❤ by GitHub

Results

Posted in Office 365, SharePoint 2013, SharePoint Online
Tagged CSOM, Enterprise Keywords
7 Comments

November 9, 2014

An alternative way of getting Client Object properties using SharePoint REST and CSOM APIs

When working with client APIs such as JSOM or REST you have probably noticed that certain properties of objects are not available compared to SSOM counterparts. For example, SPList class exposes SPList.Author property for getting an SPUser object that represents information about the user who created the list which in turn is not available for SP.List object. Hence the question arises, how those properties could be retrieved using client APIs?

The solution that I would like to demonstrate is based on retrieving client object properties from XML schema.

Getting SP.List object properties using JSOM

The function getListProperties is indented for loading list schema of the SP.List using SP.List.schemaXml property and extracting properties from it’s value:

	function getListProperties(listTitle, OnSuccess,OnError) {

	var context = SP.ClientContext.get_current();
	var web = context.get_web();
	var list = web.get_lists().getByTitle(listTitle);

	context.load(web);
	context.load(list,'SchemaXml');

	context.executeQueryAsync(function(){
	var schemaXml = list.get_schemaXml();
	var listJson = schemaXml2Json(schemaXml);
	OnSuccess(listJson);
	},OnError);
	}



	function schemaXml2Json(schemaXml)
	{
	var jsonObject = {};
	var schemaXmlDoc = $.parseXML(schemaXml);
	$(schemaXmlDoc).find('List').each(function() {
	$.each(this.attributes, function(i, attr){
	jsonObject[attr.name] = attr.value;
	});
	});
	return jsonObject;
	}

view raw

getListProperties.js

hosted with ❤ by GitHub

The following example demonstrates how to retrieve Author property using the specified method:

Example:

	function getListAuthor(listTitle,OnSuccess,OnError) {
	getListProperties(listTitle,
	function(listJson){
	var context = SP.ClientContext.get_current();
	var listAuthor = context.get_web().getUserById(listJson.Author);
	context.load(listAuthor);
	context.executeQueryAsync(
	function(){
	OnSuccess(listAuthor);
	},OnError);
	},
	OnError);
	}


	//Usage
	getListAuthor('Discussion Board',
	function(author){
	console.log('List created by: ' + author.get_loginName());
	},
	function(sender,args){
	console.log('Error occured:' + args.get_message());
	}
	);

view raw

getListAuthor.js

hosted with ❤ by GitHub

Getting SP.List object properties using REST

The following REST endpoint is used for retrieving SP.List.schemaXml property:

http://<sitecollection>/<site>/_api/web/lists/getbytitle(listtitle)/schemaXml

	function getJson(url)
	{
	return $.ajax({
	url: url,
	type: "GET",
	contentType: "application/json;odata=verbose",
	headers: {
	"Accept": "application/json;odata=verbose"
	}
	});
	}


	function getListProperties(listTitle) {
	var listEndpointUrl = _spPageContextInfo.webAbsoluteUrl + "/_api/web/lists/getbytitle('" + listTitle + "')/SchemaXml";
	return getJson(listEndpointUrl).then(
	function(data){
	var schemaXml = data.d.SchemaXml;
	return schemaXml2Json(schemaXml);
	});
	}

view raw

getListProperties.js

hosted with ❤ by GitHub

Example:

The same example that demonstrates how to retrieve Author property of List resource using REST:

	getListProperties('Discussion Board')
	.done(function(properties)
	{
	console.log('List created by: ' + properties.Author);
	})
	.fail(
	function(error){
	console.log(JSON.stringify(error));
	});

view raw

getListAuthor.js

hosted with ❤ by GitHub

Posted in JavaScript, JQuery, SharePoint
Tagged JSOM, REST, SP.List
Leave a comment

September 25, 2014

Manage User Custom Actions in Office 365

Overview

Custom Actions offer a flexible way to extend capabilities of the SharePoint. The possibilities span the range of including custom JavaScript on every page to extending the Ribbon. In SharePoint 2013/SharePoint Online you can leverage the CSOM/REST to manage custom actions. Below are demonstrated two simple examples of using custom actions in real world scenarios and I hope you you’ll find them useful.

Example 1. Enable jQuery

Let’s get started with an example that demonstrate how to add jQuery library to Office 365/SharePoint Online site. Unfortunately it is not supported to reference external resources, for example from Microsoft Ajax Content Delivery Network (CDN) that hosts popular third party JavaScript libraries including jQuery. The prerequisite for referencing JavaScript files is that they could only be accesible when located within the site collection. So, the first step would be to save a jQuery library into Style Library: /Style Library/Scripts/jQuery/jquery-2.1.1.js.

The following Activate-JQuery.ps1 script demonstrates how to enable jQuery library in Office 365/SharePoint Online site

	param(
	[string]$SiteUrl,
	[string]$UserName,
	[string]$Password
	)

	. ".\UserCustomActions.ps1"

	<#
	.SYNOPSIS
	Enable jQuery Library
	.DESCRIPTION
	Enable jQuery Library in Office 365/SharePoint Online site
	.EXAMPLE
	.\Activate-JQuery.ps1 -SiteUrl "https://tenant-public.sharepoint.com" -UserName "username@tenant.onmicrosoft.com" -Password "password"
	#>
	Function Activate-JQuery([string]$SiteUrl,[string]$UserName,[string]$Password)
	{
	$context = New-Object Microsoft.SharePoint.Client.ClientContext($SiteUrl)
	$context.Credentials = Get-SPOCredentials –UserName $UserName –Password $Password

	$sequenceNo = 1482
	$jQueryUrl = "~SiteCollection/Style Library/Scripts/jQuery/jquery-2.1.1.js"
	Add-ScriptLinkAction –Context $Context –ScriptSrc $jQueryUrl –Sequence $sequenceNo

	$context.Dispose()
	}


	Activate–JQuery –SiteUrl $SiteUrl –UserName $UserName –Password $Password

view raw

Activate-JQuery.ps1

hosted with ❤ by GitHub

Dependencies: UserCustomActions.ps1

Example 2. Enable Google Analytics

The following Activate-GoogleAnalytics.ps1 script demonstrates how to activate tracking code in Office 365/SharePoint Online site

	param(
	[string]$SiteUrl,
	[string]$UserName,
	[string]$Password
	)

	. ".\UserCustomActions.ps1"

	<#
	.SYNOPSIS
	Activate Google Analytics
	.DESCRIPTION
	Activate Google Analytics in Office 365/SharePoint Online site
	.EXAMPLE
	.\Activate-GoogleAnalytics.ps1 -SiteUrl "https://tenant-public.sharepoint.com" -UserName "username@tenant.onmicrosoft.com" -Password "password"
	#>


	Function Activate-GoogleAnalytics([string]$SiteUrl,[string]$UserName,[string]$Password)
	{
	$context = New-Object Microsoft.SharePoint.Client.ClientContext($SiteUrl)
	$context.Credentials = Get-SPOCredentials –UserName $UserName –Password $Password

	$sequenceNo = 1480
	#Insert your Tracking code here or specify valid Tracking ID
	$TrackingCode = "(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]\|\|function(){
	(i[r].q=i[r].q\|\|[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
	m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
	})(window,document,'script','//www.google-analytics.com/analytics.js','ga');

	ga('create', 'UA-XXXXXXXX-X', 'auto');
	ga('send', 'pageview');"

	Add-ScriptLinkAction –Context $Context –ScriptBlock $TrackingCode –Sequence $sequenceNo

	$context.Dispose()
	}


	Activate–GoogleAnalytics –SiteUrl $SiteUrl –UserName $UserName –Password $Password

view raw

Activate-GoogleAnalytics.ps1

hosted with ❤ by GitHub

Dependencies: UserCustomActions.ps1

Follow these instructions to use Google Analytics to collect data from Office 365/SharePoint Online sites.

To set up the web tracking code:

Find the tracking code snippet for your property.
Sign in to your Google Analytics account, and click Admin in the top menu bar. From the Account and Propertycolumns, select the property you’re working with. Click Tracking Info / Tracking Code.
Find your tracking code snippet. It’s in a box with several lines of JavaScript in it. Everything in this box is your tracking code snippet. It starts with <script> and ends with </script>.
The tracking code contains a unique ID that corresponds to each Google Analytics property. Don’t mix up tracking code snippets from different properties, and don’t reuse the same tracking code snippet on multiple domains. Click to expand this image and see where the tracking code snippet is in the interface.
Open Activate-GoogleAnalytics.ps1, paste the tracking code into $TrackingCode variable and run the script to register tracking code in Office 365/SharePoint Online site
Check your set up.
Make sure that the tracking snippet installed on your website matches the code shown in the view, and see more ways you can verify your set up.

Posted in Google Analytics, JQuery, Office 365, PowerShell, SharePoint Online
Tagged Ajax, CDN, jQuery, UserCustomActions
2 Comments

August 24, 2014

Working with folders and files via SharePoint 2013 REST in PowerShell

Overview

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.

Explore the REST service files and folder syntax

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.

	[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client")
	[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime")
	. ".\Invoke-RestSPO.ps1"

	<#
	.SYNOPSIS
	Retieve Folder
	.DESCRIPTION
	Read Folder operation via SharePoint 2013 REST API
	url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Shared Documents')
	method: GET
	headers:
	Authorization: "Bearer " + accessToken
	accept: "application/json;odata=verbose" or "application/atom+xml"
	.NOTES
	Prerequisite : Invoke-RestSPO function
	.EXAMPLE
	$Folder = Get-SPOFolder -WebUrl $WebUrl -UserName $UserName -Password $Password -FolderUrl '/Shared Documents/Folder To Read'
	#>
	Function Get-SPOFolder(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$FolderUrl

	)


	$Url = $WebUrl + "/_api/web/GetFolderByServerRelativeUrl('" + $FolderUrl + "')"
	Invoke-RestSPO $Url Get $UserName $Password
	}

	<#
	.SYNOPSIS
	Create Folder
	.DESCRIPTION
	Create Folder operation via SharePoint 2013 REST API.
	url: http://site url/_api/web/folders
	method: POST
	body: { '__metadata': { 'type': 'SP.Folder' }, 'ServerRelativeUrl': '/document library relative url/folder name'}
	Headers:
	Authorization: "Bearer " + accessToken
	X-RequestDigest: form digest value
	accept: "application/json;odata=verbose"
	content-type: "application/json;odata=verbose"
	content-length:length of post body
	.NOTES
	Prerequisite : Invoke-RestSPO function
	.EXAMPLE
	$Folder = Create-SPOFolder -WebUrl $WebUrl -UserName $UserName -Password $Password -FolderUrl '/Shared Documents/Folder To Create'
	#>
	Function Create-SPOFolder(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$FolderUrl

	)


	$Url = $WebUrl + "/_api/web/folders"
	$folderPayload = @{
	__metadata = @{'type' = 'SP.Folder' };
	ServerRelativeUrl = $FolderUrl;
	} \| ConvertTo-Json


	$contextInfo = Get-SPOContextInfo $WebUrl $UserName $Password
	Invoke-RestSPO –Url $Url –Method Post –UserName $UserName –Password $Password –Metadata $folderPayload –RequestDigest $contextInfo.GetContextWebInformation.FormDigestValue
	}


	<#
	.SYNOPSIS
	Update Folder
	.DESCRIPTION
	Update Folder operation via SharePoint 2013 REST API.
	url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')
	method: POST
	body: { '__metadata': { 'type': 'SP.Folder' }, 'Name': 'New name' }
	Headers:
	Authorization: "Bearer " + accessToken
	X-RequestDigest: form digest value
	"IF-MATCH": etag or "*"
	"X-HTTP-Method":"MERGE",
	accept: "application/json;odata=verbose"
	content-type: "application/json;odata=verbose"
	content-length:length of post body
	.NOTES
	Prerequisite : Invoke-RestSPO function
	.EXAMPLE
	Update-SPOFolder -WebUrl $WebUrl -UserName $UserName -Password $Password -FolderUrl '/Shared Documents/Folder To Update' -FolderName "New Folder Name"
	#>
	Function Update-SPOFolder(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$FolderUrl,

	[Parameter(Mandatory=$True)]
	[String]$FolderName

	)


	$Url = $WebUrl + "/_api/web/GetFolderByServerRelativeUrl('" + $FolderUrl + "')"
	$folderPayload = @{
	__metadata = @{'type' = 'SP.Folder' };
	}
	if($FolderName) {
	$folderPayload['Name'] = $FolderName
	}

	$folderPayload = $folderPayload \| ConvertTo-Json


	$contextInfo = Get-SPOContextInfo $WebUrl $UserName $Password
	Invoke-RestSPO –Url $Url –Method Post –UserName $UserName –Password $Password –Metadata $folderPayload –RequestDigest $contextInfo.GetContextWebInformation.FormDigestValue –ETag "*" –XHTTPMethod "MERGE"
	}

	<#
	.SYNOPSIS
	Delete Folder
	.DESCRIPTION
	Delete Folder operation via SharePoint 2013 REST API.
	url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')
	method: POST
	Headers:
	Authorization: "Bearer " + accessToken
	X-RequestDigest: form digest value
	"IF-MATCH": etag or "*"
	"X-HTTP-Method":"DELETE"
	.NOTES
	Prerequisite : Invoke-RestSPO function
	.EXAMPLE
	Delete-SPOFolder -WebUrl $WebUrl -UserName $UserName -Password $Password -FolderUrl '/Shared Documents/Folder To Delete'
	#>
	Function Delete-SPOFolder(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$FolderUrl

	)


	$Url = $WebUrl + "/_api/web/GetFolderByServerRelativeUrl('" + $FolderUrl + "')"
	$contextInfo = Get-SPOContextInfo $WebUrl $UserName $Password
	Invoke-RestSPO –Url $Url –Method Post –UserName $UserName –Password $Password –RequestDigest $contextInfo.GetContextWebInformation.FormDigestValue –ETag "*" –XHTTPMethod "DELETE"
	}

view raw

Folders-RestSPO.ps1

hosted with ❤ by GitHub

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

	[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client")
	[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime")
	. ".\Invoke-RestSPO.ps1"

	<#
	.SYNOPSIS
	Retieve Files in Folder
	.DESCRIPTION
	Read Files operation via SharePoint 2013 REST API
	url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files
	method: GET
	headers:
	Authorization: "Bearer " + accessToken
	accept: "application/json;odata=verbose" or "application/atom+xml"
	.NOTES
	Prerequisite : Invoke-RestSPO function
	.EXAMPLE
	$Files = Get-SPOFiles -WebUrl $WebUrl -UserName $UserName -Password $Password -FolderUrl '/Shared Documents/Folder'
	#>
	Function Get-SPOFiles(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$FolderUrl

	)


	$Url = $WebUrl + "/_api/web/GetFolderByServerRelativeUrl('" + $FolderUrl + "')/Files"
	Invoke-RestSPO $Url Get $UserName $Password \| % { $_.results }
	}




	<#
	.SYNOPSIS
	Delete File
	.DESCRIPTION
	Delete Files operation via SharePoint 2013 REST API
	url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')
	method: POST
	headers:
	Authorization: "Bearer " + accessToken
	X-RequestDigest: form digest value
	IF-MATCH: etag or "*"
	X-HTTP-Method:"DELETE"
	.NOTES
	Prerequisite : Invoke-RestSPO function
	.EXAMPLE
	Delete-SPOFile -WebUrl $WebUrl -UserName $UserName -Password $Password -FileUrl '/Shared Documents/Folder/File To Delete'
	#>
	Function Delete-SPOFile(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$FileUrl

	)


	$Url = $WebUrl + "/_api/web/GetFileByServerRelativeUrl('" + $FileUrl + "')"
	$contextInfo = Get-SPOContextInfo $WebUrl $UserName $Password
	Invoke-RestSPO –Url $Url –Method Post –UserName $UserName –Password $Password –RequestDigest $contextInfo.GetContextWebInformation.FormDigestValue –ETag "*" –XHTTPMethod "DELETE"
	}



	<#
	.SYNOPSIS
	Download File
	.DESCRIPTION
	Read File operation via SharePoint 2013 REST API
	url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/$value
	method: GET
	headers:
	Authorization: "Bearer " + accessToken
	.NOTES
	Prerequisite : Invoke-RestSPO function
	.EXAMPLE
	Download-SPOFile -WebUrl $WebUrl -UserName $UserName -Password $Password -FileUrl '/Shared Documents/Folder/File To Download' -DownloadPath 'c:\downloads'
	#>
	Function Download-SPOFile(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$True)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$FileUrl,

	[Parameter(Mandatory=$True)]
	[String]$DownloadPath

	)

	$Url = $WebUrl + "/_api/web/GetFileByServerRelativeUrl('" + $FileUrl + "')/`$value"
	$fileContent = Invoke-RestSPO –Url $Url –Method Get –UserName $UserName –Password $Password –BinaryStringResponseBody $True

	#Save
	$fileName = [System.IO.Path]::GetFileName($FileUrl)
	$downloadFilePath = [System.IO.Path]::Combine($DownloadPath,$fileName)
	[System.IO.File]::WriteAllBytes($downloadFilePath,$fileContent)
	}







	<#
	.SYNOPSIS
	Upload File
	.DESCRIPTION
	Create File operation via SharePoint 2013 REST API
	url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')
	method: POST
	headers:
	Authorization: "Bearer " + accessToken
	X-RequestDigest: form digest value
	IF-MATCH: etag or "*"
	X-HTTP-Method:"DELETE"
	.NOTES
	Prerequisite : Invoke-RestSPO function
	.EXAMPLE
	Upload-SPOFile -WebUrl $WebUrl -UserName $UserName -Password $Password -FolderUrl '/Shared Documents/Folder' -UploadFilePath 'Physical Path to File'
	#>
	Function Upload-SPOFile(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$True)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$FolderUrl,

	[Parameter(Mandatory=$True)]
	[String]$UploadFilePath

	)

	$FileInfo = New-Object System.IO.FileInfo($UploadFilePath)
	$Url = $WebUrl + "/_api/web/GetFolderByServerRelativeUrl('" + $FolderUrl + "')/Files/add(url='" + $FileInfo.Name + "',overwrite=true)"
	$FileContent = [System.IO.File]::ReadAllBytes($FileInfo.FullName)

	$contextInfo = Get-SPOContextInfo $WebUrl $UserName $Password
	Invoke-RestSPO –Url $Url –Method Post –UserName $UserName –Password $Password –Body $FileContent –RequestDigest $contextInfo.GetContextWebInformation.FormDigestValue
	}

view raw

Files-RestSPO.ps1

hosted with ❤ by GitHub

Summary

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.

References

Posted in PowerShell, SharePoint Online, Uncategorized
Tagged Invoke-RestSPO, O365, PowerShell, REST, SharePoint
7 Comments

July 29, 2014

How to: Upload files into Office 365 via PowerShell

Overview

Being one of the most common questions “How to upload files to SharePoint Library?”, i noticed that usually folder structure is not taken into account in the provided solutions.
So i decided to fill the gap and implement another version that allows to preserve folder structure while uploading files.

Prerequisites

SharePoint client components SDK have to be installed on the machine running the script

PowerShell script

PowerShell script demonstrates how to upload files within a specified local directory to a Document Library within a Site in an O365 tenant.

	Add-Type –Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.dll"
	Add-Type –Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"



	Function Ensure-Folder()
	{
	Param(
	[Parameter(Mandatory=$True)]
	[Microsoft.SharePoint.Client.Web]$Web,

	[Parameter(Mandatory=$True)]
	[Microsoft.SharePoint.Client.Folder]$ParentFolder,

	[Parameter(Mandatory=$True)]
	[String]$FolderUrl

	)

	$folderNames = $FolderUrl.Trim().Split("/",[System.StringSplitOptions]::RemoveEmptyEntries)
	$folderName = $folderNames[0]
	Write-Host "Creating folder [$folderName] …"
	$curFolder = $ParentFolder.Folders.Add($folderName)
	$Web.Context.Load($curFolder)
	$web.Context.ExecuteQuery()
	Write-Host "Folder [$folderName] has been created succesfully. Url: $($curFolder.ServerRelativeUrl)"

	if ($folderNames.Length -gt 1)
	{
	$curFolderUrl = [System.String]::Join("/", $folderNames, 1, $folderNames.Length – 1)
	Ensure–Folder –Web $Web –ParentFolder $curFolder –FolderUrl $curFolderUrl
	}
	}



	Function Upload-File()
	{
	Param(
	[Parameter(Mandatory=$True)]
	[Microsoft.SharePoint.Client.Web]$Web,

	[Parameter(Mandatory=$True)]
	[String]$FolderRelativeUrl,

	[Parameter(Mandatory=$True)]
	[System.IO.FileInfo]$LocalFile

	)

	try {
	$fileUrl = $FolderRelativeUrl + "/" + $LocalFile.Name
	Write-Host "Uploading file [$($LocalFile.FullName)] …"
	[Microsoft.SharePoint.Client.File]::SaveBinaryDirect($Web.Context, $fileUrl, $LocalFile.OpenRead(), $true)
	Write-Host "File [$($LocalFile.FullName)] has been uploaded succesfully. Url: $fileUrl"
	}
	catch {
	write-host "An error occured while uploading file [$($LocalFile.FullName)]"
	}
	}




	function Upload-Files()
	{

	Param(
	[Parameter(Mandatory=$True)]
	[String]$Url,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$TargetListTitle,

	[Parameter(Mandatory=$True)]
	[String]$SourceFolderPath

	)

	if($Password) {
	$SecurePassword = $Password \| ConvertTo-SecureString –AsPlainText –Force
	}
	else {
	$SecurePassword = Read-Host –Prompt "Enter the password" –AsSecureString
	}
	$Context = New-Object Microsoft.SharePoint.Client.ClientContext($Url)
	$Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($UserName,$SecurePassword)
	$Context.Credentials = $Credentials


	$web = $Context.Web
	$Context.Load($web)
	$list = $web.Lists.GetByTitle($TargetListTitle);
	$Context.Load($list.RootFolder)
	$Context.ExecuteQuery()


	Get-ChildItem $SourceFolderPath –Recurse \| % {
	if ($_.PSIsContainer -eq $True) {
	$folderUrl = $_.FullName.Replace($SourceFolderPath,"").Replace("\","/")
	if($folderUrl) {
	Ensure–Folder –Web $web –ParentFolder $list.RootFolder –FolderUrl $folderUrl
	}
	}
	else{
	$folderRelativeUrl = $list.RootFolder.ServerRelativeUrl + $_.DirectoryName.Replace($SourceFolderPath,"").Replace("\","/")
	Upload–File –Web $web –FolderRelativeUrl $folderRelativeUrl –LocalFile $_
	}
	}
	}



	#Usage


	$Url = "https://contoso.sharepoint.com"
	$UserName = "username@contoso.onmicrosoft.com"
	$Password = "password"
	$TargetListTitle = "Documents" #Target Library
	$SourceFolderPath = "C:\Users\user\Upload" #Source Physical Path


	#Upload files
	Upload–Files –Url $Url –UserName $UserName –Password $Password –TargetListTitle $TargetListTitle –SourceFolderPath $SourceFolderPath

view raw

SPOUpload-Files.ps1

hosted with ❤ by GitHub

May 31, 2014

SharePoint Online client for PHP

In this post I would like to introduce you to a SharePoint client for PHP available on GitHub. The library provides a SharePoint Online (SPO) client for PHP applications. It allows you to performs CRUD operations on SharePoint data using an SharePoint 2013 REST/OData based API.

API

PHP:cURL library is used to make HTTP requests to performs CRUD operations on SharePoint data using SharePoint 2013 REST API.

Getting started

A first example

	<?php

	$username = 'username@tenant.onmicrosoft.com';
	$password = 'password';
	$url = "https://tenant.sharepoint.com/";


	try {
	$authCtx = new AuthenticationContext($Url);
	$authCtx->acquireTokenForUser($username,$password);
	$ctx = new ClientContext($Url,$authCtx);
	printTasks($ctx);
	}
	catch (Exception $e) {
	echo 'Authentication failed: ', $e->getMessage(), "\n";
	}

	function printTasks(ClientContext $ctx){

	$listTitle = 'Tasks';
	$web = $ctx->getWeb();
	$list = $web->getLists()->getByTitle($listTitle);
	$items = $list->getItems();
	$ctx->load($items);
	$ctx->executeQuery();
	foreach( $items->getData() as $item ) {
	print "Task: '{$item->Title}'\r\n";
	}
	}

	?>

view raw

SPOFirstExample.php

hosted with ❤ by GitHub

Key points:

SPOClient class represents a REST Service client for the specified SharePoint Online (SPO) site
The signIn method performs a claims-based authentication. You can find more details about remote authentication in Remote authentication in SharePoint Online post.

The following examples demonstrates how to perform the remaining CRUD operations on SharePoint list data.

	<?php

	require_once 'SPOClient.php';

	$username = 'username@tenant.onmicrosoft.com';
	$password = 'password';
	$url = "https://tenant.sharepoint.com/";

	$client = new SPOClient($url);
	$client->signIn($username,$password);

	//Get Tasks list
	$listTitle = 'Tasks';
	$list = $client->getList($listTitle);

	//Create a Task item
	$itemProperties = array('Title' => 'Order Approval', 'Body' => 'Order approval task');
	$taskItem = $list->addItem($itemProperties);
	print "Task '{$taskItem->Title}' has been created succesfully.\r\n";

	$itemId = $taskItem->Id;
	//Update a Task item
	$itemProperties = array('PercentComplete' => 1);
	$list->updateItem($itemId,$itemProperties);

	//Delete a Task item
	$list->deleteItem($itemId);

	?>

view raw

ListExamples.php

hosted with ❤ by GitHub

List data generator

And finally one more example that demonstrates how to populate Contacts list in SharePoint. For generating fake data we will utilize Faker PHP library, below is provided the complete example:

	<?php

	require_once __DIR__ . '/../../Faker/src/autoload.php'; //Faker library (https://github.com/fzaninotto/Faker)
	require_once 'SPOClient.php';

	$username = 'username@tenant.onmicrosoft.com';
	$password = 'password';
	$url = "https://tenant.sharepoint.com/";

	generateContacts($url,$username,$password);


	function generateContacts($url,$username,$password){

	$client = new SPOClient($url);
	$client->signIn($username,$password);

	$list = $client->getList('Contacts');
	$contactsCount = 120;
	for($i = 0; $i < $contactsCount; $i++){
	$contactEntry = createContactEntry();
	$item = $list->addItem($contactEntry);
	print "Contact '{$item->Title}' has been created succesfully.\r\n";
	}

	}

	function createContactEntry()
	{
	$contactCard = Faker\Factory::create();
	return array('Title' => $contactCard->username,
	'FullName' => $contactCard->name,
	'Email' => $contactCard->email,
	'Company' => $contactCard->company,
	'WorkPhone' => $contactCard->phoneNumber,
	'WorkAddress' => $contactCard->streetAddress,
	'WorkCity' => $contactCard->city,
	'WorkZip' => $contactCard->postcode,
	'WorkCountry' => $contactCard->country,
	'WebPage' => array ('Url' => $contactCard->url)
	);
	}

	?>

view raw

ListDataGenerator.php

hosted with ❤ by GitHub

Summary

The library currently supports CRUD operations against SharePoint list data. But since SharePoint 2013 REST covers a much broader set of API, the library could be extended.

Hopefully this helps you get started how you can interact with a SharePoint Online site from a remote Web application written in PHP!

May 8, 2014

Consuming the SharePoint 2013 REST Service from SharePoint Designer

In SharePoint 2013 workflows was introduced a new action named Call HTTP Web Service. This action is flexible enough to make requests to a variety web services including SharePoint REST service.

Figure 1 shows you the Call HTTP Web Service action on the SharePoint Designer 2013 surface.

Figure 1. SPD Workflow that demonstrates how to leverage Call HTTP Web Service action for Read operation

The specified example demonstrates how to perform Read operation for retrieving webs information:

Create a workflow variable named Url and set it’s value to [%Workflow Context:Current Site URL%]_api/web/webinfos
Insert Build Dictionary action to construct request headers. Add key value pairs from table 1. Save results into a variable of type Dictionary and named RequestHeaders
Insert Call HTTP Web Service action. Open Properties window and specify it’s properties as shown in table 2.

Table 1. Request Headers for a RequestHeaders dictionary variable

Name	Type	Value
Accept	String	application/json;odata=verbose
Content-Type	String	application/json;odata=verbose

Table 2. Call HTTP Web Service action properties for Read operation

Property Name	Value
Address	Set value to variable Url that was created in step 1
RequestType	Set value to HTTP GET
RequestHeaders	Set value to dictionary variable RequestHeaders that we’ve constructed to store request header properties in step 2
ResponseContent	Create a new dictionary variable named Result for storing the response returned by the REST service and set value to variable Result

Scenario: Create Site Workflow

The below example demonstrates how to perform Create operation using Call HTTP Web Service action, in particular how to create web site from a workflow.

Note: In order to perform Create/Update/Delete operations using Call HTTP Web Service action, App permissions for workflow have to be configured. Please follow the steps in article Create a workflow with elevated permissions by using the SharePoint 2013 Workflow platform to configure App permissions for workflow.

Figure 2 shows you the configured Call HTTP Web Service action for creating web site

SPD Workflow

Figure 2. SharePoint Designer workflow for creating web site

Steps:

1. Create a workflow variable named Url and set it’s value to [%Workflow Context:Current Site URL%]_api/web/webinfos/add

2,3 and 5. Those steps serve for building payload to submit to the service. RequestContent parameter of Call HTTP Web Service action is used for setting payloads to submit to the service. See tables 4,5 and 6 for a details.

4. Insert Build Dictionary action to construct request headers. Add key value pairs from table 1. Save results into a variable of type Dictionary and named RequestHeaders

6. Insert Call HTTP Web Service action. Open Properties window and specify it’s properties as shown in table 3.

Table 3. Call HTTP Web Service action properties for Create operation

Property Name	Value
Address	Set value to variable Url that was created in step 1
RequestType	Set value to HTTP POST
RequestHeaders	Set value to dictionary variable RequestHeaders that we’ve constructed to store request header properties in step 4
RequestContent	Set value to dictionary variable RequestContent that was created for storing payload in step 5
ResponseContent	Create a new dictionary variable named Result for storing the response returned by the REST service and set value to variable Result

Specifying web site creation information

For building payload to be submitted to the service the following dictionary variables are initialized in the workflow

Table 4. Metadata dictionary variable

Name	Type	Value
type	String	SP.WebInfoCreationInformation

Table 5. WebParameters dictionary variable

Name	Type	Value
__metadata	Dictionary	Variable:Metadata
Url	String	Parameter:WebTitle
Title	String	Parameter:WebTitle
Description	String	Parameter:WebDesc
Language	Integer	Parameter:Language
WebTemplate	String	sts
UseIniquePermissions	Boolean	false

Table 6. RequestContent dictionary variable

Name	Type	Value
parameters	Dictionary	Variable:WebParameters

For passing information about web site, an Initiation form is used as shown on figure 3

Figure 3. Initiation Form

References

Posted in SharePoint 2013, SharePoint Online
Tagged Call HTTP Web Service, REST, SharePoint Designer, SharePoint Workflow, SPD
8 Comments

April 15, 2014

Consuming the SharePoint 2013 REST API from PowerShell

Introduction

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)

	Add-Type –Path "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.dll"
	Add-Type –Path "C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"

	<#
	.Synopsis
	Sends an HTTP or HTTPS request to a SharePoint Online REST-compliant web service.
	.DESCRIPTION
	This function sends an HTTP or HTTPS request to a Representational State
	Transfer (REST)-compliant ("RESTful") SharePoint Online web service.
	.EXAMPLE
	Invoke-SPORestMethod -Url "https://contoso.sharepoint.com/_api/web"
	.EXAMPLE
	Invoke-SPORestMethod -Url "https://contoso.sharepoint.com/_api/contextinfo" -Method "Post"
	#>

	Function Invoke-RestSPO(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$Url,

	[Parameter(Mandatory=$False)]
	[Microsoft.PowerShell.Commands.WebRequestMethod]$Method = [Microsoft.PowerShell.Commands.WebRequestMethod]::Get,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$False)]
	[String]$Metadata,

	[Parameter(Mandatory=$False)]
	[System.Byte[]]$Body,

	[Parameter(Mandatory=$False)]
	[String]$RequestDigest,

	[Parameter(Mandatory=$False)]
	[String]$ETag,

	[Parameter(Mandatory=$False)]
	[String]$XHTTPMethod,

	[Parameter(Mandatory=$False)]
	[System.String]$Accept = "application/json;odata=verbose",

	[Parameter(Mandatory=$False)]
	[String]$ContentType = "application/json;odata=verbose",

	[Parameter(Mandatory=$False)]
	[Boolean]$BinaryStringResponseBody = $False

	)




	if([string]::IsNullOrEmpty($Password)) {
	$SecurePassword = Read-Host –Prompt "Enter the password" –AsSecureString
	}
	else {
	$SecurePassword = $Password \| ConvertTo-SecureString –AsPlainText –Force
	}


	$credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($UserName, $SecurePassword)
	$request = [System.Net.WebRequest]::Create($Url)
	$request.Credentials = $credentials
	$request.Headers.Add("X-FORMS_BASED_AUTH_ACCEPTED", "f")
	$request.ContentType = $ContentType
	$request.Accept = $Accept
	$request.Method=$Method

	if($RequestDigest) {
	$request.Headers.Add("X-RequestDigest", $RequestDigest)
	}
	if($ETag) {
	$request.Headers.Add("If-Match", $ETag)
	}
	if($XHTTPMethod) {
	$request.Headers.Add("X-HTTP-Method", $XHTTPMethod)
	}
	if($Metadata -or $Body) {
	if($Metadata) {
	$Body = [byte[]][char[]]$Metadata
	}
	$request.ContentLength = $Body.Length
	$stream = $request.GetRequestStream()
	$stream.Write($Body, 0, $Body.Length)
	}
	else {
	$request.ContentLength = 0
	}

	#Process Response
	$response = $request.GetResponse()
	try {
	if($BinaryStringResponseBody -eq $False) {
	$streamReader = New-Object System.IO.StreamReader $response.GetResponseStream()
	try {
	$data=$streamReader.ReadToEnd()
	$results = $data \| ConvertFrom-Json
	$results.d
	}
	finally {
	$streamReader.Dispose()
	}
	}
	else {
	$dataStream = New-Object System.IO.MemoryStream
	try {
	Stream–CopyTo –Source $response.GetResponseStream() –Destination $dataStream
	$dataStream.ToArray()
	}
	finally {
	$dataStream.Dispose()
	}
	}
	}
	finally {
	$response.Dispose()
	}

	}


	# Get Context Info
	Function Get-SPOContextInfo(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password
	)


	$Url = $WebUrl + "/_api/contextinfo"
	Invoke-RestSPO $Url Post $UserName $Password
	}



	Function Stream-CopyTo([System.IO.Stream]$Source, [System.IO.Stream]$Destination)
	{
	$buffer = New-Object Byte[] 8192
	$bytesRead = 0
	while (($bytesRead = $Source.Read($buffer, 0, $buffer.Length)) -gt 0)
	{
	$Destination.Write($buffer, 0, $bytesRead)
	}
	}

view raw

Invoke-RestSPO.ps1

hosted with ❤ by GitHub

Request Digests

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.

ETag

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.

	#———————————————————————————————-
	# List CRUD operations via SharePoint REST API
	#———————————————————————————————-


	# Create a List
	Function New-SPOList(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$Title,

	[Parameter(Mandatory=$True)]
	[String]$BaseTemplate
	)

	$listMetadata = @{
	__metadata = @{'type' = 'SP.List' };
	Title = $Title;
	BaseTemplate = $BaseTemplate} \| ConvertTo-Json


	$Url = $WebUrl + "/_api/lists"

	$contextInfo = Get-SPOContextInfo $WebUrl $UserName $Password
	Invoke-RestSPO $Url Post $UserName $Password $listMetadata $contextInfo.GetContextWebInformation.FormDigestValue
	}

	# Update a List
	Function Set-SPOList(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$Identity,

	[Parameter(Mandatory=$False)]
	[String]$Title,

	[Parameter(Mandatory=$False)]
	[String]$Description
	)

	$listMetadata = @{
	__metadata = @{'type' = 'SP.List' };
	}
	if($Title) {
	$listMetadata['Title'] = $Title
	}
	if($Description) {
	$listMetadata['Description'] = $Description
	}
	$listMetadata = $listMetadata \| ConvertTo-Json


	$Url = $WebUrl + "/_api/lists/getbytitle('" + $Identity + "')"

	$contextInfo = Get-SPOContextInfo $WebUrl $UserName $Password
	Invoke-RestSPO –Url $Url –Method Post –UserName $UserName –Password $Password –RequestDigest $contextInfo.GetContextWebInformation.FormDigestValue –Metadata $listMetadata –ETag "*" –XHTTPMethod "MERGE"
	}


	#Get List(s)
	Function Get-SPOList(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password
	)

	$Url = $WebUrl + "/_api/lists"
	$data = Invoke-RestSPO $Url Get $UserName $Password
	$data.results
	}


	#Delete a List
	Function Remove-SPOList(){

	Param(
	[Parameter(Mandatory=$True)]
	[String]$WebUrl,

	[Parameter(Mandatory=$True)]
	[String]$UserName,

	[Parameter(Mandatory=$False)]
	[String]$Password,

	[Parameter(Mandatory=$True)]
	[String]$Identity
	)

	$Url = $WebUrl + "/_api/lists/getbytitle('" + $Identity + "')"
	$contextInfo = Get-SPOContextInfo $WebUrl $UserName $Password
	Invoke-RestSPO –Url $Url –Method Post –UserName $UserName –Password $Password –RequestDigest $contextInfo.GetContextWebInformation.FormDigestValue –ETag "*" –XHTTPMethod "DELETE"
	}

view raw

ListOps-RestSPO.ps1

hosted with ❤ by GitHub

References

Posted in PowerShell, SharePoint Online
Tagged PowerShell, REST, SharePoint, SharePoint Online
6 Comments