Deploymentgroups - List

Reference

Service:: Task Agent

API Version:: 6.0-preview.1

Get a list of deployment groups by name or IDs.

GET https://dev.azure.com/{organization}/{project}/_apis/distributedtask/deploymentgroups?api-version=6.0-preview.1

With optional parameters:

GET https://dev.azure.com/{organization}/{project}/_apis/distributedtask/deploymentgroups?name={name}&actionFilter={actionFilter}&$expand={$expand}&continuationToken={continuationToken}&$top={$top}&ids={ids}&api-version=6.0-preview.1

URI Parameters

Name	In	Required	Type	Description
organization	path	True	string	The name of the Azure DevOps organization.
project	path	True	string	Project ID or project name
api-version	query	True	string	Version of the API to use. This should be set to '6.0-preview.1' to use this version of the api.
$expand	query		DeploymentGroupExpands	Include these additional details in the returned objects.
$top	query		integer int32	Maximum number of deployment groups to return. Default is 1000.
actionFilter	query		DeploymentGroupActionFilter	Get only deployment groups on which this action can be performed.
continuationToken	query		string	Get deployment groups with names greater than this continuationToken lexicographically.
ids	query		string array (int32)	Comma separated list of IDs of the deployment groups.
name	query		string	Name of the deployment group.

Responses

Name	Type	Description
200 OK	DeploymentGroup[]	successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.machinegroup_manage	Provides ability to manage deployment group and agent pools

Examples

Get a deployment group by name

Get deployment groups by IDs

Get deployment groups in pages

List all deployment groups

Get a deployment group by name

Sample Request

HTTP

GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups?api-version=6.0-preview.1

Sample Response

Status code:: 200

{
  "count": 1,
  "value": [
    {
      "machineCount": 0,
      "description": "This deployment group is created to demnostrate the client usage",
      "id": 11,
      "project": {
        "id": "91879ed9-819b-46f3-9e0b-52ed4b20c04c",
        "name": "DeploymentGroupRESTSample"
      },
      "name": "MyDeploymentGroup1",
      "pool": {
        "id": 6,
        "scope": "86088ab1-30d8-4526-9663-3406752b8bc6",
        "name": "DeploymentGroupRESTSample-MyDeploymentGroup1",
        "isHosted": false,
        "poolType": "deployment",
        "size": 0
      }
    }
  ]
}

Get deployment groups by IDs

Sample Request

HTTP

GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups?api-version=6.0-preview.1

Sample Response

Status code:: 200

{
  "count": 2,
  "value": [
    {
      "machineCount": 0,
      "description": "This deployment group is created to demnostrate the client usage",
      "id": 12,
      "project": {
        "id": "91879ed9-819b-46f3-9e0b-52ed4b20c04c",
        "name": "DeploymentGroupRESTSample"
      },
      "name": "MyDeploymentGroup10",
      "pool": {
        "id": 7,
        "scope": "86088ab1-30d8-4526-9663-3406752b8bc6",
        "name": "DeploymentGroupRESTSample-MyDeploymentGroup10",
        "isHosted": false,
        "poolType": "deployment",
        "size": 0
      }
    },
    {
      "machineCount": 0,
      "description": "This deployment group is created to demnostrate the client usage",
      "id": 13,
      "project": {
        "id": "91879ed9-819b-46f3-9e0b-52ed4b20c04c",
        "name": "DeploymentGroupRESTSample"
      },
      "name": "MyDeploymentGroup11",
      "pool": {
        "id": 8,
        "scope": "86088ab1-30d8-4526-9663-3406752b8bc6",
        "name": "DeploymentGroupRESTSample-MyDeploymentGroup11",
        "isHosted": false,
        "poolType": "deployment",
        "size": 0
      }
    }
  ]
}

Get deployment groups in pages

Sample Request

HTTP

GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups?api-version=6.0-preview.1

Sample Response

Status code:: 200

x-MS-ContinuationToken: MyDeploymentGroup14

Response Body

{
  "count": 2,
  "value": [
    {
      "machineCount": 0,
      "description": "This deployment group is created to demnostrate the client usage",
      "id": 14,
      "project": {
        "id": "91879ed9-819b-46f3-9e0b-52ed4b20c04c",
        "name": "DeploymentGroupRESTSample"
      },
      "name": "MyDeploymentGroup12",
      "pool": {
        "id": 9,
        "scope": "86088ab1-30d8-4526-9663-3406752b8bc6",
        "name": "DeploymentGroupRESTSample-MyDeploymentGroup12",
        "isHosted": false,
        "poolType": "deployment",
        "size": 0
      }
    },
    {
      "machineCount": 0,
      "description": "This deployment group is created to demnostrate the client usage",
      "id": 15,
      "project": {
        "id": "91879ed9-819b-46f3-9e0b-52ed4b20c04c",
        "name": "DeploymentGroupRESTSample"
      },
      "name": "MyDeploymentGroup13",
      "pool": {
        "id": 10,
        "scope": "86088ab1-30d8-4526-9663-3406752b8bc6",
        "name": "DeploymentGroupRESTSample-MyDeploymentGroup13",
        "isHosted": false,
        "poolType": "deployment",
        "size": 0
      }
    }
  ]
}

List all deployment groups

Sample Request

HTTP

GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups?api-version=6.0-preview.1

Sample Response

Status code:: 200

{
  "count": 3,
  "value": [
    {
      "machineCount": 0,
      "description": "This deployment group is created to demnostrate the client usage",
      "id": 11,
      "project": {
        "id": "91879ed9-819b-46f3-9e0b-52ed4b20c04c",
        "name": "DeploymentGroupRESTSample"
      },
      "name": "MyDeploymentGroup1",
      "pool": {
        "id": 6,
        "scope": "86088ab1-30d8-4526-9663-3406752b8bc6",
        "name": "DeploymentGroupRESTSample-MyDeploymentGroup1",
        "isHosted": false,
        "poolType": "deployment",
        "size": 0
      }
    },
    {
      "machineCount": 0,
      "description": "This deployment group is created to demnostrate the client usage",
      "id": 12,
      "project": {
        "id": "91879ed9-819b-46f3-9e0b-52ed4b20c04c",
        "name": "DeploymentGroupRESTSample"
      },
      "name": "MyDeploymentGroup10",
      "pool": {
        "id": 7,
        "scope": "86088ab1-30d8-4526-9663-3406752b8bc6",
        "name": "DeploymentGroupRESTSample-MyDeploymentGroup10",
        "isHosted": false,
        "poolType": "deployment",
        "size": 0
      }
    },
    {
      "machineCount": 0,
      "description": "This deployment group is created to demnostrate the client usage",
      "id": 13,
      "project": {
        "id": "91879ed9-819b-46f3-9e0b-52ed4b20c04c",
        "name": "DeploymentGroupRESTSample"
      },
      "name": "MyDeploymentGroup11",
      "pool": {
        "id": 8,
        "scope": "86088ab1-30d8-4526-9663-3406752b8bc6",
        "name": "DeploymentGroupRESTSample-MyDeploymentGroup11",
        "isHosted": false,
        "poolType": "deployment",
        "size": 0
      }
    }
  ]
}

Definitions

Name	Description
Demand
DeploymentGroup	Deployment group.
DeploymentGroupActionFilter	Get only deployment groups on which this action can be performed.
DeploymentGroupExpands	Include these additional details in the returned objects.
DeploymentMachine	Deployment target.
IdentityRef
JObject	Represents a JSON object.
JToken	Represents an abstract JSON token.
PackageVersion
ProjectReference
PropertiesCollection	The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a `TypeCode != TypeCode.Object`) except for `DBNull` are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.
ReferenceLinks	The class to represent a collection of REST reference links.
TaskAgent	A task agent.
TaskAgentAuthorization	Provides data necessary for authorizing the agent using OAuth 2.0 authentication flows.
TaskAgentCloudRequest
TaskAgentDelaySource
TaskAgentJobRequest	A job request for an agent.
TaskAgentPoolOptions	Additional pool settings and details
TaskAgentPoolReference
TaskAgentPoolType	Gets or sets the type of the pool
TaskAgentPublicKey	Represents the public key portion of an RSA asymmetric key.
TaskAgentReference	A reference to an agent.
TaskAgentStatus	Whether or not the agent is online.
TaskAgentUpdate	Details about an agent update.
TaskAgentUpdateReason
TaskAgentUpdateReasonType
TaskOrchestrationOwner
TaskResult	The result of this request.

Demand

Name	Type	Description
name	string
value	string

DeploymentGroup

Deployment group.

Name	Type	Description
description	string	Description of the deployment group.
id	integer	Deployment group identifier.
machineCount	integer	Number of deployment targets in the deployment group.
machineTags	string[]	List of unique tags across all deployment targets in the deployment group.
machines	DeploymentMachine[]	List of deployment targets in the deployment group.
name	string	Name of the deployment group.
pool	TaskAgentPoolReference	Deployment pool in which deployment agents are registered.
project	ProjectReference	Project to which the deployment group belongs.

DeploymentGroupActionFilter

Get only deployment groups on which this action can be performed.

Name	Type	Description
manage	string	Only deployment groups for which caller has manage permission.
none	string	All deployment groups.
use	string	Only deployment groups for which caller has use permission.

DeploymentGroupExpands

Include these additional details in the returned objects.

Name	Type	Description
machines	string	Deprecated: Include all the deployment targets.
none	string	No additional properties.
tags	string	Include unique list of tags across all deployment targets.

DeploymentMachine

Deployment target.

Name	Type	Description
agent	TaskAgent	Deployment agent.
id	integer	Deployment target Identifier.
properties	PropertiesCollection	Properties of the deployment target.
tags	string[]	Tags of the deployment target.

IdentityRef

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias	string	Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
id	string
imageUrl	string	Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary
inactive	boolean	Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary
isAadIdentity	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)
isContainer	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType)
isDeletedInOrigin	boolean
profileUrl	string	Deprecated - not in use in most preexisting implementations of ToIdentityRef
uniqueName	string	Deprecated - use Domain+PrincipalName instead
url	string	This url is the full route to the source resource of this graph subject.

JObject

Represents a JSON object.

Name	Type	Description
item	JToken	Represents an abstract JSON token.
type	string	Gets the node type for this JToken.

JToken

Represents an abstract JSON token.

Name	Type	Description
first	JToken	Get the first child token of this token.
hasValues	boolean	Gets a value indicating whether this token has child tokens.
item	JToken	Represents an abstract JSON token.
last	JToken	Get the last child token of this token.
next	JToken	Gets the next sibling token of this node.
parent	string	Gets or sets the parent.
path	string	Gets the path of the JSON token.
previous	JToken	Gets the previous sibling token of this node.
root	JToken	Gets the root JToken of this JToken.
type	string	Gets the node type for this JToken.

PackageVersion

Name	Type	Description
major	integer
minor	integer
patch	integer

ProjectReference

Name	Type	Description
id	string
name	string

PropertiesCollection

The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object) except for DBNull are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.

Name	Type	Description
count	integer	The count of properties in the collection.
item	object
keys	string[]	The set of keys in the collection.
values	string[]	The set of values in the collection.

ReferenceLinks

The class to represent a collection of REST reference links.

Name	Type	Description
links	object	The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

TaskAgent

A task agent.

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
accessPoint	string	This agent's access point.
assignedAgentCloudRequest	TaskAgentCloudRequest	The agent cloud request that's currently associated with this agent.
assignedRequest	TaskAgentJobRequest	The request which is currently assigned to this agent.
authorization	TaskAgentAuthorization	Authorization information for this agent.
createdOn	string	Date on which this agent was created.
enabled	boolean	Whether or not this agent should run jobs.
id	integer	Identifier of the agent.
lastCompletedRequest	TaskAgentJobRequest	The last request which was completed by this agent.
maxParallelism	integer	Maximum job parallelism allowed for this agent.
name	string	Name of the agent.
osDescription	string	Agent OS.
pendingUpdate	TaskAgentUpdate	Pending update for this agent.
properties	PropertiesCollection	The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a `TypeCode != TypeCode.Object`) except for `DBNull` are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.
provisioningState	string	Provisioning state of this agent.
status	TaskAgentStatus	Whether or not the agent is online.
statusChangedOn	string	Date on which the last connectivity status change occurred.
systemCapabilities	object
userCapabilities	object
version	string	Agent version.

TaskAgentAuthorization

Provides data necessary for authorizing the agent using OAuth 2.0 authentication flows.

Name	Type	Description
authorizationUrl	string	Endpoint used to obtain access tokens from the configured token service.
clientId	string	Client identifier for this agent.
publicKey	TaskAgentPublicKey	Public key used to verify the identity of this agent.

TaskAgentCloudRequest

Name	Type	Description
agent	TaskAgentReference	A reference to an agent.
agentCloudId	integer
agentConnectedTime	string
agentData	JObject	Represents a JSON object.
agentSpecification	JObject	Represents a JSON object.
pool	TaskAgentPoolReference
provisionRequestTime	string
provisionedTime	string
releaseRequestTime	string
requestId	string

TaskAgentDelaySource

Name	Type	Description
delays	string[]
taskAgent	TaskAgentReference	A reference to an agent.

TaskAgentJobRequest

A job request for an agent.

Name	Type	Description
agentDelays	TaskAgentDelaySource[]
agentSpecification	JObject	Represents a JSON object.
assignTime	string	The date/time this request was assigned.
data	object	Additional data about the request.
definition	TaskOrchestrationOwner	The pipeline definition associated with this request
demands	Demand[]	A list of demands required to fulfill this request.
expectedDuration	string
finishTime	string	The date/time this request was finished.
hostId	string	The host which triggered this request.
jobId	string	ID of the job resulting from this request.
jobName	string	Name of the job resulting from this request.
lockedUntil	string	The deadline for the agent to renew the lock.
matchedAgents	TaskAgentReference[]	A reference to an agent.
matchesAllAgentsInPool	boolean
orchestrationId	string
owner	TaskOrchestrationOwner	The pipeline associated with this request
planGroup	string
planId	string	Internal ID for the orchestration plan connected with this request.
planType	string	Internal detail representing the type of orchestration plan.
poolId	integer	The ID of the pool this request targets
queueId	integer	The ID of the queue this request targets
queueTime	string	The date/time this request was queued.
receiveTime	string	The date/time this request was receieved by an agent.
requestId	integer	ID of the request.
reservedAgent	TaskAgentReference	The agent allocated for this request.
result	TaskResult	The result of this request.
scopeId	string	Scope of the pipeline; matches the project ID.
serviceOwner	string	The service which owns this request.
statusMessage	string
userDelayed	boolean

TaskAgentPoolOptions

Additional pool settings and details

Name	Type	Description
elasticPool	string	TaskAgentPool backed by the Elastic pool service
none	string
preserveAgentOnJobFailure	string	Set to true if agents are held for investigation after a TaskAgentJobRequest failure
singleUseAgents	string	Set to true if agents are re-imaged after each TaskAgentJobRequest

TaskAgentPoolReference

Name	Type	Description
id	integer
isHosted	boolean	Gets or sets a value indicating whether or not this pool is managed by the service.
isLegacy	boolean	Determines whether the pool is legacy.
name	string
options	TaskAgentPoolOptions	Additional pool settings and details
poolType	TaskAgentPoolType	Gets or sets the type of the pool
scope	string
size	integer	Gets the current size of the pool.

TaskAgentPoolType

Gets or sets the type of the pool

Name	Type	Description
automation	string	A typical pool of task agents
deployment	string	A deployment pool

TaskAgentPublicKey

Represents the public key portion of an RSA asymmetric key.

Name	Type	Description
exponent	string[]	Gets or sets the exponent for the public key.
modulus	string[]	Gets or sets the modulus for the public key.

TaskAgentReference

A reference to an agent.

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
accessPoint	string	This agent's access point.
enabled	boolean	Whether or not this agent should run jobs.
id	integer	Identifier of the agent.
name	string	Name of the agent.
osDescription	string	Agent OS.
provisioningState	string	Provisioning state of this agent.
status	TaskAgentStatus	Whether or not the agent is online.
version	string	Agent version.

TaskAgentStatus

Whether or not the agent is online.

Name	Type	Description
offline	string
online	string

TaskAgentUpdate

Details about an agent update.

Name	Type	Description
currentState	string	Current state of this agent update.
reason	TaskAgentUpdateReason	Reason for this update.
requestTime	string	Date on which this update was requested.
requestedBy	IdentityRef	Identity which requested this update.
sourceVersion	PackageVersion	Source agent version of the update.
targetVersion	PackageVersion	Target agent version of the update.

TaskAgentUpdateReason

Name	Type	Description
code	TaskAgentUpdateReasonType

TaskAgentUpdateReasonType

Name	Type	Description
downgrade	string
manual	string
minAgentVersionRequired	string

TaskOrchestrationOwner

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
id	integer
name	string

TaskResult

The result of this request.

Name	Type	Description
abandoned	string
canceled	string
failed	string
skipped	string
succeeded	string
succeededWithIssues	string

Deploymentgroups - List

URI Parameters

Responses

Security

oauth2

Scopes

Examples

Get a deployment group by name

Sample Request

Sample Response

Get deployment groups by IDs

Sample Request

Sample Response

Get deployment groups in pages

Sample Request

Sample Response

List all deployment groups

Sample Request

Sample Response

Definitions

Demand

DeploymentGroup

DeploymentGroupActionFilter

DeploymentGroupExpands

DeploymentMachine

IdentityRef

JObject

JToken

PackageVersion

ProjectReference

PropertiesCollection

ReferenceLinks

TaskAgent

TaskAgentAuthorization

TaskAgentCloudRequest

TaskAgentDelaySource

TaskAgentJobRequest

TaskAgentPoolOptions

TaskAgentPoolReference

TaskAgentPoolType

TaskAgentPublicKey

TaskAgentReference

TaskAgentStatus

TaskAgentUpdate

TaskAgentUpdateReason

TaskAgentUpdateReasonType

TaskOrchestrationOwner

TaskResult

Feedback

Additional resources