check_jenkins_url
Checks the url provided to the API has a Jenkins server running on it. It returns the version number of
the Jenkins server if it is running.
$jenkins->check_jenkins_url;
# 1.460
current_status
Returns the current status of the server as returned by the API. This is a hash containing a fairly
comprehensive list of what's going on.
$jenkins->current_status();
# {
# 'assignedLabels' => [
# {}
# ],
# 'description' => undef,
# 'jobs' => [
# {
# 'color' => 'blue',
# 'name' => 'Jenkins-API',
# 'url' => 'http://jenkins:8080/job/Jenkins-API/'
# },
# 'mode' => 'NORMAL',
# 'nodeDescription' => 'the master Jenkins node',
# 'nodeName' => '',
# 'numExecutors' => 2,
# 'overallLoad' => {},
# 'primaryView' => {
# 'name' => 'All',
# 'url' => 'http://jenkins:8080/'
# },
# 'quietingDown' => bless( do{\(my $o = 0)}, 'JSON::XS::Boolean' ),
# 'slaveAgentPort' => 0,
# 'useCrumbs' => $VAR1->{'quietingDown'},
# 'useSecurity' => $VAR1->{'quietingDown'},
# 'views' => [
# {
# 'name' => 'All',
# 'url' => 'http://jenkins:8080/'
# }
# ]
# }
It is also possible to pass two parameters to the query to refine or expand the data you get back. The
tree parameter allows you to select specific elements. The example from the Jenkins documentation ,
"tree=> 'jobs[name],views[name,jobs[name]]'" demonstrates the syntax nicely.
The other parameter you can pass is depth, by default it's 0, if you set it higher it dumps a ton of
data.
$jenkins->current_status({ extra_params => { tree => 'jobs[name,color]' }});;
# {
# 'jobs' => [
# {
# 'color' => 'blue',
# 'name' => 'Jenkins-API',
# },
# ]
# }
$jenkins->current_status({ extra_params => { depth => 1 }});
# returns everything and the kitchen sink.
It is also possible to only look at a subset of the data. Most urls you can see on the website in
Jenkins can be accessed. If you have a job named Test-Project for example with the url
"/job/Test-Project" you can specify the "path_parts => ['job', 'Test-Project']" to look at the data for
that job alone.
$jenkins->current_status({
path_parts => [qw/job Test-Project/],
extra_params => { depth => 1 },
});
# just returns the data relating to job Test-Project.
# returning it in detail.
The method will die saying 'Invalid response' if the server doesn't respond as it expects, or die with a
JSON decoding error if the JSON parsing fails.
get_job_details
Returns detail about the job specified.
$job_details = $jenkins->get_job_details('Test-Project');
# {
# 'actions' => [],
# 'buildable' => bless( do{\(my $o = 0)}, 'JSON::PP::Boolean' ),
# 'builds' => [],
# 'color' => 'disabled',
# 'concurrentBuild' => $VAR1->{'buildable'},
# 'description' => '',
# 'displayName' => 'Test-Project',
# 'displayNameOrNull' => undef,
# 'downstreamProjects' => [],
# 'firstBuild' => undef,
# 'healthReport' => [],
# 'inQueue' => $VAR1->{'buildable'},
# 'keepDependencies' => $VAR1->{'buildable'},
# 'lastBuild' => undef,
# 'lastCompletedBuild' => undef,
# 'lastFailedBuild' => undef,
# 'lastStableBuild' => undef,
# 'lastSuccessfulBuild' => undef,
# 'lastUnstableBuild' => undef,
# 'lastUnsuccessfulBuild' => undef,
# 'name' => 'Test-Project',
# 'nextBuildNumber' => 1,
# 'property' => [],
# 'queueItem' => undef,
# 'scm' => {},
# 'upstreamProjects' => [],
# 'url' => 'http://jenkins-t2:8080/job/Test-Project/'
# }
The information can be refined in the same way as "current_status" using "extra_params".
view_status
Provides the status of the specified view. The list of views is provided in the general status report.
$jenkins->view_status('MyView');
# {
# 'busyExecutors' => {},
# 'queueLength' => {},
# 'totalExecutors' => {},
# 'totalQueueLength' => {}
# }
# {
# 'description' => undef,
# 'jobs' => [
# {
# 'color' => 'blue',
# 'name' => 'Test',
# 'url' => 'http://jenkins-t2:8080/job/Test/'
# }
# ],
# 'name' => 'Test',
# 'property' => [],
# 'url' => 'http://jenkins-t2:8080/view/Test/'
# }
This method allows the same sort of refinement as the "current_status" method. To just get the job info
from the view for example you can do essentially the same,
use Data::Dumper;
my $view_list = $api->current_status({ extra_params => { tree => 'views[name]' }});
my @views = grep { $_ ne 'All' } map { $_->{name} } @{$view_list->{views}};
for my $view (@views)
{
my $view_jobs = $api->view_status($view, { extra_params => { tree => 'jobs[name,color]' }});
print Dumper($view_jobs);
}
# {
# 'jobs' => [
# {
# 'color' => 'blue',
# 'name' => 'Test'
# }
# ]
# }
trigger_build
Trigger a build,
$success = $jenkins->trigger_build('Test-Project');
If you need to specify a token you can pass that like this,
$jenkins->trigger_build('Test-Project', { token => $token });
Note that the success response is simply to indicate that the build has been scheduled, not that the
build has succeeded.
trigger_build_with_parameters
Trigger a build with parameters,
$success = $jenkins->trigger_build_with_parameters('Test-Project', { Parameter => 'Value' } );
The method behaves the same way as trigger_build.
build_queue
This returns the items in the build queue.
$jenkins->build_queue();
This allows the same "extra_params" as the "current_status" call. The depth and tree parameters work in
the same way. See the Jenkins API documentation for more details.
The method will die saying 'Invalid response' if the server doesn't respond as it expects, or die with a
JSON decoding error if the JSON parsing fails.
load_statistics
This returns the load statistics for the server.
$jenkins->load_statistics();
# {
# 'busyExecutors' => {},
# 'queueLength' => {},
# 'totalExecutors' => {},
# 'totalQueueLength' => {}
# }
This also allows the same "extra_params" as the "current_status" call. The depth and tree parameters
work in the same way. See the Jenkins API documentation for more details.
The method will die saying 'Invalid response' if the server doesn't respond as it expects, or die with a
JSON decoding error if the JSON parsing fails.
create_job
Takes the project name and the XML for a config file and gets Jenkins to create the job.
my $success = $api->create_job($project_name, $config_xml);
project_config
This method returns the configuration for the project in XML.
my $config = $api->project_config($project_name);
set_project_config
This method allows you to set the configuration for the project using XML.
my $success = $api->set_project_config($project_name, $config);
delete_project
Delete the project from Jenkins.
my $success = $api->delete_project($project_name);
general_call
This is a catch all method for making a call to the API. Jenkins is extensible with plugins which can
add new API end points. We can not predict all of these so this method allows you to call those
functions without needing a specific method.
general_call($url_parts, $args);
my $response = $api->general_call(
['job', $job, 'api', 'json'],
{
method => 'GET',
extra_params => { tree => 'color,description' },
decode_json => 1,
expected_response_code => 200,
});
# does a GET /job/$job/api/json?tree=color%2Cdescription
# decodes the response as json
# dies if a 200 response isn't returned.
The arguments hash can contain these elements,
• method
Valid options are the HTTP verbs, make sure they are in caps.
• extra_params
Pass in extra parameters the method expects.
• decode_json
Defaulted to true.
• expected_response_code
Defaulted to 200
response_code
This method returns the HTTP response code from our last request to the Jenkins server. This may be
useful when an error occurred.
response_content
This method returns the content of the HTTP response from our last request to the Jenkins server. This
may be useful when an error occurs.
response_header
This method returns the specified header of the HTTP response from our last request to the Jenkins
server.
The following example triggers a parameterized build, extracts the 'Location' HTTP response header, and
selects certain elements of the queue item information
$success = $jenkins->trigger_build_with_parameters('Test-Project', { Parameter => 'Value' } );
if ($success) {
my $location = $jenkins->response_header('Location');
my $queue_item = $jenkins->general_call(
[ URI->new($location)->path_segments, 'api', 'json' ],
{
extra_params => { tree => 'url,why,executable[url]' }
}
);
# {
# 'executable' => {
# 'url' => 'http://jenkins:8080/job/Test-Project/136/',
# '_class' => 'org.jenkinsci.plugins.workflow.job.WorkflowRun'
# },
# 'url' => 'queue/item/555125/',
# 'why' => undef,
# '_class' => 'hudson.model.Queue$LeftItem'
# };
} else {
print $jenkins->response_code;
}
Install Now
PNG Icons