Hello Everyone
In this article, I will share with you some information on what you can do with the Rest APIs of Azure DevOps Service on the work items of your projects in Azure DevOps.
First of all, if you ask, “why should I bother with APIs?", I can give you a few reasons for this. For example, let us have a field called 'Module' in the tasks of a product backlog item. Assume that we have to print the title information of pbi in this field, and that we need to do this for multiple pbis. This process requires us to perform recursive operations. In other words, we get that field information for each pbi and print it to the tasks. It can be very difficult to do this operation in Excel. Especially if there is a rule of the task, it may not be possible to do this, because you will probably encounter with errors while publishing the changes. But we only need 5 minutes to do this with APIs. After typing the necessary script, press the run button and continue to work on your other items while script performs your operations.
What can we do?
It is possible to perform many operations with these API services, such as creating a new work item, deleting an existing work item, updating the fields, listing your desired work items according to a specific query, and viewing information that you can from the frontend of Azure DevOps. How? Then continue reading.
First Step
In order to call APIs of Azure DevOps services, you need to generate a personnel access token at the project collection level of your project. For this, you can follow the following steps:
Click the Profile Settings button as shown below and click the Staff access tokens list.
When you are at the token screen, you have to generate a new token by clicking the New Token button.
For the organization, you must select the organization (project collection) information of the project of the work items you want to process.
Access tokens are specific to the organization where they are generated. API cannot be invoked for a project belonging to another organization with that token. Otherwise you will get a 401 Unauthorized error.
You can choose the token expire period as long as you want. The default value, which is 30 days, is left here.
Here, as the Scopes, you can grant full access authority for this token. Thus, you can perform all transactions with this token. For this article, I only enabled the work item privileges with Custom Define.
The token is generated by clicking the Create button. Now you can use this token information in header information when invoking APIs for work item operations.
Creating a work item
The API you will invoke is as follows:
PATCH
https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/${type}?api-version=5.1
Organization: Name of the organization of the project where your work items are located
Project: Name of the project where your work items are.
Type: ype of the work item we want to create. Have we written it, is it finished? No! Let us invoke this API now. I will perform my operations with PowerShell script. You can use any programming language you wish.
In the PowerShell script below, it creates a task type work item for the trial project.
$witType="task"$apiadress = "https://dev.azure.com/kadriyetaylann/deneme/_apis/wit/workitems/`$$($witType)?api-version=5.1"$personalAccessToken = "2ojzcqzxxmkn6hxrt7lhog3lgfgiqxjyi5u37tcn4334xi4ofi3a"$token = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes(":$($personalAccessToken)"))$headers = @{authorization = "Basic $token" }$body="[{`"op`": `"add`",`"path`": `"/fields/System.Title`",`"value`": `"InvokeAPIDeneme1`"}]"Invoke-RestMethod -Uri $apiadress -Method Patch -Body $body -ContentType "application/json-patch+json" -Headers $headers
Let us review our script now:
$witType: You need to assign as a variable the work item type name you want to create as a string to this parameter.
$apiadress: API you will invoke
$personalAccessToken: Access token you have received through Azure DevOps
$token: Encoded access token
$headers: Token information encoded for being authorized
$body: Body of the request to be used when assigning request – For the Operation here (add, remove, update), you need to give the field information and the value of the field.
op: Operation to be performed
path: A field information in the work item (Since this is a create operation, the title information of the work item was given)
value: value information for the field specified in the path parameter
Request is made to API in the last line.
When the above script is run on PowerShell, the output should be something similar to the output below.
Updating
Let us update the State information as Active for the task work item we created above. For this, the following API should be used.
PATCH
https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}?api-version=5.1
When you run the code below, Status information will be updated.
$apiadress = "https://dev.azure.com/kadriyetaylann/deneme/_apis/wit/workitems/6?api-version=5.1"$personalAccessToken ="kng3gqpbax6kpku7kc2h5zi532jwxfm75wfj3gdgwxuxkemplk3a"$token = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes(":$($personalAccessToken)"))$headers = @{authorization = "Basic $token" }$body="[{`"op`": `"replace`",`"path`": `"/fields/System.State`",`"value`": `"Active`"}]"Invoke-RestMethod -Uri $apiadress -Method Patch -Body $body -ContentType "application/json-patch+json" -Headers $headers
API address and body parameters have been modified in the above script.
When the above script is run in PowerShell, the output should be something similar to the output below.
Deleting
Let us delete the work item we created above.
For this, the following API should be used.
DELETE
https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}?api-version=5.1
When you run the code below, the task work item with an id no 6 will be deleted.
$apiadress = "https://dev.azure.com/kadriyetaylann/deneme/_apis/wit/workitems/6?api-version=5.1"$personalAccessToken ="kng3gqpbax6kpku7kc2h5zi532jwxfm75wfj3gdgwxuxkemplk3a"$token = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes(":$($personalAccessToken)"))$headers = @{authorization = "Basic $token" }Invoke-RestMethod -Uri $apiadress -Method Delete -ContentType "application/json-patch+json" -Headers $headers
When the above script is run in PowerShell, the output should be something similar to the output below.
You can also access the Scripts from the GitHub link below.
In this article, create, update and delete operations are performed. In my future articles, I will talk about how to run the queries that we have prepared in Azure DevOps Query Editor through APIs.
You can access the related article here :)
See you in my next article :)