Call VS Team Services (VSTS) REST API from your Build Pipeline

Today I had the necessity to call the Visual Team Services (VSTS) REST API to get the code changes associated to the build I was currently running. I want these changes to get all the files and to do some actions with the files that were changed.

First I tried to call the REST API from Postman. In Postman you can call REST API’s quite easily and you can add authentication to the request. Because we have to access VSTS, which requires some authentication, we need to set this up. In order to access VSTS we first have to setup Alternate Credentials or a Personal Access Token.

To set up the security in Postman, select [Basic Authentication] on the Authorization Tab in Postman, and use the alternate username and password to access VSTS. If you use the Personal Access Token, just paste the token in the password field.

Then, I looked up the REST Call in the VSTS REST API Documentation and found the following call

https://{instance}/defaultcollection/{project}/_apis/build/builds/{buildid}/
changes?api-version={version}

After I tested the call in Postman, it was time to set up the build. In VSTS I created an empty definition and added the Powershell task to run some Inline Powershell.

But here is the tricky part. The Build can run on any agent, so it is not allowed to just call REST API’s of our VSTS account automatically. Because that would mean that anybody could just access anything. As an alternative you could add your credentials to the powershell call but there is a better way ! (brief description here on MSDN)

On the [Options] tab of your Build Definition there is a checkbox called [Allow Scripts to access OAuth Token]. This option creates a hidden variable call System.AccessToken, which you can add to the header of your REST Calls.

After we have set up this token (by checking the box), we can add Powershell to do a REST API call.

Invoke-RestMethod -Uri $url -Headers 
@{Authorization = "Bearer $env:SYSTEM_ACCESSTOKEN"

The addition of the header makes sure you can access the REST API without providing credentials.

The Powershell script to get my build changes no looks like this.

$url = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$env:SYSTEM_TEAMPROJECTID/
_apis/build/builds/$($env:BUILD_BUILDID)/changes?api-version=2.0"
Write-Host "URL: $url"
$definition = Invoke-RestMethod -Uri $url -Headers @{
 Authorization = "Bearer $env:SYSTEM_ACCESSTOKEN"
}
Write-Host "Definition = $($definition | ConvertTo-Json -Depth 1000)"

Hope this helps!