zabbix_manager 5.1.4 → 5.1.6

data/lib/zabbix_manager/classes/graphs.rb

@@ -2,22 +2,32 @@
 
 class ZabbixManager
   class Graphs < Basic
-    # 用于通过 Zabbix API 与 Graphs 交互的方法名称
+    # 返回图形对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "graph"
     end
 
-    # 用于通过 Zabbix API 标识特定 Graph 对象的 id 字段名称
+    # 返回图形对象用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end
 
-    # 从 Zabbix API 获取完整/扩展的 Graph 数据
+    # 按名称搜索并获取图形的完整数据。
+    #
+    # @param data [Hash] 包含图形识别字段及其值的查询条件
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Hash] 匹配的图形完整数据
     def get_full_data(data)
-      log "[DEBUG] 使用参数调用 get_full_data: #{data.inspect}"
+      log "[DEBUG] Call get_full_data with parameters: #{data.inspect}"
 
-      get_raw(
-        {
+      @client.api_request(
+        method: "#{method_name}.get",
+        params: {
           search: {
             identify.to_sym => data[identify.to_sym]
           },
@@ -26,10 +36,16 @@ class ZabbixManager
       )
     end
 
-    # 从 Zabbix API 获取主机的 Graph ids
+    # 获取指定主机的图形 ID，并可按名称片段进一步过滤。
+    #
+    # @param data [Hash] 包含 host，且可包含 filter 的查询条件
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Array] 匹配的图形 ID 列表
     def get_ids_by_host(data)
-      result = get_raw(
-        {
+      result = @client.api_request(
+        method: "graph.get",
+        params: {
           filter: {
             host: data[:host]
           },
@@ -38,45 +54,36 @@ class ZabbixManager
       )
 
       result.filter_map do |graph|
-        num    = graph["graphid"]
-        name   = graph["name"]
+        num = graph["graphid"]
+        name = graph["name"]
         filter = data[:filter]
 
-        num if filter.nil? || /#{filter}/ =~ name
+        num if filter.nil? || name.include?(filter.to_s)
       end
     end
 
-    # 通过 Zabbix API 获取 Graph Item 对象
+    # 获取指定图形包含的图形监控项。
+    #
+    # @param data [Hash, String, Integer] 图形 ID
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Hash] 图形监控项数据
     def get_items(data)
       @client.api_request(
         method: "graphitem.get",
         params: {
           graphids: [data],
-          output:   "extend"
+          output: "extend"
         }
       )
     end
 
-    # 通过 Zabbix API 获取或创建 Graph 对象
-    def get_or_create(data)
-      log "[DEBUG] 使用参数调用 get_or_create: #{data.inspect}"
-
-      unless (id = get_id(name: data[:name], templateid: data[:templateid]))
-        id = create(data)
-      end
-
-      id
-    end
-
-    # 通过 Zabbix API 创建或更新 Graph 对象
-    def create_or_update(data)
-      graphid = get_id(name: data[:name], templateid: data[:templateid])
-      graphid ? _update(data.merge(graphid: graphid)) : create(data)
-    end
-
-    def _update(data)
-      data.delete(:name)
-      update(data)
+    # 生成由图形名称和所属模板构成的稳定查询条件。
+    # @param data [Hash] 包含 name 和 templateid 的图形属性
+    # @return [Hash] 图形唯一查询条件
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      { name: attributes.fetch(:name), templateid: attributes.fetch(:templateid) }
     end
   end
 end

data/lib/zabbix_manager/classes/hostgroups.rb

@@ -2,19 +2,69 @@
 
 class ZabbixManager
   class HostGroups < Basic
-    # 用于通过 Zabbix API 与 HostGroups 交互的方法名称
+    # 返回主机群组对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "hostgroup"
     end
 
-    # 用于通过 Zabbix API 标识特定 HostGroup 对象的 id 字段名称
+    # 返回主机群组用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end
 
-    # HostGroup 对象通过 Zabbix API 使用的 key 字段名称
+    # 返回主机群组的 Zabbix ID 字段名。
+    #
+    # @return [String]
     def key
       "groupid"
     end
+
+    # 批量解析主机群组名称并返回对应的群组 ID。
+    # @param data [Array<String>, String] 待查询的群组名称
+    # @return [Array<Hash>, nil] 群组 ID 列表，未命中时返回 nil
+    def get_hostgroup_ids(data)
+      names = normalized_names(data)
+      return nil if names.empty?
+
+      groups = @client.api_request(
+        method: "hostgroup.get",
+        params: {
+          output: %w[groupid name],
+          filter: { name: names }
+        }
+      )
+
+      groups.empty? ? nil : groups.map { |group| { groupid: group.fetch("groupid") } }
+    end
+
+    # 批量查询并创建缺失的主机群组，避免逐名称重复查询。
+    # @param data [Array<String>, String] 待确保存在的群组名称
+    # @return [Array<Hash>] 群组 ID 列表
+    def get_or_create_hostgroups(data)
+      names = normalized_names(data)
+      existing = @client.api_request(
+        method: "hostgroup.get",
+        params: { output: %w[groupid name], filter: { name: names } }
+      ).index_by { |group| group.fetch("name") }
+
+      names.map do |name|
+        group = existing[name]
+        next({ groupid: group.fetch("groupid") }) if group
+
+        result = @client.api_request(method: "hostgroup.create", params: { name: name })
+        { groupid: result.fetch("groupids").first }
+      end
+    end
+
+    # 清理、去空并去重主机群组名称。
+    # @param data [Array<String>, String] 原始群组名称
+    # @return [Array<String>] 规范化后的群组名称
+    private def normalized_names(data)
+      Array(data).filter_map { |name| name.to_s.strip.presence }.uniq
+    end
   end
 end

data/lib/zabbix_manager/classes/hostinterfaces.rb

@@ -1,29 +1,189 @@
 # frozen_string_literal: true
 
 class ZabbixManager
+  # 封装高频使用的 Zabbix 主机接口查询与幂等更新。
   class HostInterfaces < Basic
-    # 用于通过 Zabbix API 与 HostInterfaces 交互的方法名称
+    # 返回对应的 Zabbix API 模块名。
+    # @return [String]
     def method_name
       "hostinterface"
     end
 
-    # 用于通过 Zabbix API 标识特定 HostInterface 对象的 id 字段名称
-    def identify
-      "hostids"
+    # 返回接口对象的主键字段。
+    # @return [String]
+    def key
+      "interfaceid"
     end
 
-    # HostInterface 对象通过 Zabbix API 使用的 key 字段名称
-    def key
+    # 使用接口 ID 作为通用查询标识。
+    # @return [String]
+    def identify
       "interfaceid"
     end
 
-    # 通过 Zabbix API 基于提供的 hostid 获取 Zabbix interface 的 id
-    # @note 基于 hostid 查询关联的 Interfaceid
-    def get_interfaceid(hostid)
-      result = get_raw({ output: key, identify.to_sym => hostid })
+    # 查询指定主机的全部接口，可选择同时返回关联监控项。
+    # @return [Array<Hash>]
+    def for_host(hostid, select_items: nil)
+      raise Invalid, "hostid is required" if hostid.blank?
+
+      params = { hostids: hostid, output: "extend" }
+      params[:selectItems] = select_items if select_items
+      @client.api_request(method: "hostinterface.get", params: params)
+    end
+
+    # 规范化并校验接口定义，不执行远端查询或写入。
+    # @return [Array<Hash>]
+    def validate(interfaces)
+      desired = Array.wrap(interfaces).map { |interface| normalize_definition(interface) }
+      validate_definitions!(desired)
+      desired
+    end
+
+    # 校验 host.create 中全部接口的创建必填合同。
+    # @return [Array<Hash>]
+    def validate_for_create(interfaces)
+      validate(interfaces).each { |attributes| validate_create_definition!(attributes) }
+    end
 
-      # 如果查询结果不为空，且第一个元素不为空，则继续获取 {interfaceid} 并转换为整数
-      result&.[](0)&.[](key)&.to_i
+    # 幂等创建或更新一个主机的接口集合。
+    # @return [Array<Integer>]
+    def reconcile_for_host(hostid:, interfaces:)
+      @client.with_upsert_lock("host-interfaces:#{hostid}") do
+        plan = plan_for_host(hostid: hostid, interfaces: interfaces)
+        apply_plan(hostid: hostid, plan: plan)
+      end
     end
+
+    # 删除明确指定的主机接口；关联监控项由 Zabbix 按官方规则处理。
+    # @return [Array<Integer>]
+    def delete_many(hostid:, interfaceids:)
+      ids = Array(interfaceids).filter_map { |value| value.to_s.strip.presence }.uniq
+      raise Invalid, "interfaceids are required" if ids.empty?
+
+      owned_ids = for_host(hostid).map { |interface| interface.fetch("interfaceid").to_s }
+      foreign_ids = ids - owned_ids
+      raise Conflict, "interfaces do not belong to host #{hostid}: #{foreign_ids.join(", ")}" if foreign_ids.any?
+
+      result = @client.api_request(method: "hostinterface.delete", params: ids)
+      Array(result.fetch("interfaceids")).map(&:to_i)
+    end
+
+    private
+
+      # 预先校验并生成仅供当前对象执行的接口变更计划。
+      def plan_for_host(hostid:, interfaces:)
+        desired = validate(interfaces)
+        existing = for_host(hostid)
+        desired.map { |attributes| [attributes, matching_interface(existing, attributes)] }
+      end
+
+      # 执行内部生成的接口变更计划，避免调用方伪造跨主机接口 ID。
+      def apply_plan(hostid:, plan:)
+        plan.map do |attributes, current|
+          current ? update_interface(attributes, current) : create_interface(hostid, attributes)
+        end
+      end
+
+      # 把接口字段递归转换为统一符号键。
+      def normalize_definition(interface)
+        interface.deep_symbolize_keys
+      end
+
+      # 校验新接口的通用字段及 SNMP 条件字段。
+      def validate_create_definition!(attributes)
+        attributes[:ip] = "" unless attributes.key?(:ip)
+        attributes[:dns] = "" unless attributes.key?(:dns)
+        interface_identity(attributes)
+        validate_snmp_details!(attributes) if attributes[:type].to_i == 2
+      end
+
+      # 校验 SNMP 版本和 v1/v2c community 必填合同。
+      def validate_snmp_details!(attributes)
+        details = attributes[:details]&.deep_symbolize_keys
+        raise Invalid, "SNMP interface details are required" unless details
+
+        version = Integer(details[:version])
+        raise Invalid, "SNMP interface version must be 1, 2, or 3" unless [1, 2, 3].include?(version)
+        if [1, 2].include?(version) && details[:community].blank?
+          raise Invalid, "SNMP v1/v2 interface community is required"
+        end
+
+        attributes[:details] = details
+      rescue ArgumentError, TypeError
+        raise Invalid, "SNMP interface version must be 1, 2, or 3"
+      end
+
+      # 校验期望接口是否包含重复身份。
+      # @return [void]
+      # @api private
+      def validate_definitions!(interfaces)
+        identities = interfaces.map { |interface| interface_identity(interface) }
+        duplicate = identities.tally.find { |_identity, count| count > 1 }&.first
+        raise Invalid, "duplicate desired interface identity #{duplicate}" if duplicate
+      end
+
+      # 按显式 ID 或稳定端点身份匹配已有接口。
+      # @return [Hash, nil]
+      # @api private
+      def matching_interface(existing, attributes)
+        if attributes[:interfaceid]
+          match = existing.find { |item| item["interfaceid"].to_s == attributes[:interfaceid].to_s }
+          raise Invalid, "interfaceid #{attributes[:interfaceid]} does not belong to this host" unless match
+
+          return match
+        end
+
+        candidates = existing.select { |item| endpoint_identity(item) == endpoint_identity(attributes) }
+        raise Conflict, "interface identity is ambiguous; provide interfaceid" if candidates.length > 1
+
+        candidates.first
+      end
+
+      # 生成不依赖数组顺序的接口身份。
+      # @return [String]
+      # @api private
+      def interface_identity(attributes)
+        values = attributes.with_indifferent_access
+        return "id:#{values[:interfaceid]}" if values[:interfaceid].present?
+
+        endpoint_identity(values)
+      end
+
+      # 使用类型、端点和端口匹配接口，不把可变的 main 或远端 ID 作为端点身份。
+      def endpoint_identity(attributes)
+        values = attributes.with_indifferent_access
+
+        %i[type main useip port].each do |field|
+          raise Invalid, "interface #{field} is required" if values[field].blank?
+        end
+        endpoint_field = values[:useip].to_i == 1 ? :ip : :dns
+        raise Invalid, "interface #{endpoint_field} is required" if values[endpoint_field].blank?
+
+        "endpoint:#{values[:type]}:#{values[:useip]}:#{values[endpoint_field]}:#{values[:port]}"
+      end
+
+      # 更新已属于目标主机的接口。
+      # @return [Integer]
+      # @api private
+      def update_interface(attributes, current)
+        interfaceid = current.fetch("interfaceid")
+        @client.api_request(
+          method: "hostinterface.update",
+          params: attributes.except(:hostid).merge(interfaceid: interfaceid)
+        )
+        interfaceid.to_i
+      end
+
+      # 为目标主机创建缺失接口。
+      # @return [Integer]
+      # @api private
+      def create_interface(hostid, attributes)
+        validate_create_definition!(attributes)
+        result = @client.api_request(
+          method: "hostinterface.create",
+          params: attributes.except(:interfaceid).merge(hostid: hostid)
+        )
+        result.fetch("interfaceids").first.to_i
+      end
   end
 end