Jenkins Python API
背景
对Jenkins服务器实现脚本化的管理, 例如 触发 Job 等。
Jenkins REST API
https://www.jenkins.io/doc/book/using/remote-access-api/
REST API
Many objects of Jenkins provide the remote access API. They are available at /.../api/ where "..." portion is the object for which you'd like to access.
- XML API
- Access data exposed in HTML as XML for machine consumption. Schema is also available.
You can also specify optional XPath to control the fragment you'd like to obtain (but see below). For example, ../api/xml?xpath=/*/*[0].
For XPath that matches multiple nodes, you need to also specify the "wrapper" query parameter to specify the name of the root XML element to be create so that the resulting XML becomes well-formed.
Similarly exclude query parameter can be used to exclude nodes that match the given XPath from the result. This is useful for trimming down the amount of data you fetch (but again see below). This query parameter can be specified multiple times.
XPath filtering is powerful, and you can have it only return a very small data, but note that the server still has to build a full DOM of the raw data, which could cause a large memory spike. To avoid overloading the server, consider using the tree parameter, or use the xpath parameter in conjunction with the tree parameter. When used together, the result of the tree parameter filtering is built into DOM, then the XPath is applied to compute the final return value. In this way, you can often substantially reduce the size of DOM built in memory.
- JSON API
- Access the same data as JSON for JavaScript-based access. tree may be used.
- Python API
Access the same data as Python for Python clients. This can be parsed into Python object as eval(urllib.urlopen("...").read()) and the resulting object tree is identical to that of JSON. However, when you do this, beware of the security implication. If you are connecting to a non-trusted Jenkins, the server can send you malicious Python programs.
In Python 2.6 or later you can safely parse this output using ast.literal_eval(urllib.urlopen("...").read())
For more information about remote API in Jenkins, see the documentation.
What can you do with it?
Remote API can be used to do things like these:
retrieve information from Jenkins for programmatic consumption.
trigger a new build
create/copy jobs
Submitting jobs
Jobs without parameters
You merely need to perform an HTTP POST on
JENKINS_URL/job/JOBNAME/build
.Jobs with parameters
Simple example - sending "String Parameters":
curl JENKINS_URL/job/JOB_NAME/buildWithParameters \ --user USER:TOKEN \ --data id=123 --data verbosity=high
Another example - sending a "File Parameter":
curl JENKINS_URL/job/JOB_NAME/buildWithParameters \ --user USER:PASSWORD \ --form FILE_LOCATION_AS_SET_IN_JENKINS=@PATH_TO_FILE
The symbol '@' is important in this example. Also, the path to the file is absolute path. In order to make this command work, you need to configure your Jenkins job to take a file parameter and match the File location field in the Jenkins job configuration with the key in the
--form
option.
Python API
Python API wrappers
JenkinsAPI, Python-Jenkins, api4jenkins, aiojenkins are object-oriented python wrappers for the Python REST API which aim to provide a more conventionally pythonic way of controlling a Jenkins server. It provides a higher-level API containing a number of convenience functions. Services offered currently include:
Query the test-results of a completed build
Get objects representing the latest builds of a job
Search for artifacts by simple criteria
Block until jobs are complete
Install artifacts to custom-specified directory structures
Authentication support for Jenkins instances
Ability to search for builds by subversion revision
Ability to add/remove/query Jenkins agents
python-jenkins
https://python-jenkins.readthedocs.io/en/latest/index.html
Python Jenkins is a python wrapper for the Jenkins REST API which aims to provide a more conventionally pythonic way of controlling a Jenkins server. It provides a higher-level API containing a number of convenience functions.
We like to use python-jenkins to automate our Jenkins servers. Here are some of the things you can use it for:
- Create new jobs
- Copy existing jobs
- Delete jobs
- Update jobs
- Get a job’s build information
- Get Jenkins master version information
- Get Jenkins plugin information
- Start a build on a job
- Create nodes
- Enable/Disable nodes
- Get information on nodes
- Create/delete/reconfig views
- Put server in shutdown mode (quiet down)
- List running builds
- Delete builds
- Wipeout job workspace
- Create/delete/update folders [1]
- Set the next build number [2]
- Install plugins
- and many more..
https://python-jenkins.readthedocs.io/en/latest/examples.html#example-3-working-with-jenkins-jobs
server.create_job('empty', jenkins.EMPTY_CONFIG_XML) jobs = server.get_jobs() print jobs my_job = server.get_job_config('cool-job') print(my_job) # prints XML configuration server.build_job('empty') server.disable_job('empty') server.copy_job('empty', 'empty_copy') server.enable_job('empty_copy') server.reconfig_job('empty_copy', jenkins.RECONFIG_XML) server.delete_job('empty') server.delete_job('empty_copy') # build a parameterized job # requires creating and configuring the api-test job to accept 'param1' & 'param2' server.build_job('api-test', {'param1': 'test value 1', 'param2': 'test value 2'}) last_build_number = server.get_job_info('api-test')['lastCompletedBuild']['number'] build_info = server.get_build_info('api-test', last_build_number) print build_info # get all jobs from the specific view jobs = server.get_jobs(view_name='View Name') print jobs