PowerShell and SharePoint: First Things First, Let's Just Connect to the Farm

 In the previous article I covered what this series was going to be about, an introduction if you will. If you missed it, head out over there and read it first so you can understand where the series is coming from and where it is going.

REST is a powerful tool. REST, combined with SharePoint, can be magical. It is the foundation of what we will be covering in this series. It will be this avenue, this platform that I will use along with PowerShell to help me be a good Site Collection Administrator.

Let's dig in!

Invoke-RestMethod is a PowerShell command that allows us to make a RESTful call to SharePoint. You can make a "GET" request, a "POST" request, a "MERGE" request and a few other types of requests that I wont mention here. At least not on this article.

Invoke-RestMethod -Method Get -Uri "<your sharepoint site>" -credential "<your creds>"

So let's take that command for a spin. Let's connect to SharePoint and see what we get. I have cracked opened my development environment that does not have SharePoint running, opened up VS Code, my editor of choice, and started getting giddy because... well because programming does that to me (Does it do it for you too?).

Clear-Host
$Response = Invoke-RestMethod -Method Get -uri "http://i.run.com/" -Credential "<my credentials>"

First of all I love "Clear-Host". That command simply clears my terminal window every time I run this code. Any errors that show up after running my code is a direct response of the code that I just ran. No doubt about it.

The second line is my REST call that does all the magic for me. I am using the GET method, passing my URI (yes, I enjoy running. Maybe too much), and my credentials which I have selected not to include. When that line sucessfully runs, two things happen:

  1. SharePoint will prompt me for my password. If you look closely at the Terminal window (never close your terminal window) you will see the request for your password and
  2. If I have entered my login and password correctly I have successfully connected to my SharePoint farm and the results of my call are held in the $Response variable.

There is so much to unpack from just that one line. I won't cover it all because there is just too much. For example, instead of hard coding your credentials in the -Credential parameter you could use Get-Credential to store you credentials. This way, you only get prompted once for your credentials. Once your credentials are stored in a variable you just use the variable in your REST call.

Clear-Host
$creds = Get-Credential
$Response = Invoke-RestMethod -Method Get -uri "http://i.run.com/" -Credential $creds

In the example above $creds holds the credentials we want to use to authenticate to SharePoint with. A few things you might want to consider: in the code above, you want to have a way to check if $creds has already been populated with your credentials, an IF Statement perhaps, otherwise, you will always get prompted for your credentials which defeats the purpose of using Get-Credential.

Another thing to note here is that I have hard coded the URL to my SharePoint Site. That limits my script to one Site. What if I have multiple sites I need to manage? To make my script more dynamic, more inclusive, more widely used, I should ask the end-user for the URL, populate that URL into a variable and use that variable in my Invoke-RestMethod.

Again, so many things to unpack here. I wont go through them all but I do want to get back on track. Go back to your terminal window to interact with the $Response variable. Let's check out what it holds.

$Response.getType()

This tells us what type of object we have. According to the results, I have an XML document. Why XML? Where is this coming from? The default content type being used by the REST call is "application/xml". You can change to return JSON and we will cover that in another article.

If you remember in our REST call we asked PowerShell to get the Site Collection and by default this brings back the home page. Let's dig deeper.

$Response.html

The results are formated in a table by PowerShell. You can think of this is a Key/Value pair. In our case we will be able to dig into the body. Let's see what I can get out of it:

$Response.html.body

Hmm... anybody else see what I see?

$Response.html.body.form

As you can see there is a lot of information inside the $Response varaible. I wont dig into all of it and technically, this is not specific to SharePoint. You can run the same REST call on any web site and get the similar results. You just have to dig for it. "How do you dig for it?" you may be asking.

$Response | Get-Member

Get-Member is a great command that shows me all the methods and properties that I can "dig" into to get information.

$Response.html | Get-Member
$Response.html.body | Get-Member
$Response.html.body.form | Get-Member

You get the idea.

I am already starting to feel a little better about my role as a Site Collection Administrator. Having access to the servers would make life easier but not having access does not prevent me from being a good SCA!

Comments

Post a Comment