zabbixapi 3.1.0 → 3.2.1

data/lib/zabbixapi/classes/triggers.rb

@@ -1,32 +1,49 @@
 class ZabbixApi
   class Triggers < Basic
-
+    # The method name used for interacting with Triggers via Zabbix API
+    #
+    # @return [String]
     def method_name
-      "trigger"
+      'trigger'
     end
 
+    # The id field name used for identifying specific Trigger objects via Zabbix API
+    #
+    # @return [String]
     def indentify
-      "description"
+      'description'
     end
 
+    # Dump Trigger object data by key from Zabbix API
+    #
+    # @param data [Hash] Should include desired object's key and value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Hash]
     def dump_by_id(data)
       log "[DEBUG] Call dump_by_id with parametrs: #{data.inspect}"
 
       @client.api_request(
-        :method => "trigger.get",
+        :method => 'trigger.get',
         :params => {
           :filter => {
-            key.to_sym => data[key.to_sym]
+            key.to_sym => data[key.to_sym],
           },
-          :output => "extend",
-          :select_items => "extend",
-          :select_functions => "extend"
+          :output => 'extend',
+          :select_items => 'extend',
+          :select_functions => 'extend',
         }
       )
     end
 
+    # Safely update Trigger object using Zabbix API by deleting and replacing trigger
+    #
+    # @param data [Hash] Needs to include description and hostid to properly identify Triggers via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def safe_update(data)
-      log "[DEBUG] Call update with parametrs: #{data.inspect}"
+      log "[DEBUG] Call safe_update with parameters: #{data.inspect}"
 
       dump = {}
       item_id = data[key.to_sym].to_i
@@ -34,31 +51,36 @@ class ZabbixApi
         dump = symbolize_keys(item) if item[key].to_i == data[key.to_sym].to_i
       end
 
-      expression = dump[:items][0][:key_]+"."+dump[:functions][0][:function]+"("+dump[:functions][0][:parameter]+")"
-      dump[:expression] = dump[:expression].gsub(/\{(\d*)\}/,"{#{expression}}") #TODO ugly regexp
+      expression = dump[:items][0][:key_] + '.' + dump[:functions][0][:function] + '(' + dump[:functions][0][:parameter] + ')'
+      dump[:expression] = dump[:expression].gsub(/\{(\d*)\}/, "{#{expression}}") # TODO: ugly regexp
       dump.delete(:functions)
       dump.delete(:items)
 
       old_expression = data[:expression]
-      data[:expression] = data[:expression].gsub(/\{.*\:/,"{") #TODO ugly regexp
+      data[:expression] = data[:expression].gsub(/\{.*\:/, '{') # TODO: ugly regexp
       data.delete(:templateid)
 
       log "[DEBUG] expression: #{dump[:expression]}\n data: #{data[:expression]}"
 
       if hash_equals?(dump, data)
-        log "[DEBUG] Equal keys #{dump} and #{data}, skip update"
+        log "[DEBUG] Equal keys #{dump} and #{data}, skip safe_update"
         item_id
       else
         data[:expression] = old_expression
         # disable old trigger
-        log "[DEBUG] disable :" + @client.api_request(:method => "#{method_name}.update", :params => [{:triggerid=> data[:triggerid], :status => "1" }]).inspect
+        log '[DEBUG] disable :' + @client.api_request(:method => "#{method_name}.update", :params => [{:triggerid => data[:triggerid], :status => '1'}]).inspect
         # create new trigger
         data.delete(:triggerid)
         create(data)
       end
-
     end
 
+    # Get or Create Trigger object using Zabbix API
+    #
+    # @param data [Hash] Needs to include description and hostid to properly identify Triggers via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def get_or_create(data)
       log "[DEBUG] Call get_or_create with parameters: #{data.inspect}"
 
@@ -68,10 +90,15 @@ class ZabbixApi
       id
     end
 
+    # Create or update Trigger object using Zabbix API
+    #
+    # @param data [Hash] Needs to include description and hostid to properly identify Triggers via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def create_or_update(data)
       triggerid = get_id(:description => data[:description], :hostid => data[:hostid])
       triggerid ? update(data.merge(:triggerid => triggerid)) : create(data)
     end
-
   end
 end

data/lib/zabbixapi/classes/unusable.rb

@@ -1,10 +1,8 @@
 class ZabbixApi
   class Triggers < Basic
-
     def create_or_update(data)
       log "[DEBUG] Call create_or_update with parametrs: #{data.inspect}"
       get_or_create(data)
     end
-
   end
 end

data/lib/zabbixapi/classes/usergroups.rb

@@ -1,69 +1,76 @@
 class ZabbixApi
   class Usergroups < Basic
-
+    # The method name used for interacting with Usergroups via Zabbix API
+    #
+    # @return [String]
     def method_name
-      "usergroup"
+      'usergroup'
     end
 
+    # The key field name used for Usergroup objects via Zabbix API
+    #
+    # @return [String]
     def key
-      "usrgrpid"
+      'usrgrpid'
     end
 
+    # The id field name used for identifying specific Usergroup objects via Zabbix API
+    #
+    # @return [String]
     def indentify
-      "name"
+      'name'
     end
 
-    # Set permission for usrgrp on some hostgroup
+    # Set permissions for usergroup using Zabbix API
     #
-    # * *Args*    :
-    #   - +data+ -> Hash with :usrgrpids => id, :hostgroupids => [], :permission => 2,3 (read and read write)
-    # * *Returns* :
-    #   - Integer
+    # @param data [Hash] Needs to include usrgrpids and hostgroupids along with permissions to set
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id (usergroup)
     def set_perms(data)
       permission = data[:permission] || 2
       result = @client.api_request(
-        :method => "usergroup.massAdd",
+        :method => 'usergroup.massAdd',
         :params => {
           :usrgrpids => [data[:usrgrpid]],
-          :rights => data[:hostgroupids].map { |t| {:permission => permission, :id => t} }
+          :rights => data[:hostgroupids].map { |t| {:permission => permission, :id => t} },
         }
       )
       result ? result['usrgrpids'][0].to_i : nil
     end
 
-    # Update usergroup, add user
+    # Add users to usergroup using Zabbix API
     #
-    # * *Args*    :
-    #   - +data+ -> Hash with :usrgrpids => id, :userids => []
-    # * *Returns* :
-    #   - Integer
+    # @param data [Hash] Needs to include userids and usrgrpids to mass add users to groups
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id (usergroup)
     def add_user(data)
       result = @client.api_request(
-        :method => "usergroup.massAdd",
+        :method => 'usergroup.massAdd',
         :params => {
           :usrgrpids => data[:usrgrpids],
-          :userids => data[:userids]
+          :userids => data[:userids],
         }
       )
       result ? result['usrgrpids'][0].to_i : nil
     end
 
-    # Update usergroup, modify users
+    # Update users in usergroups using Zabbix API
     #
-    # * *Args*    :
-    #   - +data+ -> Hash with :usrgrpids => id, :userids => []
-    # * *Returns* :
-    #   - Integer
+    # @param data [Hash] Needs to include userids and usrgrpids to mass update users in groups
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id (usergroup)
     def update_users(data)
       result = @client.api_request(
-        :method => "usergroup.massUpdate",
+        :method => 'usergroup.massUpdate',
         :params => {
           :usrgrpids => data[:usrgrpids],
-          :userids => data[:userids]
+          :userids => data[:userids],
         }
       )
       result ? result['usrgrpids'][0].to_i : nil
     end
-
   end
 end

data/lib/zabbixapi/classes/usermacros.rb

@@ -1,79 +1,159 @@
 class ZabbixApi
   class Usermacros < Basic
+    # The id field name used for identifying specific User macro objects via Zabbix API
+    #
+    # @return [String]
     def indentify
-      "macro"
+      'macro'
     end
 
+    # The method name used for interacting with User macros via Zabbix API
+    #
+    # @return [String]
     def method_name
-      "usermacro"
+      'usermacro'
     end
 
+    # Get User macro object id from Zabbix API based on provided data
+    #
+    # @param data [Hash] Needs to include macro to properly identify user macros via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call or missing object's id field name (indentify).
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def get_id(data)
       log "[DEBUG] Call get_id with parameters: #{data.inspect}"
 
       # symbolize keys if the user used string keys instead of symbols
       data = symbolize_keys(data) if data.key?(indentify)
-      # raise an error if indentify name was not supplied 
+      # raise an error if indentify name was not supplied
       name = data[indentify.to_sym]
-      raise ApiError.new("#{indentify} not supplied in call to get_id") if name == nil
+      raise ApiError.new("#{indentify} not supplied in call to get_id") if name.nil?
 
-      result = request(data, "usermacro.get", "hostmacroid")
+      result = request(data, 'usermacro.get', 'hostmacroid')
 
-      result.length > 0 && result[0].key?("hostmacroid") ? result[0]["hostmacroid"].to_i : nil
+      !result.empty? && result[0].key?('hostmacroid') ? result[0]['hostmacroid'].to_i : nil
     end
 
+    # Get Global macro object id from Zabbix API based on provided data
+    #
+    # @param data [Hash] Needs to include macro to properly identify global macros via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call or missing object's id field name (indentify).
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def get_id_global(data)
       log "[DEBUG] Call get_id_global with parameters: #{data.inspect}"
 
       # symbolize keys if the user used string keys instead of symbols
       data = symbolize_keys(data) if data.key?(indentify)
-      # raise an error if indentify name was not supplied 
+      # raise an error if indentify name was not supplied
       name = data[indentify.to_sym]
-      raise ApiError.new("#{indentify} not supplied in call to get_id") if name == nil
+      raise ApiError.new("#{indentify} not supplied in call to get_id") if name.nil?
 
-      result = request(data, "usermacro.get", "globalmacroid")
+      result = request(data, 'usermacro.get', 'globalmacroid')
 
-      result.length > 0 && result[0].key?("globalmacroid") ? result[0]["globalmacroid"].to_i : nil
+      !result.empty? && result[0].key?('globalmacroid') ? result[0]['globalmacroid'].to_i : nil
     end
 
+    # Get full/extended User macro data from Zabbix API
+    #
+    # @param data [Hash] Should include object's id field name (indentify) and id value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Hash]
     def get_full_data(data)
       log "[DEBUG] Call get_full_data with parameters: #{data.inspect}"
 
-      request(data, "usermacro.get", "hostmacroid")
+      request(data, 'usermacro.get', 'hostmacroid')
     end
 
+    # Get full/extended Global macro data from Zabbix API
+    #
+    # @param data [Hash] Should include object's id field name (indentify) and id value
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Hash]
     def get_full_data_global(data)
       log "[DEBUG] Call get_full_data_global with parameters: #{data.inspect}"
 
-      request(data, "usermacro.get", "globalmacroid")
+      request(data, 'usermacro.get', 'globalmacroid')
     end
 
+    # Create new User macro object using Zabbix API (with defaults)
+    #
+    # @param data [Hash] Needs to include hostid, macro, and value to create User macro via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is created
+    # @return [Boolean] True/False if multiple objects are created
     def create(data)
-      request(data, "usermacro.create", "hostmacroids")
+      request(data, 'usermacro.create', 'hostmacroids')
     end
 
+    # Create new Global macro object using Zabbix API (with defaults)
+    #
+    # @param data [Hash] Needs to include hostid, macro, and value to create Global macro via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is created
+    # @return [Boolean] True/False if multiple objects are created
     def create_global(data)
-      request(data, "usermacro.createglobal", "globalmacroids")
+      request(data, 'usermacro.createglobal', 'globalmacroids')
     end
 
+    # Delete User macro object using Zabbix API
+    #
+    # @param data [Hash] Should include hostmacroid's of User macros to delete
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is deleted
+    # @return [Boolean] True/False if multiple objects are deleted
     def delete(data)
       data_delete = [data]
-      request(data_delete, "usermacro.delete", "hostmacroids")
+      request(data_delete, 'usermacro.delete', 'hostmacroids')
     end
 
+    # Delete Global macro object using Zabbix API
+    #
+    # @param data [Hash] Should include hostmacroid's of Global macros to delete
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is deleted
+    # @return [Boolean] True/False if multiple objects are deleted
     def delete_global(data)
       data_delete = [data]
-      request(data_delete, "usermacro.deleteglobal", "globalmacroids")
+      request(data_delete, 'usermacro.deleteglobal', 'globalmacroids')
     end
 
+    # Update User macro object using Zabbix API
+    #
+    # @param data [Hash] Should include object's id field name (indentify), id value, and fields to update
+    # @param force [Boolean] Whether to force an object update even if provided data matches Zabbix
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is created
+    # @return [Boolean] True/False if multiple objects are created
     def update(data)
-      request(data, "usermacro.update", "hostmacroids")
+      request(data, 'usermacro.update', 'hostmacroids')
     end
 
+    # Update Global macro object using Zabbix API
+    #
+    # @param data [Hash] Should include object's id field name (indentify), id value, and fields to update
+    # @param force [Boolean] Whether to force an object update even if provided data matches Zabbix
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] The object id if a single object is created
+    # @return [Boolean] True/False if multiple objects are created
     def update_global(data)
-      request(data, "usermacro.updateglobal", "globalmacroids")
+      request(data, 'usermacro.updateglobal', 'globalmacroids')
     end
 
+    # Get or Create User macro object using Zabbix API
+    #
+    # @param data [Hash] Needs to include macro and hostid to properly identify User macros via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def get_or_create(data)
       log "[DEBUG] Call get_or_create with parameters: #{data.inspect}"
 
@@ -83,6 +163,12 @@ class ZabbixApi
       id
     end
 
+    # Get or Create Global macro object using Zabbix API
+    #
+    # @param data [Hash] Needs to include macro and hostid to properly identify Global macros via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def get_or_create_global(data)
       log "[DEBUG] Call get_or_create_global with parameters: #{data.inspect}"
 
@@ -92,31 +178,51 @@ class ZabbixApi
       id
     end
 
+    # Create or update User macro object using Zabbix API
+    #
+    # @param data [Hash] Needs to include macro and hostid to properly identify User macros via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def create_or_update(data)
       hostmacroid = get_id(:macro => data[:macro], :hostid => data[:hostid])
       hostmacroid ? update(data.merge(:hostmacroid => hostmacroid)) : create(data)
     end
 
+    # Create or update Global macro object using Zabbix API
+    #
+    # @param data [Hash] Needs to include macro and hostid to properly identify Global macros via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
     def create_or_update_global(data)
       hostmacroid = get_id_global(:macro => data[:macro], :hostid => data[:hostid])
       hostmacroid ? update_global(data.merge(:globalmacroid => globalmacroid)) : create_global(data)
     end
 
-    private
-      def request(data, method, result_key)
-        # Zabbix has different result formats for gets vs updates
-        if method.include?(".get")
-          if result_key.include?("global")
-            result = @client.api_request(:method => method, :params => { :globalmacro => true, :filter => data })
-          else
-            result = @client.api_request(:method => method, :params => { :filter => data })
-          end
+  private
+
+    # Custom request method to handle both User and Global macros in one
+    #
+    # @param data [Hash] Needs to include macro and hostid to properly identify Global macros via Zabbix API
+    # @param method [String] Zabbix API method to use for the request
+    # @param result_key [String] Which key to use for parsing results based on User vs Global macros
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
+    def request(data, method, result_key)
+      # Zabbix has different result formats for gets vs updates
+      if method.include?('.get')
+        if result_key.include?('global')
+          @client.api_request(:method => method, :params => {:globalmacro => true, :filter => data})
         else
-          result = @client.api_request(:method => method, :params => data)
-
-          result.key?(result_key) && result[result_key].length > 0 ? result[result_key][0].to_i : nil
+          @client.api_request(:method => method, :params => {:filter => data})
         end
-      end
+      else
+        result = @client.api_request(:method => method, :params => data)
 
+        result.key?(result_key) && !result[result_key].empty? ? result[result_key][0].to_i : nil
+      end
+    end
   end
 end