This documentation relates to QuickBuild 11.0.x
Select here if you are using a different version

Interact with Builds

Version 1 by Robin Shen
on Feb 01, 2021 07:53.

 
compared with
Current by Robin Shen
on Feb 18, 2021 14:22.

 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 11 changes. View first change.

 h1. Access build by build id
  
 h2. Syntax
 Build can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>{code}
 The response is of mime type _application/xml_, and the content is XML representation of the build.
  
 h2. Security
 You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demostrates how to access XML representation of build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to access XML representation of build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14{code}
  
 h1. Access build status by build id
  
 h2. Syntax
 Build status can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/status{code}
 The response is of mime type _text/plain_, and the content is string representation of the build status.
  
 h2. Security
 You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build.
  
 h2. Demo
Below [curl|http://curl.haxx.se/] command demostrates how to access status of build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to access status of build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/status{code}
  
 h1. Access build begin date by build id
  
 h2. Syntax
 Build begin date can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/begin_date{code}
 The response is of mime type _text/plain_, and the content is string representation of build begin date (mill-seconds since January 1, 1970, 00:00:00 GMT)
  
 h2. Security
 You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build.
  
 h2. Demo
Below [curl|http://curl.haxx.se/] command demostrates how to access begin date of build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to access begin date of build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/begin_date{code}
  
 h1. Access build version by build id
  
 h2. Syntax
 Build version can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/version{code}
 The response is of mime type _text/plain_, and the content is string representation of the build version.
  
 h2. Security
 You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build.
  
 h2. Demo
Below [curl|http://curl.haxx.se/] command demostrates how to access version of build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to access version of build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/version{code}
  
 h1. Access build duration by build id
  
 h2. Syntax
 Build duration can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/duration{code}
 The response is of mime type _text/plain_, and the content is string representation of the build duration (milli-seconds). Status 204 (No Content) will be returned if build is not finished.
  
 h2. Security
 You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build.
  
 h2. Demo
Below [curl|http://curl.haxx.se/] command demostrates how to access duration of build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to access duration of build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/duration{code}
  
 {anchor:get request id}
 h1. Get build request id by build id
  
 h2. Syntax
 [Build request|Interact with Build Requests] id can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/request_id{code}
 The response is of mime type _text/plain_, and the content is string representation of the build request id. Status 204 (No Content) will be returned if build is finished.
  
 h2. Security
 You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have permission to access belonging configuration of requested build.
  
 h2. Demo
Below [curl|http://curl.haxx.se/] command demostrates how to get request id of build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to get request id of build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/request_id{code}
  
 h1. Access executed steps by build id
  
 h2. Syntax
 Executed steps of a build can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/steps{code}
 The response is of mime type _application/xml_, and the content is XML representation of the list of steps executed in the build.
  
 h2. Security
 You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have permission to access settings of belonging configuration.
  
 h2. Demo
Below [curl|http://curl.haxx.se/] command demostrates how to access executed steps by build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to access executed steps by build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/steps{code}
  
 h1. Access used repositories by build id
  
 h2. Syntax
 Used repositories of a build can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/repositories{code}
 The response is of mime type _application/xml_, and the content is XML representation of the list of repositories used in the build.
  
 h2. Security
 You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have permission to access settings of belonging configuration.
  
 h2. Demo
Below [curl|http://curl.haxx.se/] command demostrates how to access used repositories by build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to access used repositories by build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/repositories{code}
  
h1. Access used variables by build id
  
 h2. Syntax
 Used variables of a build can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/variables{code}
 The response is of mime type _application/xml_, and the content is XML representation of the list of variables used in the build.
  
 h2. Security
 You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have permission to access build variables.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to access used variables in build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/variables{code}
  
  
 h1. Access dependency builds by build id
  
 h2. Syntax
 All dependency builds whose artifacts are used by current build can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/dependencies{code}
 The response is of mime type _application/xml_, and the content is XML representation of the list of dependency builds of specified build.
  
 h2. Security
 You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have permission to access all dependency builds of specified build.
  
 h2. Demo
Below [curl|http://curl.haxx.se/] command demostrates how to access dependency builds of build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to access dependency builds of build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/dependencies{code}
  
 h1. Access dependent builds by build id
  
 h2. Syntax
 All dependent builds who using artifacts of current build can be accessed by build id using http GET method through below url:
 {code}http://localhost:8810/rest/builds/<build id>/dependents{code}
 The response is of mime type _application/xml_, and the content is XML representation of the list of dependent builds of specified build.
  
 h2. Security
 You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have permission to access all dependent builds of specified build.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demostrates how to access dependent builds of build with id _14_:
  Below [curl|http://curl.haxx.se/] command demonstrates how to access dependent builds of build with id _14_:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/14/dependents{code}
  
 h1. Search Builds
  
 h2. Syntax
 Builds can be searched using http GET method through below url:
 {code}http://localhost:8810/rest/builds?<search criteria1>=<value1>&<search criteria2>=<value2>&...{code}
 Query string part of the url represents various search criterias to restrict the search result. Supported search criterias are:
 ||Search criteria||Explanation||
 |configuration_id|This tells QuickBuild under which configuration id to search builds. If not specified, all configurations will be searched.|
 |recursive|If set to _true_, QuickBuild will also search builds in all descendent configurations of specified configuration. The value is assumed as _false_ if not specified.|
 |from_date|In the format of _yyyy-MM-dd_, for example: _2009-11-12_. If specified, search builds generated after this date|
 |to_date|In the format of _yyyy-MM-dd_, for example: _2009-11-12_. If specified, search builds generated before this date|
 |version|Specify the build version to match. The character _*_ can be used in the version string to do wildcard match. If not specified, all versions will be matched.|
 |status|Status of the build to match. Valid build statuses are: _SUCCESSFUL_, _FAILED_, _RECOMMENDED_, _CANCELLED_, _RUNNING_, _TIMEOUT_. If left empty, any build status will be matched.|
 |user_id|Match builds which is triggered by specified user. If not specified, builds triggered by any user will be matched.|
 |master_node|Match builds with master step running on specified node if specified.|
 |promoted_from_id|Match builds promoted from specified build id if specified.|
 |request_id|If specified, match builds with specified build request id|
 |first|Specify start position of search results. Position _0_ is assumed if this param is not specified.|
 |count|Specify number of builds to return. This parameter is required.|
  
 The response is of mime type _application/xml_, and the content is XML representation of list of matched builds.
  
 {warning}The parameter _count_ is required to limit the returned result set in order not to put heavy load on the server.{warning}
  
 h2. Security
 You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have permission to access returned builds.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] commands demonstrates how to combine different criterias to perform search:
 # Search all failed builds under configuration with id _2_:
 {code}curl -u admin:admin "http://localhost:8810/rest/builds?configuration_id=2&status=FAILED&count=100"{code}
 # Search all successful builds generated before _2009-11-12_ in the system:
 {code}curl -u admin:admin "http://localhost:8810/rest/builds?status=SUCCESSFUL&to_date=2009-11-12&count=100"{code}
 # Search all failed builds with version containing _qa_:
 {code}curl -u admin:admin "http://localhost:8810/rest/builds?version=*qa*&status=FAILED&count=100"{code}
  
 h1. Count Builds
  
 h2. Syntax
 Builds can be counted using http GET method through below url:
 {code}http://localhost:8810/rest/builds/count?<search criteria1>=<value1>&<search criteria2>=<value2>&...{code}
 Query string part of the url represents various search criterias to restrict the search result. Supported search criterias are:
 ||Search criteria||Explanation||
 |configuration_id|This tells QuickBuild under which configuration id to search builds. If not specified, all configurations will be searched.|
 |recursive|If set to _true_, QuickBuild will also search builds in all descendent configurations of specified configuration. The value is assumed as _false_ if not specified.|
 |from_date|In the format of _yyyy-MM-dd_, for example: _2009-11-12_. If specified, search builds generated after this date|
 |to_date|In the format of _yyyy-MM-dd_, for example: _2009-11-12_. If specified, search builds generated before this date|
 |version|Specify the build version to match. The character _*_ can be used in the version string to do wildcard match. If not specified, all versions will be matched.|
 |status|Status of the build to match. Valid build statuses are: _SUCCESSFUL_, _FAILED_, _RECOMMENDED_, _CANCELLED_, _RUNNING_, _TIMEOUT_. If left empty, any build status will be matched.|
 |user_id|Match builds which is triggered by specified user. If not specified, builds triggered by any user will be matched.|
 |promoted_from_id|If specified, match builds which is promoted from specified build|
 |request_id|If specified, match builds with specified build request id|
  
 The response is of mime type _text/plain_, and the content is string representation of number of builds matching search criterias. If no any search criterias are specified, all builds in the system will be counted.
  
 h2. Security
 Any user can call this RESTful API to count builds in system.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] commands demonstrates how to combine different criterias to perform build counting:
 # Count all failed builds under configuration with id _2_:
 {code}curl -u admin:admin "http://localhost:8810/rest/builds/count?configuration_id=2&status=FAILED"{code}
 # Count all successful builds generated before _2009-11-12_ in the system:
 {code}curl -u admin:admin "http://localhost:8810/rest/builds/count?status=SUCCESSFUL&to_date=2009-11-12"{code}
 # Count all failed builds with version containing _qa_:
 {code}curl -u admin:admin "http://localhost:8810/rest/builds/count?version=*qa*&status=FAILED"{code}
  
 h1. Update build
  
 h2. Syntax
 Build can be updated by posting XML representation of the build to below url:
 {code}http://localhost:8810/rest/builds{code}
 Please note that the _configuration_ element denotes id of the belonging configuration.
 Normally you do not need to create the XML from scratch: you may retrieve XML representation of the build using the http GET method, modify certain parts of the XML and post back to above url.
 The response is of mime type _text/plain_ and the content is string representation of the build id being updated.
  
 h2. Security
 You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have _SAVE_BUILD_ permission on the belonging configuration.
  
 h2. Demo
 We will use [curl|http://curl.haxx.se/] to demonstrate how to move the build to be under another configuration. Let's assume the build id is _100_, and the destination configuration id is _6_.
 # Retrieve xml representation of desired build into a temp file using below command:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/100 > tempfile.xml{code}
 # Edit _tempfile.xml_ and change the _configuration_ property to take the value _6_.
 # Post back modified content using below command:
 {code}curl -X POST -u admin:admin -d@tempfile.xml http://localhost:8810/rest/builds{code}
  
 {warning}Moving builds to other configurations is not suggested since it will result in inaccurate change sets when compare builds in the original configuration.{warning}
  
 h1. Create build
  
 h2. Syntax
 Build object can be created by posting XML representation of the build to below url:
 {code}http://localhost:8810/rest/builds{code}
 Please note that:
 # The posted xml should NOT contain the _id_ element; otherwise, QuickBuild will treat the post as an updating to the build with that id.
 # The _configuration_ element denotes id of the belonging configuration.
 Normally you do not need to create the XML from scratch: you may retrieve XML representation of a templating build using the http GET method, remove the _id_ element, modify certain parts and post back to above url.
 The response is of mime type _text/plain_ and the content is string representation of id of the newly created build.
  
 {note} This is different from [requesting new build|Interact with Build Requests#request new build] in the system. It simply adds a build object in the system, and is normally used to move build objects between different servers or configurations.{note}
  
 h2. Security
 You will need to use http BASIC authentication to login as administrator if the anonymous does not have administrative rights.
  
 h2. Demo
 We will use [curl|http://curl.haxx.se/] to demonstrate how to create a new build by copying an existing build with id _100_.
 # Retrieve xml representation of build with id _100_ into a temp file using below command:
 {code}curl -u admin:admin http://localhost:8810/rest/builds/100 > tempfile.xml{code}
 # Edit _tempfile.xml_ to remove the _id_ element, and change other properties as desired.
 # Post back modified content using below command:
 {code}curl -X POST -u admin:admin -d@tempfile.xml http://localhost:8810/rest/builds{code}
  
 h1. Delete Build
  
 h2. Syntax
 Build can be deleted using http DELETE method through below url:
 {code}http://localhost:8810/rest/builds/<build id>{code}
  
 {note}This service simply deletes the build object in database, and is different from build cacellation. You may follow below steps to cancel a running build:
 # [Get build request id|#get request id]
 # [Delete the build request|interact with build requests#delete build request] with build request id if it is not empty
 {note}
  
 h2. Security
 You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have _DELETE_BUILD_ permission on the belonging configuration.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to delete the build with id _100_:
 {code}curl -X DELETE -u admin:admin http://localhost:8810/rest/builds/100{code}