zabbix_manager 5.1.5 → 6.0.0

data/lib/zabbix_manager/classes/items.rb

@@ -1,95 +1,229 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Items < Basic
-    # 用于通过 Zabbix API 与 Items 交互的方法名称
+  # 监控项查询与写入；通用 CRUD 使用名称，专用 upsert 使用 hostid + key_。
+  class Items < Resource
+    DEFAULT_OPTIONS = {
+      delay: "1m",
+      history: "1h",
+      status: 0,
+      value_type: 3
+    }.freeze
+    ITEM_TYPES = [0, 2, 3, 5, 7, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22].freeze
+    REQUIRED_INTERFACE_TYPES = [0, 12, 16, 17, 20].freeze
+    REQUIRED_PARAMS_TYPES = [11, 13, 14, 15, 21, 22].freeze
+
+    # 返回监控项对应的 Zabbix API 模块名。
+    #
+    # @return [String]
     def method_name
       "item"
     end
 
-    # 用于通过 Zabbix API 标识特定 Item 对象的 id 字段名称
-    def identify
-      "name"
+    # 返回创建监控项时的克制默认值。
+    #
+    # @return [Hash]
+    def default_options
+      DEFAULT_OPTIONS.dup
     end
 
-    # 通过 Zabbix API 创建 Item 对象时使用的默认选项
-    def default_options
-      {
-        name:                  nil,
-        key_:                  nil,
-        hostid:                nil,
-        delay:                 60,
-        history:               3600,
-        status:                0,
-        type:                  7,
-        snmp_community:        "",
-        snmp_oid:              "",
-        value_type:            3,
-        data_type:             0,
-        trapper_hosts:         "localhost",
-        snmp_port:             161,
-        units:                 "",
-        multiplier:            0,
-        delta:                 0,
-        snmpv3_securityname:   "",
-        snmpv3_securitylevel:  0,
-        snmpv3_authpassphrase: "",
-        snmpv3_privpassphrase: "",
-        formula:               0,
-        trends:                86_400,
-        logtimefmt:            "",
-        valuemapid:            0,
-        delay_flex:            "",
-        authtype:              0,
-        username:              "",
-        password:              "",
-        publickey:             "",
-        privatekey:            "",
-        params:                "",
-        ipmi_sensor:           ""
-      }
-    end
-
-    # 通过 Zabbix API 获取或创建 Item 对象
-    def get_or_create(data)
-      log "[DEBUG] 调用 #{method_name}.get_or_create 方法，参数: #{data.inspect}"
-
-      if (id = get_id(name: data[:name], hostid: data[:hostid]))
-        id
-      else
-        create(data)
-      end
+    # 使用主机和名称组成通用 CRUD 的查询边界。
+    #
+    # @param data [Hash] 包含 name 和 hostid 的监控项属性
+    # @raise [ApiError] Zabbix API 明确返回业务错误
+    # @raise [TransportError] HTTP 或网络请求失败，可能无法确认远端结果
+    # @return [Hash] 名称和所属主机组成的精确过滤条件
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
+    end
+
+    # 查询主机监控项，可按稳定 key 集合过滤并选择关联对象。
+    # @return [Array<Hash>]
+    def for_host(hostid, keys: nil, output: "extend", select_preprocessing: nil, select_tags: nil)
+      raise Invalid, "hostid is required" if hostid.blank?
+
+      params = { hostids: hostid, output: output }
+      params[:filter] = { key_: keys } if keys.present?
+      params[:selectPreprocessing] = select_preprocessing if select_preprocessing
+      params[:selectTags] = select_tags if select_tags
+      @client.api_request(method: "item.get", params: params)
+    end
+
+    # 按主机和稳定 key 查询唯一监控项。
+    # @return [Hash, nil]
+    def find_by_key(hostid:, key:)
+      result = for_host(hostid, keys: key, output: "extend", select_preprocessing: "extend")
+      raise Conflict, "multiple items use key #{key} on host #{hostid}" if result.length > 1
+
+      result.first
+    end
+
+    # 按 hostid + key_ 幂等创建或更新监控项。
+    # @return [Integer]
+    def upsert_by_key(data)
+      apply_item(*plan_item(validate_item!(data)))
     end
 
-    # 通过 Zabbix API 创建或更新 Item 对象
-    def create_or_update(data)
-      itemid = get_id(name: data[:name], hostid: data[:hostid])
-      itemid ? update(data.merge(itemid: itemid)) : create(data)
+    # 先校验整批数据，再按稳定 key 逐项幂等写入。
+    # @yieldparam effective [Array<Hash>] 合并已有配置或创建默认值后的有效属性；块失败时不写入
+    # @return [Array<Integer>]
+    def upsert_many(collection)
+      items = Array(collection).map { |data| validate_item!(data) }
+      identities = items.map { |item| [item[:hostid].to_s, item[:key_].to_s] }
+      duplicate = identities.tally.find { |_identity, count| count > 1 }&.first
+      raise Invalid, "duplicate hostid + key_ identity #{duplicate.join(":")}" if duplicate
+
+      plans = items.map { |item| plan_item(item) }
+      if block_given?
+        effective = plans.map do |attributes, current|
+          if current && !%w[type value_type].all? { |field| current.key?(field) }
+            raise ProtocolError, "item.get must include type and value_type for effective configuration validation"
+          end
+
+          current ? current.deep_symbolize_keys.merge(attributes).deep_dup : attributes.deep_dup
+        end
+        yield effective
+      end
+      plans.map { |attributes, current| apply_item(attributes, current) }
     end
 
-    # 通过 Zabbix API 获取特定主机和接口下的监控项
-    def get_interface_items(hostid, name)
-      # 记录调试信息，标识方法调用以及传递的参数
-      log "[DEBUG] 调用 #{method_name}.get_interface_items，参数：hostid #{hostid.inspect}，name #{name.inspect}"
+    # 批量启用或停用监控项。
+    # @return [Array<Integer>]
+    def set_status(hostid:, itemids:, enabled:)
+      validate_boolean!(enabled, "enabled")
+      ids = normalized_ids(itemids)
+      verify_host_ownership!(hostid, ids)
+      result = @client.api_request(
+        method: "item.update",
+        params: ids.map { |itemid| { itemid: itemid, status: enabled ? 0 : 1 } }
+      )
+      response_ids(result, expected: ids)
+    end
 
-      # 自动剔除收尾空白字符，规范化接口名
-      _name = name&.gsub(%r{[^/0-9]}, "")&.strip
-      iface = "#{_name}("
+    # 批量删除明确指定的监控项。
+    # @return [Array<Integer>]
+    def delete_many(hostid:, itemids:)
+      ids = normalized_ids(itemids)
+      verify_host_ownership!(hostid, ids)
+      result = @client.api_request(method: "item.delete", params: ids)
+      response_ids(result, expected: ids)
+    end
 
-      # 使用 Zabbix API 进行模糊查询，获取特定主机和接口下的监控项
-      result = get_raw(
-        {
-          output:  "extend",
+    # 返回主机中可能表示接口流量的已启用监控项。
+    # 方向和接口精确匹配由 Monitoring 业务层负责。
+    # @return [Array<Hash>]
+    def monitored_traffic_candidates(hostid)
+      @client.api_request(
+        method: "item.get",
+        params: {
           hostids: [hostid],
-          search:  { name: iface }
+          monitored: true,
+          output: %w[itemid hostid name key_ type snmp_oid value_type status units],
+          selectPreprocessing: "extend",
+          sortfield: "name",
+          sortorder: "ASC"
         }
       )
+    end
+
+    # 按主机接口幂等创建或更新 DNS 解析监控项，并返回监控项 ID。
+    # DNS 名称会进入 item key，因此拒绝可能改变 key 参数结构的分隔符。
+    # @return [Integer]
+    def upsert_dns_item(hostid:, interfaceid:, dns_name:)
+      name = dns_name.to_s.strip
+      raise Invalid, "dns_name is required" if name.blank?
+      raise Invalid, "dns_name contains unsupported item key delimiters" if name.match?(/[\[\],]/)
+
+      upsert_by_key(
+        hostid: hostid,
+        interfaceid: interfaceid,
+        name: "【DNS域名解析监控】#{name}",
+        key_: "net.dns.record[,#{name},A,2,2]",
+        type: 0,
+        value_type: 1,
+        delay: "1m",
+        history: "90d",
+        timeout: "3s"
+      )
+    end
 
-      # 过滤结果，只保留符合正则表达式的项
-      filtered_result = result.select { |item| item["snmp_oid"].match?(/(1.3.6.1.2.1.31.1.1.1.(6|10|15)|1.3.6.1.2.1.2.2.1.8)./) }
+    private
 
-      # 如果结果为空，则返回 nil；否则，返回排序后的结果
-      filtered_result.empty? ? nil : filtered_result.sort_by { |item| item["key_"] }
+    # 创建必填字段必须在整批写入开始前校验。
+    def plan_item(attributes)
+      current = find_by_key(hostid: attributes[:hostid], key: attributes[:key_])
+      validate_item_type!(attributes[:type]) if attributes.key?(:type)
+      response_identifier(current["itemid"]) if current
+      unless current
+        attributes = default_options.merge(attributes)
+        validate_create_item!(attributes)
+      end
+      [attributes, current]
+    end
+
+    def apply_item(attributes, current)
+      if current
+        itemid = current.fetch("itemid")
+        result = @client.api_request(method: "item.update", params: attributes.except(:hostid).merge(itemid: itemid))
+        response_id(result, expected: [itemid])
+      else
+        result = @client.api_request(method: "item.create", params: attributes)
+        response_id(result)
+      end
+    end
+
+    # 规范化并校验幂等写入所需字段。
+    # @return [Hash]
+    # @api private
+    def validate_item!(data)
+      attributes = data.deep_symbolize_keys
+      raise Invalid, "hostid is required" if attributes[:hostid].blank?
+      raise Invalid, "key_ is required" if attributes[:key_].blank?
+      raise Invalid, "name is required" if attributes[:name].blank?
+
+      attributes
+    end
+
+    # 校验 item.create 的通用必填字段和 SNMP 条件字段。
+    def validate_create_item!(attributes)
+      raise Invalid, "type is required when creating an item" if attributes[:type].blank?
+      raise Invalid, "value_type is required when creating an item" if attributes[:value_type].blank?
+
+      type = validate_item_type!(attributes[:type])
+
+      if REQUIRED_INTERFACE_TYPES.include?(type) && attributes[:interfaceid].blank?
+        raise Invalid, "interfaceid is required for item type #{type}"
+      end
+      if REQUIRED_PARAMS_TYPES.include?(type) && attributes[:params].blank?
+        raise Invalid, "params is required for item type #{type}"
+      end
+
+      raise Invalid,
+            "master_itemid is required for a dependent item" if type == 18 && attributes[:master_itemid].blank?
+      raise Invalid, "url is required for an HTTP item" if type == 19 && attributes[:url].blank?
+      return unless type == 20
+
+      raise Invalid, "snmp_oid is required for an SNMP item" if attributes[:snmp_oid].blank?
+    end
+
+    def validate_item_type!(value)
+      type = integer_attribute(value, "type")
+      raise Invalid, "unsupported item type #{type}" unless ITEM_TYPES.include?(type)
+
+      type
+    end
+
+    # 回查监控项归属，阻止共享高权限令牌跨主机修改。
+    def verify_host_ownership!(hostid, ids)
+      raise Invalid, "hostid is required" if hostid.blank?
+
+      result = @client.api_request(
+        method: "item.get", params: { hostids: hostid, itemids: ids, output: ["itemid"] }
+      )
+      owned_ids = result.map { |item| item.fetch("itemid").to_s }
+      foreign_ids = ids - owned_ids
+      raise Conflict, "items do not belong to host #{hostid}: #{foreign_ids.join(", ")}" if foreign_ids.any?
     end
   end
 end

data/lib/zabbix_manager/classes/maintenance.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Maintenance < Basic
-    # 用于通过 Zabbix API 与维护窗口对象交互的方法名称
+  # 原生维护期资源；时间段、目标主机和群组由调用方显式定义。
+  class Maintenance < Resource
+    # 返回维护期对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "maintenance"
     end
 
-    # 用于通过 Zabbix API 识别特定维护窗口对象的 id 字段名称
+    # 返回维护期对象用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end

data/lib/zabbix_manager/classes/media_types.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 原生通知媒介资源；仅提供最小默认值，不推断端点、凭据或版本字段。
+  class MediaTypes < Resource
+    # 返回媒介类型对象对应的 Zabbix API 方法前缀。
+    # @return [String] API 方法前缀
+    def method_name
+      "mediatype"
+    end
+
+    # 返回媒介类型的最小默认属性；端点和凭据等版本相关字段由调用方显式提供。
+    # @return [Hash] 媒介类型默认属性
+    def default_options
+      { type: 0 }
+    end
+  end
+end

data/lib/zabbix_manager/classes/problems.rb

@@ -1,88 +1,77 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Problems < Basic
-    require "active_support"
-    require "active_support/core_ext/date/calculations"
-
-    # 与 Zabbix API 交互的问题方法名称
+  # 原生问题查询与事件确认；问题身份使用 eventid，确认动作属于远端写入。
+  class Problems < Resource
+    # 返回问题对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "problem"
     end
 
-    # 识别特定问题对象的 id 字段名称
-    def identify
-      "name"
+    # 使用触发问题的事件 ID 作为对象身份。
+    #
+    # @return [String]
+    def key
+      "eventid"
     end
 
-    # 通过键值对从 Zabbix API 转储问题对象数据
-    def dump_by_id(data)
-      log "[DEBUG] 调用 #{method_name}.dump_by_id 方法，参数: #{data.inspect}"
-
-      get_raw({
-                filter: {
-                  identify.to_sym => data[identify.to_sym]
-                },
-                output: "extend"
-              })
+    # 返回事件 ID 集合字段名。
+    #
+    # @return [String]
+    def keys
+      "eventids"
     end
 
-    # 从 Zabbix API 获取完整/扩展的问题数据
+    # 获取问题及其确认、标签和抑制信息，并支持附加查询参数。
+    #
+    # @param data [Hash] 问题过滤条件及附加 API 参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Array<Hash>] 匹配的问题完整数据
     def get_full_data(data)
-      log "[DEBUG] 调用 #{method_name}.get_full_data 方法，参数: #{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 = normalized_ids(eventids)
 
       result = @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"] } }
+      response_ids(result, expected: ids)
+      result
     end
   end
 end

data/lib/zabbix_manager/classes/proxies.rb

@@ -1,31 +1,62 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Proxies < Basic
-    # 与 Zabbix API 交互的代理方法名称
+  # 原生代理资源；按服务器版本选择 name 或 host 作为名称字段。
+  class Proxies < Resource
+    # 返回 Zabbix API 中代理对象的方法名前缀。
+    #
+    # @return [String] 代理对象的方法名前缀
     def method_name
       "proxy"
     end
 
-    # 识别特定代理对象的 id 字段名称
+    # 返回用于唯一识别代理对象的字段名。
+    #
+    # @return [String] 代理对象的标识字段名
     def identify
-      "host"
+      Gem::Version.new(@client.api_version) >= Gem::Version.new("7.0") ? "name" : "host"
     end
 
-    # 使用 Zabbix API 删除代理对象
-    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: ["proxyid", identify],
+          filter: {
+            identify.to_sym => 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/proxy_groups.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # Zabbix 7.0 起提供的原生代理组资源。
+  class ProxyGroups < Resource
+    # @return [String] 原生 API 方法前缀
+    def method_name
+      "proxygroup"
+    end
+
+    # @return [String] 原生代理组 ID 字段
+    def key
+      "proxy_groupid"
+    end
+  end
+end