Class: JSS::APIConnection

Inherits:
Object
  • Object
show all
Includes:
Singleton
Defined in:
lib/jss-api/api_connection.rb,
lib/jss-api.rb

Overview

An API connection to the JSS.

This is a singleton class, only one can exist at a time. Its one instance is created automatically when the module loads, but it isn’t connected to anything at that time.

Use it via the API constant to call the #connect method, and the #get_rsrc, #put_rsrc, #post_rsrc, & #delete_rsrc methods, q.v. below.

To access the underlying RestClient::Resource instance, use JSS::API.cnx

Constant Summary collapse

RSRC =

The base API path in the jss URL

"JSSResource"
HTTP_PORT =

The Default port

9006
SSL_PORT =

The SSL port

8443
XML_HEADER =

The top line of an XML doc for submitting data via API

'<?xml version="1.0" encoding="UTF-8" standalone="no"?>'
DFT_OPEN_TIMEOUT =

Default timeouts in seconds

60
DFT_TIMEOUT = 
60

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ APIConnection

To connect, use JSS::APIConnection.instance.connect or a shortcut, JSS::API.connect



105
106
107
 
# File 'lib/jss-api/api_connection.rb', line 105

def initialize ()
  @connected = false
end

Instance Attribute Details

#cnx ⇒ RestClient::Resource (readonly)

Returns the underlying connection resource.

Returns:

  • (RestClient::Resource) —

    the underlying connection resource



89
90
91
 
# File 'lib/jss-api/api_connection.rb', line 89

def cnx
  @cnx
end

#connected ⇒ Boolean (readonly) Also known as: connected?

Returns are we connected right now?.

Returns:

  • (Boolean) —

    are we connected right now?



92
93
94
 
# File 'lib/jss-api/api_connection.rb', line 92

def connected
  @connected
end

#jss_user ⇒ String (readonly)

Returns the username who’s connected to the JSS API.

Returns:

  • (String) —

    the username who’s connected to the JSS API



86
87
88
 
# File 'lib/jss-api/api_connection.rb', line 86

def jss_user
  @jss_user
end

#server ⇒ JSS::Server (readonly)

Returns the details of the JSS to which we’re connected.

Returns:

  • (JSS::Server) —

    the details of the JSS to which we’re connected.



95
96
97
 
# File 'lib/jss-api/api_connection.rb', line 95

def server
  @server
end

Instance Method Details

#connect(args = {}) ⇒ true

Connect to the JSS API.

Parameters:

  • args (Hash) (defaults to: {}) —

    the keyed arguments for connection.

Options Hash (args):

  • :server (String) —

    Required, the hostname of the JSS API server

  • :port (Integer) —

    the port number to connect with, defaults to 8443

  • :verify_cert (Boolean) —

    should HTTPS SSL certificates be verified. Defaults to true. If your connection raises RestClient::SSLCertificateNotVerified, and you don’t care about the validity of the SSL cert. just set this explicitly to false.

  • :user (String) —

    Required, a JSS user who as API privs

  • :pw (String, Symbol) —

    Required, the password for that user, or :prompt, or :stdin If :prompt, the user is promted on the commandline to enter the password for the :user. If :stdin#, the password is read from a line of std in represented by the digit at #, so :stdin3 reads the passwd from the third line of standard input. defaults to line 1, if no digit is supplied. see JSS.stdin

  • :open_timeout (Integer) —

    the number of seconds to wait for an initial response, defaults to 60

  • :timeout (Integer) —

    the number of seconds before an API call times out, defaults to 60

Returns:

  • (true)

Raises:



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/jss-api/api_connection.rb', line 140

def connect (args = {})

  # settings from config if they aren't in the args
  args[:server] ||= JSS::CONFIG.api_server_name
  args[:port] ||= JSS::CONFIG.api_server_port
  args[:user] ||= JSS::CONFIG.api_username
  args[:timeout] ||= JSS::CONFIG.api_timeout
  args[:open_timeout] ||= JSS::CONFIG.api_timeout_open

  # if verify cert given was NOT in the args....
  if args[:verify_cert].nil?
    # set it from the prefs
    args[:verify_cert] = JSS::CONFIG.api_verify_cert
  end

  # default settings if needed
  args[:port] ||= SSL_PORT
  args[:timeout] ||= DFT_TIMEOUT
  args[:open_timeout] ||= DFT_OPEN_TIMEOUT

  # must have server, user, and pw
  raise JSS::MissingDataError, "Missing :server" unless args[:server]
  raise JSS::MissingDataError, "Missing :user" unless args[:user]
  raise JSS::MissingDataError, "Missing :pw for user '#{args[:user]}'" unless args[:pw]

  ssl = SSL_PORT == args[:port].to_i ? "s" : ''
  @rest_url = URI::encode "http#{ssl}://#{args[:server]}:#{args[:port]}/#{RSRC}"

  # prep the args for passing to RestClient::Resource
  # if verify_cert is nil (unset) or non-false, then we will verify
  args[:verify_ssl] =  (args[:verify_cert].nil? or args[:verify_cert]) ? OpenSSL::SSL::VERIFY_PEER :  OpenSSL::SSL::VERIFY_NONE
  
  # make sure we have a user
  raise JSS::MissingDataError, "No JSS user specified, or listed in configuration." unless args[:user]
  
  args[:password] = if args[:pw] == :prompt
    JSS.prompt_for_password "Enter the password for JSS user '#{args[:user]}':"
  elsif args[:pw].is_a?(Symbol) and args[:pw].to_s.start_with?('stdin')
    args[:pw].to_s =~ /^stdin(\d+)$/
    line = $1
    line ||= 1
    JSS.stdin line
  else
    args[:pw]
  end
  
  # heres our connection
  @cnx = RestClient::Resource.new("#{@rest_url}", args)

  @jss_user = args[:user]
  @connected = true
  @server = JSS::Server.new

  if @server.version < JSS.parse_jss_version(JSS::MINIMUM_SERVER_VERSION)[:version]
    raise JSS::UnsupportedError, "Your JSS Server version, #{@server.raw_version}, is to low. Must be #{JSS::MINIMUM_SERVER_VERSION} or higher."
  end

  return true
end

#delete_rsrc(rsrc) ⇒ String

Delete a resource from the JSS

Parameters:

  • rsrc (String) —

    the resource to create, the URL part after ‘JSSResource/’

Returns:

  • (String) —

    the xml response from the server.

Raises:



307
308
309
310
311
312
313
314
 
# File 'lib/jss-api/api_connection.rb', line 307

def delete_rsrc(rsrc)
  raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
  raise MissingDataError, "Missing :rsrc" if rsrc.nil?

  ### delete the resource
  @cnx[rsrc].delete

end

#disconnect ⇒ void

This method returns an undefined value.

With a REST connection, there isn’t any real “connection” to disconnect from So to disconnect, we just unset all our credentials.



229
230
231
232
233
234
 
# File 'lib/jss-api/api_connection.rb', line 229

def disconnect
  @jss_user = nil
  @rest_url = nil
  @cnx = nil
  @connected = false
end

#get_rsrc(rsrc, format = :json) ⇒ Hash, String

Get an arbitrary JSS resource

The first argument is the resource to get (the part of the API url after the ‘JSSResource/’ )

By default we get the data in JSON, and parse it into a ruby data structure (arrays, hashes, strings, etc) with symbolized Hash keys.

Parameters:

  • rsrc (String) —

    the resource to get (the part of the API url after the ‘JSSResource/’ )

  • format (Symbol) (defaults to: :json) —

    either ;json or :xml If the second argument is :xml, the XML data is returned as a String.

Returns:

Raises:



254
255
256
257
258
259
260
 
# File 'lib/jss-api/api_connection.rb', line 254

def get_rsrc (rsrc, format = :json)
  raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
  rsrc = URI::encode rsrc
  data = @cnx[rsrc].get(:accept => format)
  return JSON.parse(data, :symbolize_names => true) if format == :json
  data
end

#open_timeout=(timeout) ⇒ void

This method returns an undefined value.

Reset the open-connection timeout for the rest connection

Parameters:

  • timeout (Integer) —

    the new timeout in seconds



218
219
220
 
# File 'lib/jss-api/api_connection.rb', line 218

def open_timeout= (timeout)
  @cnx.options[:open_timeout] = timeout
end

#post_rsrc(rsrc, xml) ⇒ String

Create a new JSS resource

Parameters:

  • rsrc (String) —

    the API resource being created, the URL part after ‘JSSResource/’

  • xml (String) —

    the xml specifying the new object.

Returns:

  • (String) —

    the xml response from the server.

Raises:



290
291
292
293
294
295
296
297
298
 
# File 'lib/jss-api/api_connection.rb', line 290

def post_rsrc(rsrc,xml)
  raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected

  ### convert CRs & to &#13;
  xml.gsub!(/\r/, '&#13;')

  ### send the data
  @cnx[rsrc].post xml, :content_type => 'text/xml', :accept => :json
end

#put_rsrc(rsrc, xml) ⇒ String

Change an existing JSS resource

Parameters:

  • rsrc (String) —

    the API resource being changed, the URL part after ‘JSSResource/’

  • xml (String) —

    the xml specifying the changes.

Returns:

  • (String) —

    the xml response from the server.

Raises:



271
272
273
274
275
276
277
278
279
 
# File 'lib/jss-api/api_connection.rb', line 271

def put_rsrc(rsrc,xml)
  raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected

  ### convert CRs & to &#13;
  xml.gsub!(/\r/, '&#13;')

  ### send the data
  @cnx[rsrc].put(xml, :content_type => 'text/xml')
end

#timeout=(timeout) ⇒ void

This method returns an undefined value.

Reset the response timeout for the rest connection

Parameters:

  • timeout (Integer) —

    the new timeout in seconds



207
208
209
 
# File 'lib/jss-api/api_connection.rb', line 207

def timeout= (timeout)
  @cnx.options[:timeout] = timeout
end