Azure REST API for running builds or pipelines

Question

I am trying to automate the creation of Azure Pipelines for a particular branch using their REST api.

However, I am struggling to use almost all their API's, as their documentation lacks examples.

Things like List and Get are simple enough.

However, when it comes to queuing a build: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/builds/queue?view=azure-devops-rest-6.0

POST https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=6.0
{
    "parameters": <parameters>, // how do i send paramters
    "definition": {
        "id": 1
    },
    "sourceBranch": "refs/heads/feature/my-pipeline",
    "sourceVersion": "d265f01aeb4e677a25725f44f20ceb3ff1d7d767"
}

I am currently struggling to send parameters. I have tried:

Simple JSON like:

"parameters": {
    "appId": "bab",
    "platform": "android",
    "isDemo": true
}

and stringify version of JSON like:

"parameters": "{\"appId\": \"bab\",\"platform\": \"android\",\"isDemo\": true}"

but none seems to work.

It keeps giving me the error:

{
    "$id": "1",
    "customProperties": {
        "ValidationResults": [
            {
                "result": "error",
                "message": "A value for the 'appId' parameter must be provided."
            },
            {
                "result": "error",
                "message": "A value for the 'platform' parameter must be provided."
            },
            {
                "result": "error",
                "message": "A value for the 'isDemo' parameter must be provided."
            }
        ]
    },
    "innerException": null,
    "message": "Could not queue the build because there were validation errors or warnings.",
    "typeName": "Microsoft.TeamFoundation.Build.WebApi.BuildRequestValidationFailedException, Microsoft.TeamFoundation.Build2.WebApi",
    "typeKey": "BuildRequestValidationFailedException",
    "errorCode": 0,
    "eventId": 3000
}

The docs is very unclear in how to send this data: https://learn.microsoft.com/en-us/rest/api/azure/devops/build/builds/queue?view=azure-devops-rest-6.1#propertiescollection

Thank you very much for you help.

In the documentation it says that it is a string, so i will try with something like this parameters: "appId=xxxxx platform=xxxx isDemo=xxxxx", this is how i send the varaibles of a build with the Azure Cli for powershell and in that documentation its like this a string. Try it!! — Nacho Martínez-Aedo, Aug 30 '20 at 09:57
Tried that just now: `appId=test platform=android isDemo=true`, but get error on that as well. — Yahya Uddin, Aug 30 '20 at 14:54

score 9 · Accepted Answer · edited Sep 17 '20 at 16:14

9

I believe you cannot pass runtime parameters trough the Queue API. Instead, use Runs API

With that, your request body (use Content-type: application/json) should look something similar to this:

{
    "resources": {
        "repositories": {
            "self": {
                "refName": "refs/heads/feature/my-pipeline"
            }
        }
    },
    "templateParameters": {
        "appId": "bab"
        "platform": "android"
        "isDemo": true
    }
}

edited Sep 17 '20 at 16:14

Carlochess

676
1
8
22

answered Aug 30 '20 at 11:06

LJ.

620
6
12

1

Thanks this worked. You a life saver! How did you know how to send the resources part. It's not documented like this. – Yahya Uddin Aug 30 '20 at 19:57
Glad I could help! You can see the documentation starting with [THIS](https://learn.microsoft.com/en-US/rest/api/azure/devops/pipelines/runs/run%20pipeline?view=azure-devops-rest-6.0#request-body) and following the hyperlinks under resources Type column. I see that only the `self` parameter is not documented there, it just indicates the current repository you are using. – LJ. Aug 30 '20 at 20:30
How did you know about the "self" part though. It just says `repositories`, with no information in what the keys are supposed to be. – Yahya Uddin Aug 30 '20 at 20:34
1

Also whats the difference between "Builds" and "Runs"? – Yahya Uddin Aug 31 '20 at 00:33
1

`self` parameter is partly documented [HERE](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/multi-repo-checkout?view=azure-devops). I think you should be able also to define it by including exact repository parameters (instead of just `self`) into the request body, but that seems to be unnecessary in this case, since you are using only one main repository. I figured it out by experimenting a while ago, didn't find it specifically documented back then, and also seems like currently there is no exact definition for this. – LJ. Aug 31 '20 at 12:50
2

About the difference (Builds vs Runs). Builds API allow you to access more specifically to each build and define it that way, while Runs (included in Pipelines API) in general is meant for actions that are one level "higher" in this case Pipeline itself. That's just my view from some experience I have of working with both of them. – LJ. Aug 31 '20 at 13:32

score 1 · Answer 2 · answered Feb 03 '21 at 14:29

I just realized that in the api-version=6.0 you can also send templateParameters on the Queue Service:

POST https://dev.azure.com/{organization}/{project}/_apis/build/builds?sourceBuildId={BUILD_BUILDID}&api-version=6.0
{
    "templateParameters": { "doReleaseBuild": "True" }, 
    "definition": {
        "id": 1
    },
    "sourceBranch": "refs/heads/feature/my-pipeline",
    "sourceVersion": "d265f01aeb4e677a25725f44f20ceb3ff1d7d767"
}

Azure REST API for running builds or pipelines

2 Answers2

Linked