zabbix_manager 5.1.4 → 5.1.6

data/lib/zabbix_manager/classes/mediatypes.rb

@@ -2,78 +2,22 @@
 
 class ZabbixManager
   class Mediatypes < Basic
-    # 与 Zabbix API 交互的媒体类型方法名称
+    # 返回媒介类型对象对应的 Zabbix API 方法前缀。
+    # @return [String] API 方法前缀
     def method_name
       "mediatype"
     end
 
-    # 识别特定媒体类型对象的 id 字段名称
+    # 返回媒介类型用于业务识别的字段名。
+    # @return [String] 识别字段名
     def identify
       "name"
     end
 
-    # 默认选项，用于通过 Zabbix API 创建媒体类型对象
+    # 返回媒介类型的最小默认属性；端点和凭据等版本相关字段由调用方显式提供。
+    # @return [Hash] 媒介类型默认属性
     def default_options
-      {
-        name: "", # 媒体类型名称
-        description: "", # 描述
-        type: 0, # 0 - 电子邮件，1 - 外部脚本，2 - 短信，3 - Jabber，100 - EzTexting
-        smtp_server: "",
-        smtp_helo: "",
-        smtp_email: "", # Zabbix 服务器的电子邮件地址
-        exec_path: "",  # 外部脚本的名称
-        gsm_modem: "",  # GSM modem 的串口设备名称
-        username: "", # Zabbix 服务器使用的 Jabber 用户名
-        passwd: "" # Zabbix 服务器使用的 Jabber 密码
-      }
-    end
-
-    # 使用 API 更新媒体类型对象
-    def update(data, force = false)
-      log "[DEBUG] 调用 update 方法，参数: #{data.inspect}"
-      if data[key.to_sym].nil?
-        data[key.to_sym] = get_id(data)
-        log "[DEBUG] 用 ID 丰富数据: #{data.inspect}"
-      end
-      dump = {}
-      dump_by_id(key.to_sym => data[key.to_sym]).each do |item|
-        dump = symbolize_keys(item) if item[key].to_i == data[key.to_sym].to_i
-      end
-      if hash_equals?(dump, data) && !force
-        log "[DEBUG] 键 #{dump} 和 #{data} 相等，跳过更新"
-        data[key.to_sym].to_i
-      else
-        data_update = [data]
-        result = @client.api_request(method: "#{method_name}.update", params: data_update)
-        parse_keys result
-      end
-    end
-
-    # 从 API 获取媒体类型对象的 id
-    def get_id(data)
-      log "[DEBUG] 调用 get_id 方法，参数: #{data.inspect}"
-      data = symbolize_keys(data) if data.key?(identify)
-      name = data[identify.to_sym]
-      raise ZbxError, "未提供 #{identify} 参数，#{data} (#{method_name})" if name.nil?
-
-      result = @client.api_request(
-        method: "#{method_name}.get",
-        params: {
-          filter: { name: name },
-          output: [key, identify]
-        }
-      )
-      id = nil
-      result.each { |item| id = item[key].to_i if item[identify] == data[identify.to_sym] }
-      id
-    end
-
-    # 创建或更新媒体类型对象
-    def create_or_update(data)
-      log "[DEBUG] 调用 create_or_update 方法，参数: #{data.inspect}"
-
-      id = get_id(identify.to_sym => data[identify.to_sym])
-      id ? update(data.merge(key.to_sym => id.to_s)) : create(data)
+      { type: 0 }
     end
   end
 end

data/lib/zabbix_manager/classes/problems.rb

@@ -2,87 +2,105 @@
 
 class ZabbixManager
   class Problems < Basic
-    require "active_support"
-    require "active_support/core_ext/date/calculations"
-
-    # 与 Zabbix API 交互的问题方法名称
+    # 返回问题对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "problem"
     end
 
-    # 识别特定问题对象的 id 字段名称
+    # 返回问题对象用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end
 
-    # 通过键值对从 Zabbix API 转储问题对象数据
+    # 返回问题对象的兼容 ID 字段名；问题对象本身没有独立的唯一标识。
+    #
+    # @return [String]
+    def key
+      "problemid"
+    end
+
+    # 返回问题对象的复数兼容 ID 字段名。
+    #
+    # @return [String]
+    def keys
+      "problemids"
+    end
+
+    # 按识别字段查询问题对象的完整数据。
+    #
+    # @param data [Hash] 包含问题识别字段及其值的查询条件
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Hash] 匹配的问题数据
     def dump_by_id(data)
-      log "[DEBUG] 调用 #{method_name}.dump_by_id 方法，参数: #{data.inspect}"
+      log "[DEBUG] Call dump_by_id with parameters: #{data.inspect}"
 
-      get_raw({
-                filter: {
-                  identify.to_sym => data[identify.to_sym]
-                },
-                output: "extend"
-              })
+      @client.api_request(
+        method: "problem.get",
+        params: {
+          filter: {
+            identify.to_sym => data[identify.to_sym]
+          },
+          output: "extend"
+        }
+      )
     end
 
-    # 从 Zabbix API 获取完整/扩展的问题数据
+    # 获取问题及其确认、标签和抑制信息，并支持附加查询参数。
+    #
+    # @param data [Hash] 问题过滤条件及附加 API 参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Hash] 匹配的问题完整数据
     def get_full_data(data)
-      log "[DEBUG] 调用 #{method_name}.get_full_data 方法，参数: #{data.inspect}"
+      log "[DEBUG] Call get_full_data with parameters: #{data.inspect}"
 
-      data = symbolize_keys(data)
+      data = data.deep_symbolize_keys
+      params = {
+        recent: false,
+        sortfield: ["eventid"],
+        sortorder: "DESC",
+        output: "extend",
+        selectAcknowledges: "extend",
+        selectTags: "extend",
+        selectSuppressionData: "extend"
+      }.merge(data.except(:name).compact)
+      params[:filter] = { identify.to_sym => data[identify.to_sym] } if data[identify.to_sym].present?
 
-      get_raw({
-                filter:                {
-                  identify.to_sym => data[identify.to_sym]
-                },
-                eventids:              data[:eventids] || nil,
-                groupids:              data[:groupids] || nil,
-                hostids:               data[:hostids] || nil,
-                objectids:             data[:objectids] || nil,
-                applicationids:        data[:applicationids] || nil,
-                tags:                  data[:tags] || nil,
-                time_from:             data[:time_from] || nil,
-                time_till:             data[:time_till] || nil,
-                eventid_from:          data[:eventid_from] || nil,
-                eventid_till:          data[:eventid_till] || nil,
-                recent:                data[:recent] || false,
-                sortfield:             data[:sortfield] || ["eventid"],
-                sortorder:             data[:sortorder] || "DESC",
-                countOutput:           data[:countOutput] || nil,
-                output:                "extend",
-                selectAcknowledges:    "extend",
-                selectTags:            "extend",
-                selectSuppressionData: "extend"
-              })
+      @client.api_request(
+        method: "#{method_name}.get",
+        params: params
+      )
     end
 
-    # 获取所有问题对象的完整/扩展 Zabbix 数据
+    # 获取全部问题对象的完整数据。
+    #
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Array<Hash>] 匹配的问题对象列表
     def all
       get_full_data({})
     end
 
-    # 根据给定参数自动确认问题
-    def ack_problem
-      time_from = 90.days.ago.at_beginning_of_day.to_i
-      time_till = 7.days.ago.at_beginning_of_day.to_i
-      event_ids = []
-
-      get_full_data(time_from: time_from, time_till: time_till).each do |item|
-        event_ids << item["eventid"]
-      end
-      return if event_ids.empty?
+    # 批量确认事件，可指定确认动作和附加消息。
+    # @param eventids [Array<String, Integer>, String, Integer] 待确认的事件 ID
+    # @param action [Integer] Zabbix 确认动作位掩码
+    # @param message [String, nil] 可选确认消息
+    # @return [Hash] 事件确认结果
+    def acknowledge_events(eventids, action: 2, message: nil)
+      ids = Array(eventids).map(&:to_s).reject(&:blank?).uniq
+      raise Invalid, "eventids are required" if ids.empty?
 
-      result = @client.api_request(
+      @client.api_request(
         method: "event.acknowledge",
-        params: {
-          eventids: event_ids,
-          action:   2,
-          message:  "本次告警符合自动刷新规则，已通过接口处理且刷新时间为：#{Time.now}"
-        }
+        params: { eventids: ids, action: action, message: message }.compact
       )
-      result.empty? ? nil : result.map { |i| { eventids: i["eventids"] } }
     end
+
+    alias ack_event acknowledge_events
   end
 end

data/lib/zabbix_manager/classes/proxies.rb

@@ -2,30 +2,71 @@
 
 class ZabbixManager
   class Proxies < Basic
-    # 与 Zabbix API 交互的代理方法名称
+    # 返回 Zabbix API 中代理对象的方法名前缀。
+    #
+    # @return [String] 代理对象的方法名前缀
     def method_name
       "proxy"
     end
 
-    # 识别特定代理对象的 id 字段名称
+    # 返回用于唯一识别代理对象的字段名。
+    #
+    # @return [String] 代理对象的标识字段名
     def identify
       "host"
     end
 
-    # 使用 Zabbix API 删除代理对象
+    # 通过 Zabbix API 删除指定代理，并返回首个已删除代理的 ID。
+    #
+    # @param data [Array] 要删除的 proxyid 数组
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer, nil] 已删除代理的 ID，无结果时返回 nil
     def delete(data)
       result = @client.api_request(method: "proxy.delete", params: data)
       result.empty? ? nil : result["proxyids"][0].to_i
     end
 
-    # 检查代理对象是否可读
-    def is_readable(data)
+    # 检查当前凭证是否可读取指定代理。
+    #
+    # @param data [Array] 要检查的 proxyid 数组
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Boolean] 指定代理是否可读
+    def isreadable(data)
       @client.api_request(method: "proxy.isreadable", params: data)
     end
 
-    # 检查代理对象是否可写
-    def is_writable(data)
+    # 检查当前凭证是否可写入指定代理。
+    #
+    # @param data [Array] 要检查的 proxyid 数组
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Boolean] 指定代理是否可写
+    def iswritable(data)
       @client.api_request(method: "proxy.iswritable", params: data)
     end
+
+    # 按代理名称查询唯一代理 ID，空名称返回 nil，重名时拒绝选择。
+    #
+    # @param proxy [String] 代理名称
+    # @return [String, nil] 唯一代理 ID，未找到时返回 nil
+    def get_proxy_id(proxy)
+      return nil if proxy.blank?
+
+      # 请求后端接口，只支持单个代理节点
+      result = @client.api_request(
+        method: "proxy.get",
+        params: {
+          output: %w[proxyid host],
+          filter: {
+            host: proxy
+          }
+        }
+      )
+      raise Conflict, "proxy lookup is ambiguous for #{proxy}" if result.length > 1
+
+      result.first&.fetch("proxyid", nil)
+    end
   end
 end

data/lib/zabbix_manager/classes/roles.rb

@@ -2,51 +2,77 @@
 
 class ZabbixManager
   class Roles < Basic
-    # 与 Zabbix API 交互的角色方法名称
+    # 返回 Zabbix API 中角色对象的方法名前缀。
+    #
+    # @return [String] 角色对象的方法名前缀
     def method_name
       "role"
     end
 
-    # 识别特定角色对象的 id 字段名称
+    # 返回角色对象的主键字段名。
+    #
+    # @return [String] 角色对象的主键字段名
+    def key
+      "roleid"
+    end
+
+    # 返回用于唯一识别角色的业务字段名。
+    #
+    # @return [String] 角色对象的业务标识字段名
     def identify
       "name"
     end
 
-    # 使用 Zabbix API 为用户组设置权限
+    # 更新指定角色的权限规则。
+    #
+    # @param data [Hash] 包含 roleid 和 rules 的角色规则数据
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer] 已更新角色的 ID
     def rules(data)
-      rules  = data[:rules] || 2
+      attributes = data.deep_symbolize_keys
+      raise Invalid, "roleid is required" if attributes[:roleid].blank?
+      raise Invalid, "rules is required" if attributes[:rules].blank?
+
       result = @client.api_request(
         method: "role.update",
         params: {
-          roleid: data[:roleid],
-          rules:  data[:hostgroupids].map { |t| { permission: permission, id: t } }
+          roleid: attributes[:roleid],
+          rules: attributes[:rules]
         }
       )
-      result ? result["usrgrpids"][0].to_i : nil
+      result.fetch("roleids").first.to_i
     end
 
-    # 使用 Zabbix API 将用户添加到用户组
-    def add_user(data)
-      update_users(data)
-    end
-
-    # 从 Zabbix API 中根据指定键和值获取角色对象的数据
+    # 按角色 ID 获取角色详情及完整规则。
+    #
+    # @param data [Hash] 包含 id 的查询参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Array<Hash>] 匹配的角色详情
     def dump_by_id(data)
-      log "[DEBUG] 调用 dump_by_id 方法，参数: #{data.inspect}"
+      log "[DEBUG] Call dump_by_id with parameters: #{data.inspect}"
 
-      get_raw(
-        {
-          output:      "extend",
+      @client.api_request(
+        method: "role.get",
+        params: {
+          output: "extend",
           selectRules: "extend",
-          roleids:     data[:id]
+          roleids: data[:id]
         }
       )
     end
 
-    # 通过角色名称从 Zabbix API 获取角色 id
+    # 按角色名称查询所有匹配的角色 ID。
+    #
+    # @param data [Hash] 包含 name 的角色查询参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Array<String>] 匹配的角色 ID 数组
     def get_ids_by_name(data)
-      result = get_raw(
-        {
+      result = @client.api_request(
+        method: "role.get",
+        params: {
           filter: {
             name: data[:name]
           },
@@ -58,20 +84,5 @@ class ZabbixManager
         rule["roleid"]
       end
     end
-
-    # 使用 Zabbix API 更新用户角色中的用户
-    def update_users(data)
-      user_groups = data[:usrgrpids].map do |t|
-        {
-          usrgrpid: t,
-          userids:  data[:userids]
-        }
-      end
-      result      = @client.api_request(
-        method: "usergroup.update",
-        params: user_groups
-      )
-      result ? result["usrgrpids"][0].to_i : nil
-    end
   end
 end

data/lib/zabbix_manager/classes/screens.rb

@@ -2,7 +2,7 @@
 
 class ZabbixManager
   class Screens < Basic
-    # extracted from frontends/php/include/defines.inc.php
+    # 以下资源类型取自 frontends/php/include/defines.inc.php。
     # SCREEN_RESOURCE_GRAPH => 0,
     # SCREEN_RESOURCE_SIMPLE_GRAPH => 1,
     # SCREEN_RESOURCE_MAP => 2,
@@ -21,45 +21,61 @@ class ZabbixManager
     # SCREEN_RESOURCE_SYSTEM_STATUS => 15,
     # SCREEN_RESOURCE_HOST_TRIGGERS => 16
 
-    # 与 Zabbix API 交互的屏幕方法名称
+    # 返回 Zabbix API 中聚合图形对象的方法名前缀。
+    #
+    # @return [String] 聚合图形对象的方法名前缀
     def method_name
       "screen"
     end
 
-    # 用于通过 Zabbix API 标识特定屏幕对象的 ID 字段名称
+    # 返回用于唯一识别聚合图形的业务字段名。
+    #
+    # @return [String] 聚合图形的业务标识字段名
     def identify
       "name"
     end
 
-    # 删除 Zabbix API 中的屏幕对象
+    # 删除指定聚合图形并返回首个已删除对象的 ID。
+    #
+    # @param data [String, Array] 要删除的聚合图形 ID
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer, nil] 已删除聚合图形的 ID，无结果时返回 nil
     def delete(data)
       result = @client.api_request(method: "screen.delete", params: [data])
       result.empty? ? nil : result["screenids"][0].to_i
     end
 
-    # 使用 Zabbix API 为主机获取或创建屏幕对象
+    # 按名称获取聚合图形，不存在时按图形 ID 网格化创建。
+    #
+    # @param data [Hash] 包含 screen_name、graphids 及可选布局参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer] 聚合图形 ID
     def get_or_create_for_host(data)
       screen_name = data[:screen_name]
-      graphids = data[:graphids]
-      screenitems = []
-      hsize = data[:hsize] || 3
+      graphids = Array(data[:graphids])
+      raise Invalid, "screen_name is required" if screen_name.blank?
+      raise Invalid, "graphids must contain at least one graph" if graphids.empty?
+
+      hsize = positive_hsize(data.fetch(:hsize, 3))
+
       valign = data[:valign] || 2
       halign = data[:halign] || 2
       rowspan = data[:rowspan] || 1
       colspan = data[:colspan] || 1
       height = data[:height] || 320
       width = data[:width] || 200
-      vsize = data[:vsize] || [1, (graphids.size / hsize).to_i].max
+      vsize = data[:vsize] || graphids.length.fdiv(hsize).ceil
       screenid = get_id(name: screen_name)
 
       unless screenid
-        # 创建屏幕
-        graphids.each_with_index do |graphid, index|
-          screenitems << {
+        screenitems = graphids.each_with_index.map do |graphid, index|
+          {
             resourcetype: 0,
             resourceid: graphid,
-            x: (index % hsize).to_i,
-            y: (index % graphids.size / hsize).to_i,
+            x: index % hsize,
+            y: index / hsize,
             valign: valign,
             halign: halign,
             rowspan: rowspan,
@@ -78,5 +94,20 @@ class ZabbixManager
       end
       screenid
     end
+
+    private
+
+      # 将横向格数转换为正整数，非法值直接拒绝。
+      #
+      # @param value [Object] 待校验的横向格数
+      # @return [Integer] 正整数横向格数
+      def positive_hsize(value)
+        size = Integer(value)
+        raise Invalid unless size.positive?
+
+        size
+      rescue ArgumentError, TypeError
+        raise Invalid, "hsize must be a positive integer"
+      end
   end
 end

data/lib/zabbix_manager/classes/scripts.rb

@@ -2,20 +2,27 @@
 
 class ZabbixManager
   class Scripts < Basic
-    # 与 Zabbix API 交互的方法名称
+    # 返回 Zabbix API 中脚本对象的方法名前缀。
+    #
+    # @return [String] 脚本对象的方法名前缀
     def method_name
       "script"
     end
 
-    # 用于通过 Zabbix API 标识特定脚本对象的 ID 字段名称
+    # 返回用于唯一识别脚本的业务字段名。
+    #
+    # @return [String] 脚本对象的业务标识字段名
     def identify
       "name"
     end
 
-    # 执行 Zabbix API 中特定主机上的脚本
+    # 在指定主机上执行 Zabbix 脚本。
     #
-    # 示例:
-    #   execute({ scriptid: '12', hostid: '32' })
+    # 示例：
+    #   execute({ scriptid: '12', hostid: '32 })
+    #
+    # @param data [Hash] 包含 scriptid 和 hostid 的执行参数
+    # @return [Hash] Zabbix API 返回的脚本执行结果
     def execute(data)
       @client.api_request(
         method: "script.execute",
@@ -26,8 +33,11 @@ class ZabbixManager
       )
     end
 
-    # 使用 Zabbix API 通过主机获取脚本
-    def get_scripts_by_host(data)
+    # 查询指定主机可用的脚本。
+    #
+    # @param data [Hash] Zabbix scripts.getscriptsbyhosts 查询参数
+    # @return [Array<Hash>] 主机可用脚本列表
+    def getscriptsbyhost(data)
       @client.api_request(method: "script.getscriptsbyhosts", params: data)
     end
   end

data/lib/zabbix_manager/classes/server.rb

@@ -2,9 +2,15 @@
 
 class ZabbixManager
   class Server
+    # 返回连接对应的 Zabbix API 版本。
+    #
+    # @return [String] Zabbix API 版本号
     attr_reader :version
 
-    # 初始化一个新的 Server 对象，使用 ZabbixManager 客户端，并获取 Zabbix 服务器 API 版本
+    # 使用客户端初始化服务信息，并立即读取 Zabbix API 版本。
+    #
+    # @param client [ZabbixManager::Client] 已建立配置的 Zabbix 客户端
+    # @return [Server] 已初始化的服务信息对象
     def initialize(client)
       @client = client
       @version = @client.api_version