zabbix_manager 5.1.6 → 6.0.1

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) }
@@ -47,87 +41,88 @@ class ZabbixManager
     # 查询主机监控项，可按稳定 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?
+      positive_id_attribute(hostid, "hostid")
 
       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)
+      response_objects(@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: ["itemid", "key_", "name"])
-      raise Conflict, "multiple items use key #{key} on host #{hostid}" if result.length > 1
-
-      result.first
+      result = for_host(hostid, keys: key, output: "extend", select_preprocessing: "extend")
+      index_items(result, hostid, [key])[key]
     end
 
     # 按 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) }
-      identities = items.map { |item| [item[:hostid].to_s, item[:key_].to_s] }
+      identities = items.map { |item| [positive_id_attribute(item[:hostid], "hostid").to_s, item[:key_]] }
       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) }
+      existing = batch_items(items)
+      plans = items.map do |item|
+        identity = [positive_id_attribute(item[:hostid], "hostid").to_s, item[:key_]]
+        plan_item(item, existing[identity])
+      end
+      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
 
     # 返回主机中可能表示接口流量的已启用监控项。
     # 方向和接口精确匹配由 Monitoring 业务层负责。
     # @return [Array<Hash>]
     def monitored_traffic_candidates(hostid)
+      positive_id_attribute(hostid, "hostid")
       @client.api_request(
         method: "item.get",
         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 +138,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 +149,124 @@ 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?
+    # 每个主机只读取一次期望 key 集合，全部发现和校验完成后才开始写入。
+    def batch_items(items)
+      groups = items.group_by { |item| positive_id_attribute(item[:hostid], "hostid").to_s }
+      ids = {}
+      groups.each_with_object({}) do |(owner, definitions), result|
+        hostid = definitions.first[:hostid]
+        keys = definitions.map { |item| item[:key_] }
+        rows = for_host(hostid, keys: keys, select_preprocessing: "extend")
+        index_items(rows, hostid, keys).each do |key, row|
+          id = response_identifier(row["itemid"])
+          raise ProtocolError, "item.get returned duplicate item IDs across hosts" if ids.key?(id)
 
-        attributes
+          ids[id] = true
+          result[[owner, key]] = row
+        end
       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?
-
-        type = Integer(attributes[:type])
-        raise Invalid, "unsupported item type #{type}" unless ITEM_TYPES.include?(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}"
+    # 不信任服务端过滤器：返回项必须位于所请求的主机和 key 集合中。
+    def index_items(rows, hostid, keys)
+      owner = positive_id_attribute(hostid, "hostid")
+      requested = keys.to_h { |key| [key, true] }
+      ids = {}
+      response_objects(rows).each_with_object({}) do |row, result|
+        id = response_identifier(row["itemid"])
+        unless response_identifier(row["hostid"], "hostid") == owner && requested.key?(row["key_"])
+          raise ProtocolError, "item.get returned an item outside the requested host and keys"
         end
+        raise Conflict, "multiple items use the same key on host #{hostid}" if result.key?(row["key_"])
+        raise ProtocolError, "item.get returned duplicate item IDs" if ids.key?(id)
 
-        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
+        ids[id] = true
+        result[row["key_"]] = row
+      end
+    end
 
-        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"
+    # 创建必填字段必须在整批写入开始前校验。
+    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 verify_host_ownership!(hostid, ids)
-        raise Invalid, "hostid is required" if hostid.blank?
+    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)
+      raise Invalid, "item must be a hash" unless data.is_a?(Hash)
 
-        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?
+      attributes = data.deep_symbolize_keys.deep_dup
+      positive_id_attribute(attributes[:hostid], "hostid")
+      %i[key_ name].each do |field|
+        unless attributes[field].is_a?(String) && attributes[field].present?
+          raise Invalid, "#{field} must be a non-empty string"
+        end
       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?
+      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?
 
-        ids
+      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)
+      positive_id_attribute(hostid, "hostid")
+
+      result = @client.api_request(
+        method: "item.get", params: { hostids: hostid, itemids: ids, output: ["itemid"] }
+      )
+      owned_ids = response_objects(result).map { |item| response_identifier(item["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,12 +48,14 @@ class ZabbixManager
       result = @client.api_request(
         method: "proxy.get",
         params: {
-          output: %w[proxyid host],
+          output: ["proxyid", identify],
           filter: {
-            host: proxy
+            identify.to_sym => proxy
           }
         }
       )
+      result = response_objects(result)
+      result.each { |proxy_data| response_identifier(proxy_data["proxyid"]) }
       raise Conflict, "proxy lookup is ambiguous for #{proxy}" if result.length > 1
 
       result.first&.fetch("proxyid", nil)

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