What is the resourceId parameter when trying to get virtual machines attached to an environment?

Question

I am currently trying to grab the tags associated with the with a specific VM in a given environment. The problem is, I can't figure out what the resourceId parameter stands for.

According to the documentation, I should be able to grab all the machines associated with the environment. Although for the life of me, I can't figure out what the resourceId stands for. The call would look something like this:

GET https://dev.azure.com/{organization}/{project}/_apis/distributedtask/environments/{environmentId}/providers/virtualmachinegroups/{resourceId}/virtualmachines?api-version=6.0-preview.1

All of the other parameters I can understand, but not resourceId. I would appreciate any help.

Answer 1

Since I can't simply comment, still wanted to share an additional couple endpoints that helped out greatly. @bright's answer is still right on the money, but in addition to the tags, I wanted to know the underlying agent's capabilities.

GET https://dev.azure.com/{organization}/_apis/distributedtask/pools/{poolId}/agents?api-version=7.1&includeCapabilities=true

/agents API Docs

Pool id can be found from "id" property returned from:

GET https://dev.azure.com/{organization}/{project}/_apis/pipelines/environments/{environmentId}/providers/virtualmachines/pool?api-version=7.2-preview.1

/pool API Docs

P.S. That /agents endpoint has a demands query property where you can pre-filter your list of agents with certain capabilities (i.e. demands=Agent.OS), although it doesn't seem to check against the value itself, just if the capability exists by name. It will also return a collection of capabilities with just the demands you specified, which will lighten the returned payload quite a bit in most cases, which is exactly what I wanted.

EDIT: Actually it is possible for the demands to be set to equal a certain value. Example: demands=Agent.OS -equals Windows_NT. Just make sure to URL encode that value. I stumbled upon this by looking at the code from Microsoft.TeamFoundation.DistributedTask.WebApi nuget package (see DemandEquals & DemandMinimumVersion).

Answer 2

The document "Virtualmachines - List" seems have some issues and need to be updated.

To list the Virtualmachines in an environment, you can try the following endpoint.

GET https://dev.azure.com/{organization}/{project}/_apis/pipelines/environments/{environmentId}/providers/virtualmachines?api-version=6.1-preview.1

I have tested this endpoint on my side, it can work fine.

[UPDATE]

The required scope should be "Environment (Read & manage)". I have tested the PAT that only contains this scope to execute the API, it can work fine and return the list of the Virtual machines in the specified environment. When creating a PAT, you also need to make sure the Organization scope has contained the organization which the API is running for.

And also make sure the PAT has not expired.

Answer 3

I also found out that you could query the following addresses, for the same result:

https://dev.azure.com/{organization}/{project}/_apis/pipelines/environments/{envid}?expands=resourceReferences

and

https://dev.azure.com/{organization}/{project}/_apis/distributedtask/environments/{envid}?expands=resourceReferences

This would result in the list of resources with their tags.

I am not completely sure if it the same thing as Bright's answer, since there is no reference to the type of the resource (virtual machine/kubernetes) in the call.