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:

1. retrieve information from Jenkins for programmatic consumption.

2. trigger a new build

3. 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