1BZ::Client(3) User Contributed Perl Documentation BZ::Client(3)
2
6 BZ::Client - A client for the Bugzilla web services API.
7
9 version 4.4004
10
12 my $client = BZ::Client->new( url => $url,
13 user => $user,
14 password => $password,
15 autologin => 0 );
16 $client->login();
17
19 Please note that this BZ::Client module is aimed at the XMLRPC API
20 available in Bugzilla 5.0 and earlier.
21 For 5.1 and later, which have a totally different REST API, please see
23 Net::Bugzilla.
24 As such, I welcome all patches (via pull request) for functionality
26 relating to 5.0 and earlier.
27 I will only actively hunt down bugs relating to the 'maintained'
29 Bugzilla server softwares. Please upgrade your server and duplicate the
30 problem, or see the above commitment to accept patches to fix for older
31 versions.
32
34 This section lists the class methods of BZ::Client.
35 new
37 my $client = BZ::Client->new( url => $url,
38 user => $user,
39 password => $password );
40 my $client = BZ::Client->new( url => $url,
42 api_key => $api_key );
43 The new method constructs a new instance of BZ::Client. Whenever you
45 want to connect to the Bugzilla server, you must first create a
46 Bugzilla client. The methods input is a hash of parameters.
47 For debugging, you can pass in a subref named "logger" which will be
49 fed debugging information as the client works. Also the "logDirectory"
50 option is a directory where the raw http content will be dumped.
51 Parameters
53 url The Bugzilla servers URL, for example
55 "https://bugzilla.mozilla.org/".
56 api_key
58 API keys were introduced in 5.0.
59 An API Key can be obtained in the web interface of your Bugzilla
61 server, with the following steps:
62 1. Click 'Preferences' link
64 2. Click 'API Keys' tab
65 3. Click the checkbox next to 'Generate a new API key...'
66 4. If you like, add some description in the textbox
67 5. Click the 'Submit Changes' button
68 6. Key appears in the table under the 'Existing API keys'
69 subheading
70 user
71 The user name to use when logging in to the Bugzilla server.
72 Typically, this will be your email address.
73 password
75 The password to use when logging in to the Bugzilla server.
76 autologin
78 If set to 1 (true), will try to log in (if not already logged in)
79 when the first API call is made. This is default.
80 If set to 0, will try APi calls without logging in. You can still
82 call $client->login() to log in manually.
83 Note: once you're logged in, you'll stay that way until you call
85 "logout"
86 restrictlogin
88 If set to 1 (true), will ask Bugzilla to restrict logins to your IP
89 only. Generally this is a good idea, but may caused problems if
90 you are using a loadbalanced forward proxy.
91 Default: 0
93 connect
95 A hashref with options for HTTP::Tiny, this is passed through so
96 the bellow are for reference only:
97 http_proxy, https_proxy, proxy
99 Nominates a proxy for HTTP, HTTPS or both, respectively.
100 You might also use $ENV{all_proxy}, $ENV{http_proxy},
102 $ENV{https_proxy} or $ENV{all_proxy}.
103 timeout
105 Request timeout in seconds (default is 60)
106 verify_SSL
108 A boolean that indicates whether to validate the SSL
109 certificate of an "https" connection (default is false)
110 Connect Via Socks Proxy
112 Try something like:
114 use HTTP::Tiny; # load this manually
116 use IO::Socket::Socks::Wrapper (
117 'HTTP::Tiny::Handle::connect()' => {
118 ProxyAddr => 'localhost',
119 ProxyPort => 1080,
120 SocksVersion => 4,
121 Timeout => 15
122 }
123 );
124 use BZ::Client ...etc
125
127 This section lists the methods, which an instance of BZ::Client can
128 perform.
129 url
131 $url = $client->url();
132 $client->url( $url );
133 Returns or sets the Bugzilla servers URL.
135 user
137 $user = $client->user();
138 $client->user( $user );
139 Returns or sets the user name to use when logging in to the Bugzilla
141 server. Typically, this will be your email address.
142 password
144 $password = $client->password();
145 $client->password( $password );
146 Returns or sets the password to use when logging in to the Bugzilla
148 server.
149 autologin
151 If login is automatically called, or not.
152 login
154 Used to login to the Bugzilla server. By default, there is no need to
155 call this method explicitly: It is done automatically, whenever
156 required.
157 If autologin is set to 0, call this to log in.
159 is_logged_in
161 Returns 1 if logged in, otherwise 0.
162 logout
164 Deletes local cookies and calls Bugzilla's logout function
165 logger
167 Sets or gets the logging function. Argument is a coderef. Returns
168 "undef" if none.
169 $logger = $client->logger();
171 $client->logger(
173 sub {
174 my ($level, $msg) = @_;
175 print STDERR "$level $message\n";
176 return 1
177 });
178 Also can be set via "new", e.g.
180 $client = BZ::Client->new( logger => sub { },
182 url => $url
183 user => $user,
184 password => $password );
185 log
187 $client->log( $level, $message );
188 Sends log messages to whatever is loaded via "logger".
190 api_call
192 $response = $client->api_call( $methodName, $params, $options );
193 Used by subclasses of BZ::Client::API to invoke methods of the Bugzilla
195 API. The method name and the hash ref of parameters are sent to the
196 Bugzilla server. The options hash ref adjusts the behaviour of this
197 function when calls are made.
198 The params and options hash refs are optional, although certain param
200 values may be required depending on the method name being called. This
201 client library relies upon the Bugzilla server to enforce any method
202 parameter requirements, so insufficient requests will still be sent to
203 the server for it to then reject them.
204 Returns a hash ref of named result objects.
206 Options
208 empty_response_ok
210 With this set, an empty response is not considered an error. In
211 this case, api_call returns 1 to indicate success.
212 cookies
214 This is used internally to set cookies with the log in functions.
215 Don't touch this.
216
218 See BZ::Client::Exception
219
221 300 (Invalid Username or Password)
222 The username does not exist, or the password is wrong.
223 301 (Login Disabled)
225 The ability to login with this account has been disabled. A reason may
226 be specified with the error.
227 305 (New Password Required)
229 The current password is correct, but the user is asked to change his
230 password.
231 50 (Param Required)
233 A login or password parameter was not provided.
234
236 Bugzilla maintains demos of all supported versions and trunk at
237 <https://landfill.bugzilla.org>
238 You might consider using that for testing against live versions.
240
242 BZ::Client::Exception
243
245 • Dean Hamstead <dean@bytefoundry.com.au>
246 • Jochen Wiedmann <jochen.wiedmann@gmail.com>
248
250 This software is copyright (c) 2021 by Dean Hamstad.
251 This is free software; you can redistribute it and/or modify it under
253 the same terms as the Perl 5 programming language system itself.
254perl v5.36.0 2023-01-20 BZ::Client(3)