[Azure] From Function to SharePoint List Item

Technical / January 2, 2017 / Jasper Siegmund / 10

This article describes how to insert an item into a SharePoint list using an Azure Function written in C#. Might seem like a trivial task, but there are some caveats you might want to take notice of before you start.

Graph vs SharePoint REST API

To begin with, we need to choose how we’re going to insert items in SharePoint lists. The Microsoft Graph should be your consideration for every API action in Office365, but the SharePoint endpoints are still in beta at this moment. For production systems, I would always recommend waiting a bit until the technology is out of beta.

So if we consider Graph as “not an option”, we need to look at what SharePoint offers itself, instead. There’s multiple ways to Rome, but the REST API surely is one of the most logical ones, so we’ll go with that. Added benefit is that with the REST API you can pretty much do anything, so this article can be used as the foundation for any Function that does something in SharePoint.

Authentication

The next thing to consider is how to go about authentication. In case of an Azure Function, there’s no user interaction possible. So we need to authenticate without the need for a UI where a user enters credentials or delegates access (OAuth) in any way. This is known as an app-only (or add-in only) action in SharePoint and it requires configuration and getting an access token.

Important: in all of the examples for Microsoft Graph or other Azure AD based authentication, the access token comes from Azure AD. SharePoint Online does not support these tokens (yet, hopefully) so you can’t use such a token!

Ok, so how are we going to get this access token? Having a client ID and secret (read on…), you can get one from the access control token endpoint. Here’s the code you’ll need:

public static async Task<string> GetAuthTokenForSharePoint()
{
    HttpClient client = new HttpClient();

    string clientId = System.Configuration.ConfigurationManager.AppSettings["SP_CLIENT_ID"];
    string clientSecret = System.Configuration.ConfigurationManager.AppSettings["SP_CLIENT_SECRET"];
    string tenantId = System.Configuration.ConfigurationManager.AppSettings["SP_TENANT_ID"];
    string spTenantUrl = System.Configuration.ConfigurationManager.AppSettings["SP_TENANT_URL"];
    string spPrinciple = "00000003-0000-0ff1-ce00-000000000000";
    string spAuthUrl = "https://accounts.accesscontrol.windows.net/" + tenantId + "/tokens/OAuth/2";

    KeyValuePair<string, string>[] body = new KeyValuePair<string, string>[]
    {
        new KeyValuePair<string, string>("grant_type", "client_credentials"),
        new KeyValuePair<string, string>("client_id", $"{clientId}@{tenantId}"),
        new KeyValuePair<string, string>("resource", $"{spPrinciple}/{spTenantUrl}@{tenantId}".Replace("https://", "")),
        new KeyValuePair<string, string>("client_secret", clientSecret)
    };

    var content = new FormUrlEncodedContent(body);
    var contentLength = content.ToString().Length;

    string token = "";

    using (HttpResponseMessage response = await client.PostAsync(spAuthUrl, content))
    {
        if (response.Content != null)
        {
            string responseString = await response.Content.ReadAsStringAsync();
            JObject data = JObject.Parse(responseString);
            token = data.Value<string>("access_token");
        }
    }

    return token;
}

As you see there are some variables involved:

• clientId: this is the GUID of the application you’ve registered in SharePoint.
• clientSecret: the secret key of that same application
• tenantId: in SharePoint this is also known as the “realm”; it’s actually the GUID of the Azure AD instance you’re SharePoint Online tenant is linked to. There’s more than one ways to find out what it is; I always head over to the old management portal (manage.windowsazure.com) and open up your Azure Active Directory instance. The GUID will be part of the URL.
• tenantUrl: the is the URL to the SharePoint environment, so https://<<tenantname>>.sharepoint.com
• spPrinciple: this is a static GUID value: “00000003-0000-0ff1-ce00-000000000000”
• siteUrl: the URL to the SharePoint Online tenant
• spAuthUrl: points to accounts.accesscontrol.windows.net, which will be the token endpoint for the authentication request

I’ve configured most of these as app settings of my Azure Function, but of course you can also store them somewhere else or hardcode them for trial & error purposes.

Digest

Having only the token is not enough. SharePoint REST API calls also require passing in a digest, although the documentation here says this is not required when using add-in authentication. Despite that, I found that I’m getting errors nonetheless when leaving it out. The only way around seems to be involving certificates, which makes things much more complicated. So I prefer just getting the digest, which requires a second http post request:

public static async Task<string> GetDigestForSharePoint(string siteUrl, string token)
{
    HttpClient client = new HttpClient();

    client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);
    client.DefaultRequestHeaders.Add("accept", "application/json;odata=verbose");
    StringContent content = new StringContent("");

    string spTenantUrl = System.Configuration.ConfigurationManager.AppSettings["SP_TENANT_URL"];
    string digest = "";

    using (HttpResponseMessage response = await client.PostAsync($"{spTenantUrl}{siteUrl}/_api/contextinfo", content))
    {        
        if (response.IsSuccessStatusCode)
        {
            string contentJson = response.Content.ReadAsStringAsync().Result;
            JObject val = JObject.Parse(contentJson);
            JToken d = val["d"];
            JToken wi = d["GetContextWebInformation"];
            digest = wi.Value<string>("FormDigestValue");
        }
    }

    return digest;
}

So this is basically an empty post to /_api/contextinfo, which will return you a  response with the digest. Note that you need the authentication token from the previous method before you can actually do this, otherwise your call will just be rejected. You should also be aware that both token and digest have expiration dates, but that’s only relevant should your function take a longer time to complete. Mine runs in about one second so no need to be bothered about that.

Register your SharePoint add-in

If you have already done development with the SharePoint add-in model, this should be familiar. In order to do anything with the SharePoint API’s, you’ll need to have an add-in registered. You can do so by heading over to <siteurl>/_layouts/15/AppInv.aspx. The MSDN article here has some detailed information on how to do this. Note that the domain and redirect URL in this case are not that important, since we won’t be hosting any UI for this add-in.

When creating a new add-in registration, ensure that you give the add-in the correct permissions. Of course this depends on what your Azure Function will exactly do. For testing purposes, use the following XAML:

<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl" />
</AppPermissionRequests>

This will give the Azure Function control over everything in that specific site collection.

The client ID and client secret you get from this process are the ones you need to specify in the authentication calls above. Should anything fail, use Fiddler to inspect the contents of your requests and responses, those should give you some more detail on what’s going on. Also, http://jwt.calebb.net/ offers a quick way to decode the token you’ve been given, very useful to see what’s really in there!

Completing the Function

Now we have everything in place to actually go and do stuff! The last and final method we’ll need in our function is the one that creates a SharePoint list item:

public static async Task CreateSharePointListItem(string siteUrl, string listName, string itemTitle, TraceWriter log)
{
    try
    {
        var token = await GetAuthTokenForSharePoint();
        var digest = await GetDigestForSharePoint(siteUrl, token);

        HttpClient client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);
        client.DefaultRequestHeaders.Add("accept", "application/json;odata=verbose");
        client.DefaultRequestHeaders.Add("X-RequestDigest", digest);
        client.DefaultRequestHeaders.Add("X-HTTP-Method", "POST");

        HttpContent content = new StringContent($"{{ '__metadata': {{ 'type': 'SP.ListItem' }}, 'Title': '{itemTitle}'}}");
        content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
        content.Headers.ContentType.Parameters.Add(new NameValueHeaderValue("odata", "verbose"));

        string spTenantUrl = System.Configuration.ConfigurationManager.AppSettings["SP_TENANT_URL"];

        using (HttpResponseMessage response = await client.PostAsync($"{spTenantUrl}{siteUrl}/_api/web/Lists/GetByTitle('{listName}')/items", content))
        {
            if (!response.IsSuccessStatusCode)
                log.Error($"The REST call to SharePoint failed: {response.StatusCode.ToString()}.");
        }
    }
    catch (Exception ex)
    {
        log.Error($"Could not write SharePoint list item: {ex}");
    }
}

So that’s http request #3. We first need to get the authentication token and digest from the methods seen above. Then you’re all set to fire off any REST call to SharePoint. This can be used to create items, query lists, create sites, you name it. The only thing you need to do now is call the right URL and pass in the required content. In the above example, I create a simple list item with the Title field specified. Not rocket science of course, but at least it shows the principle.

Ah wait, I forgot one thing:

#r "Newtonsoft.Json"

using System;
using System.Net.Http;
using System.Net.Http.Headers;

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

public static async void Run(string myQueueItem, TraceWriter log)
{
    await CreateSharePointListItem("/sites/processes","Leave Requests", "Test item", log);
}

That’s the first lines of the function.

Conclusion

That’s all the bits and pieces you’ll need. Now it’s up to you to give a bit more meaning to your function. You could, for example, read an item from an Azure queue, translate it to the correct fields and then save it to SharePoint. My next post will reveal a bit more about what I’m going to do with this function. You might be interested in that one too (spoiler: it’s about bots!), so keep an eye open; coming soon!

#azure, #SharePoint, Function

Jasper Siegmund