Deploymentgroups - Add

Service:

Task Agent

API Version:

5.0-preview.1

Create a deployment group.

POST https://dev.azure.com/{organization}/{project}/_apis/distributedtask/deploymentgroups?api-version=5.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 '5.0-preview.1' to use this version of the api.

Request Body

Name	Type	Description
description	string	Description of the deployment group.
name	string	Name of the deployment group.
poolId	integer (int32)	Identifier of the deployment pool in which deployment agents are registered.

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

Create a deployment group

Sample request

HTTP

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

{
  "name": "MyDeploymentGroup1",
  "description": "This deployment group is created to demnostrate the client usage"
}

Sample response

Status code:

200

{
  "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
  }
}

Definitions

Name	Description
Demand
DeploymentGroup	Deployment group.
DeploymentGroupCreateParameter	Properties to create Deployment group.
DeploymentMachine	Deployment target.
IdentityRef
JObject
JToken
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
TaskAgentAuthorization	Provides data necessary for authorizing the agent using OAuth 2.0 authentication flows.
TaskAgentCloudRequest
TaskAgentDelaySource
TaskAgentJobRequest
TaskAgentPoolReference
TaskAgentPoolType	Gets or sets the type of the pool
TaskAgentPublicKey	Represents the public key portion of an RSA asymmetric key.
TaskAgentReference
TaskAgentStatus	Gets the current connectivity status of the agent.
TaskAgentUpdate
TaskAgentUpdateReason
TaskAgentUpdateReasonType
TaskOrchestrationOwner
TaskResult

Demand

Object

Name	Type	Description
name	string
value	string

DeploymentGroup

Object

Deployment group.

Name	Type	Description
description	string	Description of the deployment group.
id	integer (int32)	Deployment group identifier.
machineCount	integer (int32)	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.

DeploymentGroupCreateParameter

Object

Properties to create Deployment group.

Name	Type	Description
description	string	Description of the deployment group.
name	string	Name of the deployment group.
poolId	integer (int32)	Identifier of the deployment pool in which deployment agents are registered.

DeploymentMachine

Object

Deployment target.

Name	Type	Description
agent	TaskAgent	Deployment agent.
id	integer (int32)	Deployment target Identifier.
tags	string[]	Tags of the deployment target.

IdentityRef

Object

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
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
inactive	boolean
isAadIdentity	boolean
isContainer	boolean
isDeletedInOrigin	boolean
profileUrl	string
uniqueName	string
url	string	This url is the full route to the source resource of this graph subject.

JObject

Object

Name	Type	Description
item	JToken
type	string (JTokenType)

JToken

Object

Name	Type	Description
first	JToken
hasValues	boolean
item	JToken
last	JToken
next	JToken
parent	string (JContainer)
path	string
previous	JToken
root	JToken
type	string (JTokenType)

PackageVersion

Object

Name	Type	Description
major	integer (int32)
minor	integer (int32)
patch	integer (int32)

ProjectReference

Object

Name	Type	Description
id	string (uuid)
name	string

PropertiesCollection

Object

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 (int32)	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

Object

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

Object

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
accessPoint	string	Gets the access point of the agent.
assignedAgentCloudRequest	TaskAgentCloudRequest	Gets the Agent Cloud Request that's currently associated with this agent
assignedRequest	TaskAgentJobRequest	Gets the request which is currently assigned to this agent.
authorization	TaskAgentAuthorization	Gets or sets the authorization information for this agent.
createdOn	string (date-time)	Gets the date on which this agent was created.
enabled	boolean	Gets or sets a value indicating whether or not this agent should be enabled for job execution.
id	integer (int32)	Gets the identifier of the agent.
lastCompletedRequest	TaskAgentJobRequest	Gets the last request which was completed by this agent.
maxParallelism	integer (int32)	Gets or sets the maximum job parallelism allowed on this host.
name	string	Gets the name of the agent.
oSDescription	string	Gets the OS of the agent.
pendingUpdate	TaskAgentUpdate	Gets the 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	Gets or sets the current provisioning state of this agent
status	TaskAgentStatus	Gets the current connectivity status of the agent.
statusChangedOn	string (date-time)	Gets the date on which the last connectivity status change occurred.
systemCapabilities	object
userCapabilities	object
version	string	Gets the version of the agent.

TaskAgentAuthorization

Object

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

Name	Type	Description
authorizationUrl	string	Gets or sets the endpoint used to obtain access tokens from the configured token service.
clientId	string (uuid)	Gets or sets the client identifier for this agent.
publicKey	TaskAgentPublicKey	Gets or sets the public key used to verify the identity of this agent.

TaskAgentCloudRequest

Object

Name	Type	Description
agent	TaskAgentReference
agentCloudId	integer (int32)
agentConnectedTime	string (date-time)
agentData	JObject
agentSpecification	JObject
pool	TaskAgentPoolReference
provisionRequestTime	string (date-time)
provisionedTime	string (date-time)
releaseRequestTime	string (date-time)
requestId	string (uuid)

TaskAgentDelaySource

Object

Name	Type	Description
delays	string[] (TimeSpan)
taskAgent	TaskAgentReference

TaskAgentJobRequest

Object

Name	Type	Description
agentDelays	TaskAgentDelaySource[]
agentSpecification	JObject
assignTime	string (date-time)
data	object
definition	TaskOrchestrationOwner
demands	Demand[]
expectedDuration	string (TimeSpan)
finishTime	string (date-time)
hostId	string (uuid)
jobId	string (uuid)
jobName	string
lockedUntil	string (date-time)
matchedAgents	TaskAgentReference[]
orchestrationId	string
owner	TaskOrchestrationOwner
planGroup	string
planId	string (uuid)
planType	string
poolId	integer (int32)
queueId	integer (int32)
queueTime	string (date-time)
receiveTime	string (date-time)
requestId	integer (int64)
reservedAgent	TaskAgentReference
result	TaskResult
scopeId	string (uuid)
serviceOwner	string (uuid)

TaskAgentPoolReference

Object

Name	Type	Description
id	integer (int32)
isHosted	boolean	Gets or sets a value indicating whether or not this pool is managed by the service.
name	string
poolType	TaskAgentPoolType	Gets or sets the type of the pool
scope	string (uuid)
size	integer (int32)	Gets the current size of the pool.

TaskAgentPoolType

Enumeration

Gets or sets the type of the pool

Value	Description
automation
deployment

TaskAgentPublicKey

Object

Represents the public key portion of an RSA asymmetric key.

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

TaskAgentReference

Object

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
accessPoint	string	Gets the access point of the agent.
enabled	boolean	Gets or sets a value indicating whether or not this agent should be enabled for job execution.
id	integer (int32)	Gets the identifier of the agent.
name	string	Gets the name of the agent.
oSDescription	string	Gets the OS of the agent.
provisioningState	string	Gets or sets the current provisioning state of this agent
status	TaskAgentStatus	Gets the current connectivity status of the agent.
version	string	Gets the version of the agent.

TaskAgentStatus

Enumeration

Gets the current connectivity status of the agent.

Value	Description
offline
online

TaskAgentUpdate

Object

Name	Type	Description
currentState	string	The current state of this agent update
reason	TaskAgentUpdateReason	The reason of this agent update
requestTime	string (date-time)	Gets the date on which this agent update was requested.
requestedBy	IdentityRef	The identity that request the agent update
sourceVersion	PackageVersion	Gets or sets the source agent version of the agent update
targetVersion	PackageVersion	Gets or sets the target agent version of the agent update

TaskAgentUpdateReason

Object

Name	Type	Description
code	TaskAgentUpdateReasonType

TaskAgentUpdateReasonType

Enumeration

Value	Description
manual
minAgentVersionRequired

TaskOrchestrationOwner

Object

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

TaskResult

Enumeration

Value	Description
abandoned
canceled
failed
skipped
succeeded
succeededWithIssues