zabbix_manager 5.1.6 → 6.0.0

data/lib/zabbix_manager/classes/items.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Items < Basic
+  # 监控项查询与写入；通用 CRUD 使用名称，专用 upsert 使用 hostid + key_。
+  class Items < Resource
     DEFAULT_OPTIONS = {
       delay: "1m",
       history: "1h",
@@ -19,13 +20,6 @@ class ZabbixManager
       "item"
     end
 
-    # 使用名称作为通用 CRUD 的业务标识。
-    #
-    # @return [String]
-    def identify
-      "name"
-    end
-
     # 返回创建监控项时的克制默认值。
     #
     # @return [Hash]
@@ -35,10 +29,10 @@ class ZabbixManager
 
     # 使用主机和名称组成通用 CRUD 的查询边界。
     #
-    # @param data [Hash] Needs to include name and hostid to properly identify Items via Zabbix API
-    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
-    # @raise [TransportError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
-    # @return [Integer] Zabbix object id
+    # @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) }
@@ -59,7 +53,7 @@ class ZabbixManager
     # 按主机和稳定 key 查询唯一监控项。
     # @return [Hash, nil]
     def find_by_key(hostid:, key:)
-      result = for_host(hostid, keys: key, output: ["itemid", "key_", "name"])
+      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
@@ -68,25 +62,11 @@ class ZabbixManager
     # 按 hostid + key_ 幂等创建或更新监控项。
     # @return [Integer]
     def upsert_by_key(data)
-      attributes = validate_item!(data)
-
-      current = find_by_key(hostid: attributes[:hostid], key: attributes[:key_])
-      if current
-        itemid = current.fetch("itemid")
-        @client.api_request(
-          method: "item.update",
-          params: attributes.except(:hostid).merge(itemid: itemid)
-        )
-        itemid.to_i
-      else
-        create_attributes = default_options.merge(attributes)
-        validate_create_item!(create_attributes)
-        result = @client.api_request(method: "item.create", params: create_attributes)
-        result.fetch("itemids").first.to_i
-      end
+      apply_item(*plan_item(validate_item!(data)))
     end
 
     # 先校验整批数据，再按稳定 key 逐项幂等写入。
+    # @yieldparam effective [Array<Hash>] 合并已有配置或创建默认值后的有效属性；块失败时不写入
     # @return [Array<Integer>]
     def upsert_many(collection)
       items = Array(collection).map { |data| validate_item!(data) }
@@ -94,28 +74,40 @@ class ZabbixManager
       duplicate = identities.tally.find { |_identity, count| count > 1 }&.first
       raise Invalid, "duplicate hostid + key_ identity #{duplicate.join(":")}" if duplicate
 
-      items.map { |item| upsert_by_key(item) }
+      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
 
     # 批量启用或停用监控项。
     # @return [Array<Integer>]
     def set_status(hostid:, itemids:, enabled:)
-      ids = normalized_ids(itemids, "itemids")
+      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 } }
       )
-      Array(result.fetch("itemids")).map(&:to_i)
+      response_ids(result, expected: ids)
     end
 
     # 批量删除明确指定的监控项。
     # @return [Array<Integer>]
     def delete_many(hostid:, itemids:)
-      ids = normalized_ids(itemids, "itemids")
+      ids = normalized_ids(itemids)
       verify_host_ownership!(hostid, ids)
       result = @client.api_request(method: "item.delete", params: ids)
-      Array(result.fetch("itemids")).map(&:to_i)
+      response_ids(result, expected: ids)
     end
 
     # 返回主机中可能表示接口流量的已启用监控项。
@@ -127,7 +119,7 @@ class ZabbixManager
         params: {
           hostids: [hostid],
           monitored: true,
-          output: %w[itemid hostid name key_ snmp_oid value_type status units],
+          output: %w[itemid hostid name key_ type snmp_oid value_type status units],
           selectPreprocessing: "extend",
           sortfield: "name",
           sortorder: "ASC"
@@ -143,7 +135,7 @@ class ZabbixManager
       raise Invalid, "dns_name is required" if name.blank?
       raise Invalid, "dns_name contains unsupported item key delimiters" if name.match?(/[\[\],]/)
 
-      itemid = upsert_by_key(
+      upsert_by_key(
         hostid: hostid,
         interfaceid: interfaceid,
         name: "【DNS域名解析监控】#{name}",
@@ -154,72 +146,84 @@ class ZabbixManager
         history: "90d",
         timeout: "3s"
       )
-      log "Ensured DNS monitoring item for #{name}"
-      itemid
-    rescue StandardError => e
-      log "Failed to ensure DNS monitoring item: #{e.class}"
-      raise
     end
 
     private
 
-      # 规范化并校验幂等写入所需字段。
-      # @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?
+    # 创建必填字段必须在整批写入开始前校验。
+    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
 
-        attributes
+    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
 
-      # 校验 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?
+    # 规范化并校验幂等写入所需字段。
+    # @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?
 
-        type = Integer(attributes[:type])
-        raise Invalid, "unsupported item type #{type}" unless ITEM_TYPES.include?(type)
+      attributes
+    end
 
-        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
+    # 校验 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?
 
-        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
+      type = validate_item_type!(attributes[:type])
 
-        raise Invalid, "snmp_oid is required for an SNMP item" if attributes[:snmp_oid].blank?
-      rescue ArgumentError, TypeError
-        raise Invalid, "type must be a supported integer"
+      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
 
-      # 回查监控项归属，阻止共享高权限令牌跨主机修改。
-      def verify_host_ownership!(hostid, ids)
-        raise Invalid, "hostid is required" if hostid.blank?
+      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
 
-        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
+      raise Invalid, "snmp_oid is required for an SNMP item" if attributes[:snmp_oid].blank?
+    end
 
-      # 统一批量 ID 并拒绝空集合。
-      # @return [Array<String>]
-      # @api private
-      def normalized_ids(values, name)
-        ids = Array(values).filter_map { |value| value.to_s.strip.presence }.uniq
-        raise Invalid, "#{name} are required" if ids.empty?
+    def validate_item_type!(value)
+      type = integer_attribute(value, "type")
+      raise Invalid, "unsupported item type #{type}" unless ITEM_TYPES.include?(type)
 
-        ids
-      end
+      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,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Maintenance < Basic
+  # 原生维护期资源；时间段、目标主机和群组由调用方显式定义。
+  class Maintenance < Resource
     # 返回维护期对象对应的 Zabbix API 方法前缀。
     #
     # @return [String]

data/lib/zabbix_manager/classes/{mediatypes.rb → media_types.rb}

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

data/lib/zabbix_manager/classes/problems.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Problems < Basic
+  # 原生问题查询与事件确认；问题身份使用 eventid，确认动作属于远端写入。
+  class Problems < Resource
     # 返回问题对象对应的 Zabbix API 方法前缀。
     #
     # @return [String]
@@ -9,45 +10,18 @@ class ZabbixManager
       "problem"
     end
 
-    # 返回问题对象用于业务识别的字段名。
-    #
-    # @return [String]
-    def identify
-      "name"
-    end
-
-    # 返回问题对象的兼容 ID 字段名；问题对象本身没有独立的唯一标识。
+    # 使用触发问题的事件 ID 作为对象身份。
     #
     # @return [String]
     def key
-      "problemid"
+      "eventid"
     end
 
-    # 返回问题对象的复数兼容 ID 字段名。
+    # 返回事件 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] Call dump_by_id with parameters: #{data.inspect}"
-
-      @client.api_request(
-        method: "problem.get",
-        params: {
-          filter: {
-            identify.to_sym => data[identify.to_sym]
-          },
-          output: "extend"
-        }
-      )
+      "eventids"
     end
 
     # 获取问题及其确认、标签和抑制信息，并支持附加查询参数。
@@ -55,10 +29,8 @@ class ZabbixManager
     # @param data [Hash] 问题过滤条件及附加 API 参数
     # @raise [ApiError] Zabbix API 返回业务错误时抛出
     # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
-    # @return [Hash] 匹配的问题完整数据
+    # @return [Array<Hash>] 匹配的问题完整数据
     def get_full_data(data)
-      log "[DEBUG] Call get_full_data with parameters: #{data.inspect}"
-
       data = data.deep_symbolize_keys
       params = {
         recent: false,
@@ -92,15 +64,14 @@ class ZabbixManager
     # @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?
+      ids = normalized_ids(eventids)
 
-      @client.api_request(
+      result = @client.api_request(
         method: "event.acknowledge",
         params: { eventids: ids, action: action, message: message }.compact
       )
+      response_ids(result, expected: ids)
+      result
     end
-
-    alias ack_event acknowledge_events
   end
 end

data/lib/zabbix_manager/classes/proxies.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Proxies < Basic
+  # 原生代理资源；按服务器版本选择 name 或 host 作为名称字段。
+  class Proxies < Resource
     # 返回 Zabbix API 中代理对象的方法名前缀。
     #
     # @return [String] 代理对象的方法名前缀
@@ -13,18 +14,7 @@ class ZabbixManager
     #
     # @return [String] 代理对象的标识字段名
     def identify
-      "host"
-    end
-
-    # 通过 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
+      Gem::Version.new(@client.api_version) >= Gem::Version.new("7.0") ? "name" : "host"
     end
 
     # 检查当前凭证是否可读取指定代理。
@@ -58,9 +48,9 @@ class ZabbixManager
       result = @client.api_request(
         method: "proxy.get",
         params: {
-          output: %w[proxyid host],
+          output: ["proxyid", identify],
           filter: {
-            host: proxy
+            identify.to_sym => proxy
           }
         }
       )

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

data/lib/zabbix_manager/classes/roles.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Roles < Basic
+  # 角色查询与权限规则更新；权限内容由调用方定义，服务端负责权限校验。
+  class Roles < Resource
     # 返回 Zabbix API 中角色对象的方法名前缀。
     #
     # @return [String] 角色对象的方法名前缀
@@ -9,20 +10,6 @@ class ZabbixManager
       "role"
     end
 
-    # 返回角色对象的主键字段名。
-    #
-    # @return [String] 角色对象的主键字段名
-    def key
-      "roleid"
-    end
-
-    # 返回用于唯一识别角色的业务字段名。
-    #
-    # @return [String] 角色对象的业务标识字段名
-    def identify
-      "name"
-    end
-
     # 更新指定角色的权限规则。
     #
     # @param data [Hash] 包含 roleid 和 rules 的角色规则数据
@@ -34,6 +21,8 @@ class ZabbixManager
       raise Invalid, "roleid is required" if attributes[:roleid].blank?
       raise Invalid, "rules is required" if attributes[:rules].blank?
 
+      normalized_ids([attributes[:roleid]])
+
       result = @client.api_request(
         method: "role.update",
         params: {
@@ -41,24 +30,29 @@ class ZabbixManager
           rules: attributes[:rules]
         }
       )
-      result.fetch("roleids").first.to_i
+      response_id(result, expected: [attributes[:roleid]])
     end
 
     # 按角色 ID 获取角色详情及完整规则。
     #
-    # @param data [Hash] 包含 id 的查询参数
+    # @param data [Hash] 包含 roleid 的查询参数；旧 id 引用仍可使用，但不得矛盾
     # @raise [ApiError] Zabbix API 返回业务错误时抛出
     # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
     # @return [Array<Hash>] 匹配的角色详情
     def dump_by_id(data)
-      log "[DEBUG] Call dump_by_id with parameters: #{data.inspect}"
+      attributes = data.deep_symbolize_keys
+      if attributes.key?(:roleid) && attributes.key?(:id) &&
+         normalized_ids([attributes[:roleid]]) != normalized_ids([attributes[:id]])
+        raise Invalid, "roleid and id disagree"
+      end
 
+      id = normalized_ids([attributes.fetch(:roleid) { attributes[:id] }]).first
       @client.api_request(
         method: "role.get",
         params: {
           output: "extend",
           selectRules: "extend",
-          roleids: data[:id]
+          roleids: id
         }
       )
     end

data/lib/zabbix_manager/classes/screens.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Screens < Basic
+  # 旧版聚合图形的网格创建入口；目标服务器须提供 screen API。
+  class Screens < Resource
     # 以下资源类型取自 frontends/php/include/defines.inc.php。
     # SCREEN_RESOURCE_GRAPH => 0,
     # SCREEN_RESOURCE_SIMPLE_GRAPH => 1,
@@ -28,24 +29,6 @@ class ZabbixManager
       "screen"
     end
 
-    # 返回用于唯一识别聚合图形的业务字段名。
-    #
-    # @return [String] 聚合图形的业务标识字段名
-    def identify
-      "name"
-    end
-
-    # 删除指定聚合图形并返回首个已删除对象的 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
-
     # 按名称获取聚合图形，不存在时按图形 ID 网格化创建。
     #
     # @param data [Hash] 包含 screen_name、graphids 及可选布局参数
@@ -97,17 +80,15 @@ class ZabbixManager
 
     private
 
-      # 将横向格数转换为正整数，非法值直接拒绝。
-      #
-      # @param value [Object] 待校验的横向格数
-      # @return [Integer] 正整数横向格数
-      def positive_hsize(value)
-        size = Integer(value)
-        raise Invalid unless size.positive?
+    # 将横向格数转换为正整数，非法值直接拒绝。
+    #
+    # @param value [Object] 待校验的横向格数
+    # @return [Integer] 正整数横向格数
+    def positive_hsize(value)
+      size = integer_attribute(value, "hsize")
+      raise Invalid, "hsize must be a positive integer" unless size.positive?
 
-        size
-      rescue ArgumentError, TypeError
-        raise Invalid, "hsize must be a positive integer"
-      end
+      size
+    end
   end
 end

data/lib/zabbix_manager/classes/scripts.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Scripts < Basic
+  # 远端脚本执行与可用脚本查询；执行请求可能产生 API 之外的设备副作用。
+  class Scripts < Resource
     # 返回 Zabbix API 中脚本对象的方法名前缀。
     #
     # @return [String] 脚本对象的方法名前缀
@@ -9,13 +10,6 @@ class ZabbixManager
       "script"
     end
 
-    # 返回用于唯一识别脚本的业务字段名。
-    #
-    # @return [String] 脚本对象的业务标识字段名
-    def identify
-      "name"
-    end
-
     # 在指定主机上执行 Zabbix 脚本。
     #
     # 示例：

data/lib/zabbix_manager/classes/server.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 class ZabbixManager
+  # 已连接服务器的版本快照；复用 Client 初始化结果，不发起额外版本查询。
   class Server
     # 返回连接对应的 Zabbix API 版本。
     #