zabbix_manager 5.1.4 → 5.1.6

data/lib/zabbix_manager/basic/basic_logic.rb

@@ -2,78 +2,126 @@
 
 class ZabbixManager
   class Basic
-    # 使用 API 新增 Zabbix 监控对象（使用默认值）
+    # 合并默认选项后通过 Zabbix API 创建对象。
+    #
+    # @param data [Hash] 待创建的对象属性
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Integer] 创建单个对象时返回对象 ID
+    # @return [Boolean] 创建多个对象时返回操作结果
     def create(data)
-      log "[DEBUG] 调用 #{method_name}.create，参数: #{data.inspect}"
+      log "[DEBUG] Call create with parameters: #{data.inspect}"
 
-      params = default_options.merge(data)
-      result = @client.api_request(method: "#{method_name}.create", params: params)
+      # 判断是否绑定默认选项并重新生成配置
+      data_with_default = default_options.empty? ? data : default_options.merge(data)
+      data_create       = [data_with_default]
+
+      # 调用实例方法
+      result = @client.api_request(method: "#{method_name}.create", params: data_create)
+      # 判断是否执行成功并返回结果
       parse_keys result
     end
 
-    # 使用 API 更新 Zabbix 监控对象
-    def update(data, force = false)
-      log "[DEBUG] 调用 #{method_name}.update，参数: #{data.inspect}"
+    # 通过 Zabbix API 删除对象。
+    #
+    # @param data [Hash] 包含待删除对象的 ID 字段和值
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Integer] 删除单个对象时返回对象 ID
+    # @return [Boolean] 删除多个对象时返回操作结果
+    def delete(data)
+      log "[DEBUG] Call delete with parameters: #{data.inspect}"
+
+      data_delete = [data]
+      result      = @client.api_request(method: "#{method_name}.delete", params: data_delete)
+      parse_keys result
+    end
 
+    # 按业务标识查找对象，存在则更新，否则创建。
+    #
+    # @param data [Hash] 包含对象业务标识及待写入属性
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Integer] 创建或更新后的对象 ID
+    # @return [Boolean] 批量操作时返回操作结果
+    def create_or_update(data)
+      log "[DEBUG] Call create_or_update with parameters: #{data.inspect}"
+
+      id = get_id(**identity_filter(data))
+      id ? update(data.merge(key.to_sym => id)) : create(data)
+    end
+
+    # 在属性发生变化或强制更新时通过 Zabbix API 更新对象。
+    #
+    # @param data [Hash] 包含对象 ID 及待更新属性
+    # @param force [Boolean] 属性一致时是否仍强制更新
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Integer] 更新后的对象 ID
+    # @return [Boolean] 批量操作时返回操作结果
+    def update(data, force = false)
+      log "[DEBUG] Call update with parameters: #{data.inspect}"
       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
+        dump = item.deep_symbolize_keys if item[key].to_i == data[key.to_sym].to_i
       end
       if hash_equals?(dump, data) && !force
-        log "[DEBUG] 系统以有数据 #{dump} 和 待更新的数据 #{data} 相同，跳过本次更新"
+        log "[DEBUG] Equal keys #{dump} and #{data}, skip update"
         data[key.to_sym].to_i
       else
-        result = @client.api_request(method: "#{method_name}.update", params: data)
+        data_update = [data]
+        result      = @client.api_request(method: "#{method_name}.update", params: data_update)
         parse_keys result
       end
     end
 
-    # 使用 API 删除 Zabbix 监控对象
-    def delete(data)
-      log "[DEBUG] 调用 #{method_name}.delete，参数: #{data.inspect}"
-
-      result = @client.api_request(method: "#{method_name}.delete", params: [data].flatten)
-      parse_keys result
-    end
-
-    # 使用 API 获取或创建 Zabbix 监控对象
-    def get_or_create(data)
-      log "[DEBUG] 调用 #{method_name}.get_or_create，参数: #{data.inspect}"
-
-      if (id = get_id(identify.to_sym => data[identify.to_sym]))
-        id
-      else
-        create(data)
-      end
-    end
-
-    # 使用 API 批量获取或创建 Zabbix 监控对象
-    def get_or_create_keys(data)
-      log "[DEBUG] 调用 #{method_name}.get_or_create_keys，参数: #{data.inspect}"
+    # 按业务标识从 Zabbix API 获取对象扩展数据。
+    #
+    # @param data [Hash] 包含对象业务标识字段及其值
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Hash] 对象扩展数据
+    def get_full_data(data)
+      log "[DEBUG] Call get_full_data with parameters: #{data.inspect}"
 
-      ids = []
-      [data].flatten.each do |item|
-        if (id = get_or_create(item))
-          ids << { key.to_sym => id }
-        end
-      end
-      ids
+      @client.api_request(
+        method: "#{method_name}.get",
+        params: {
+          filter: {
+            identify.to_sym => data[identify.to_sym]
+          },
+          output: "extend"
+        }
+      )
     end
 
-    # 使用 API 创建或更新 Zabbix 监控对象
-    def create_or_update(data)
-      log "[DEBUG] 调用 #{method_name}.create_or_update，参数: #{data.inspect}"
+    # 将调用方参数直接传给对应的 Zabbix get 方法。
+    #
+    # @param data [Hash] 原始查询参数
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Hash] API 返回数据
+    def get_raw(data)
+      log "[DEBUG] Call get_raw with parameters: #{data.inspect}"
 
-      id = get_id(identify.to_sym => data[identify.to_sym])
-      id ? update(data.merge(key.to_sym => id.to_s)) : create(data)
+      @client.api_request(
+        method: "#{method_name}.get",
+        params: data
+      )
     end
 
-    # 使用 API 基于 key 打印 Zabbix 监控对象详情
+    # 按对象 ID 字段从 Zabbix API 获取扩展数据。
+    #
+    # @param data [Hash] 包含对象 ID 字段及其值
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @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(
-        {
+      @client.api_request(
+        method: "#{method_name}.get",
+        params: {
           filter: {
             key.to_sym => data[key.to_sym]
           },
@@ -82,112 +130,108 @@ class ZabbixManager
       )
     end
 
-    # 使用 API 基于提供的数据查询 Zabbix 监控对象 id
+    # 获取当前资源的全部对象，并返回业务标识到 ID 的映射。
+    #
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Hash] 业务标识到对象 ID 的映射
+    def all
+      result = {}
+      @client.api_request(
+        method: "#{method_name}.get",
+        params: { output: "extend" }
+      ).each do |item|
+        result[item[identify]] = item[key]
+      end
+      result
+    end
+
+    # 按业务标识精确查询对象 ID，并拒绝歧义结果。
+    #
+    # @param data [Hash] 业务标识过滤条件
+    # @raise [ApiError] API 调用失败、缺少标识字段或结果不唯一时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Integer, nil] Zabbix 对象 ID，未找到时返回空值
     def get_id(data)
-      log "[DEBUG] 调用 #{method_name}.get_id，参数: #{data.inspect}"
+      log "[DEBUG] Call get_id with parameters: #{data.inspect}"
 
-      data = symbolize_keys(data) if data.key?(identify)
+      data = data.deep_symbolize_keys
+      # 缺少业务标识字段时立即终止查询
       name = data[identify.to_sym]
-      raise ZbxError, "在调用 get_id 时未提供 identify #{identify}" if name.nil?
+      raise Invalid, "#{identify} not supplied in call to get_id" if name.nil?
 
-      # 输出信息截取 key identify
-      result = get_raw(
-        {
+      result = @client.api_request(
+        method: "#{method_name}.get",
+        params: {
           filter: data,
           output: [key, identify]
         }
       )
+      matches = result.select { |item| item[identify].to_s == name.to_s }
+      raise Conflict, "multiple #{method_name} objects match #{identify}=#{name}" if matches.length > 1
 
-      result.find { |item| item[identify] == data[identify.to_sym] }&.[](key)&.to_i
-    end
-
-    # 使用 API 基于提供的数据查询 Zabbix 监控对象 ids
-    def get_ids(data)
-      log "[DEBUG] 调用 #{method_name}.get_ids，参数: #{data.inspect}"
-
-      ids = []
-      [data].flatten.each do |item|
-        if (id = get_id(item))
-          ids << id
-        end
-      end
-      ids
+      matches.first&.fetch(key, nil)&.to_i
     end
 
-    # 使用 API 基于提供的数据查询 Zabbix 监控对象 id
-    def get_key_ids(data)
-      log "[DEBUG] 调用 #{method_name}.get_key_ids，参数: #{data.inspect}"
+    # 按业务标识获取对象，不存在时创建。
+    #
+    # @param data [Hash] 包含对象业务标识及待创建属性
+    # @raise [ApiError] Zabbix API 调用失败时抛出
+    # @raise [TransportError] Zabbix 服务端返回非 200 状态时抛出
+    # @return [Integer] Zabbix 对象 ID
+    def get_or_create(data)
+      log "[DEBUG] Call get_or_create with parameters: #{data.inspect}"
 
-      ids = []
-      [data].flatten.each do |item|
-        if (id = get_id(item))
-          ids << { key.to_sym => id }
-        end
+      unless (id = get_id(**identity_filter(data)))
+        id = create(data)
       end
-      ids
-    end
-
-    # 使用 API 基于 name 查询 Zabbix 监控对象 id
-    def get_ids_by_identify(data)
-      log "[DEBUG] 调用 #{method_name}.get_ids_by_identify，参数: #{data.inspect}"
-
-      result = get_raw(
-        {
-          filter: { identify.to_sym => [data].flatten },
-          output: [key]
-        }
-      )
-      result.empty? ? nil : result.map { |i| i[key] }
-    end
-
-    # 使用 API 基于 name 查询 Zabbix 监控对象 id
-    def get_key_ids_by_identify(data)
-      log "[DEBUG] 调用 #{method_name}.get_key_ids_by_identify，参数: #{data.inspect}"
-
-      result = get_raw(
-        {
-          filter: { identify.to_sym => [data].flatten },
-          output: [key]
-        }
-      )
-      result.empty? ? nil : result.map { |i| { key.to_sym => i[key] } }
+      id
     end
 
-    # 使用 API 查询所有 Zabbix 监控对象的详细信息
-    def all
-      result = {}
-      get_raw({ output: "extend" }).each do |item|
-        result[item[identify]] = item[key]
-      end
-      result
+    # 提取通用获取或写入操作使用的远端业务标识。
+    #
+    # @param data [Hash] 对象属性
+    # @return [Hash] 业务标识过滤条件
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      { identify.to_sym => attributes.fetch(identify.to_sym) }
     end
 
-    # 使用 API 查询 Zabbix 监控对象的详细信息
-    def get_full_data(data)
-      log "[DEBUG] 调用 #{method_name}.get_full_data，参数: #{data.inspect}"
-
-      get_raw(
-        {
-          filter: {
-            identify.to_sym => data[identify.to_sym]
-          },
-          output: "extend"
-        }
+    # 使用原始参数直接创建 Zabbix 对象。
+    #
+    # @param data [Hash, Array] 原始创建参数
+    # @return [Object] API 返回结果
+    def create_raw(data)
+      log "[DEBUG] Call create_raw with parameters: #{data.inspect}"
+      # 请求创建数据
+      @client.api_request(
+        method: "#{method_name}.create",
+        params: data
       )
     end
 
-    # 使用 API 查询 Zabbix 监控对象的原始数据
-    def get_raw(data)
+    # 使用原始参数直接更新 Zabbix 对象。
+    #
+    # @param data [Hash, Array] 原始更新参数
+    # @return [Object] API 返回结果
+    def update_raw(data)
+      log "[DEBUG] Call update_raw with parameters: #{data.inspect}"
+      # 请求创建数据
       @client.api_request(
-        method: "#{method_name}.get",
+        method: "#{method_name}.update",
         params: data
       )
     end
 
-    # 使用 API 查询 Zabbix 监控对象的原始数据
-    def request_raw(method, data)
+    # 使用原始参数直接删除 Zabbix 对象。
+    #
+    # @param data [Hash, Array] 原始删除参数
+    # @return [Object] API 返回结果
+    def delete_raw(data)
+      log "[DEBUG] Call delete_raw with parameters: #{data.inspect}"
+      # 请求创建数据
       @client.api_request(
-        method: method,
+        method: "#{method_name}.delete",
         params: data
       )
     end

data/lib/zabbix_manager/classes/actions.rb

@@ -2,30 +2,40 @@
 
 class ZabbixManager
   class Actions < Basic
-    # 用于与 Zabbix API 交互的方法名称
+    # 返回操作对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "action"
     end
 
-    # 用于通过 Zabbix API 标识特定 Action 对象的 id 字段名称
+    # 返回操作对象用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end
 
-    # 从 API 获取完整/扩展的 Action 对象数据
+    # 获取操作及其执行、恢复、确认操作和过滤条件的完整数据。
+    #
+    # @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(
-        {
-          filter:                      {
+      @client.api_request(
+        method: "#{method_name}.get",
+        params: {
+          filter: {
             identify.to_sym => data[identify.to_sym]
           },
-          output:                      "extend",
-          selectOperations:            "extend",
-          selectRecoveryOperations:    "extend",
+          output: "extend",
+          selectOperations: "extend",
+          selectRecoveryOperations: "extend",
           selectAcknowledgeOperations: "extend",
-          selectFilter:                "extend"
+          selectFilter: "extend"
         }
       )
     end

data/lib/zabbix_manager/classes/applications.rb

@@ -2,31 +2,26 @@
 
 class ZabbixManager
   class Applications < Basic
-    # 用于通过 Zabbix API 与 Applications 交互的方法名称
+    # 返回应用集对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "application"
     end
 
-    # 用于通过 Zabbix API 标识特定 Application 对象的 id 字段名称
+    # 返回应用集对象用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end
 
-    # 通过 Zabbix API 获取或创建 Application 对象
-    def get_or_create(data)
-      log "[DEBUG] 调用 get_or_create，参数为：#{data.inspect}"
-
-      if (id = get_id(name: data[:name], hostid: data[:hostid]))
-        id
-      else
-        create(data)
-      end
-    end
-
-    # 通过 Zabbix API 创建或更新 Application 对象
-    def create_or_update(data)
-      applicationid = get_id(name: data[:name], hostid: data[:hostid])
-      applicationid ? update(data.merge(applicationid: applicationid)) : create(data)
+    # 生成由应用集名称和所属主机构成的稳定查询条件。
+    # @param data [Hash] 包含 name 和 hostid 的应用集属性
+    # @return [Hash] 应用集唯一查询条件
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
     end
   end
 end

data/lib/zabbix_manager/classes/configurations.rb

@@ -2,27 +2,42 @@
 
 class ZabbixManager
   class Configurations < Basic
-    # 用于标识返回结果是否为数组
+    # 标记配置接口使用数组形式处理 API 返回值。
+    # @return [Boolean] 始终返回 true
     def array_flag
       true
     end
 
-    # 用于通过 Zabbix API 与 Configurations 交互的方法名称
+    # 返回配置对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "configuration"
     end
 
-    # 用于通过 Zabbix API 标识特定 Configuration 对象的 id 字段名称
+    # 返回配置对象用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "host"
     end
 
-    # 使用 Zabbix API 导出配置数据
+    # 通过 Zabbix API 导出配置数据。
+    #
+    # @param data [Hash] 配置导出参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Hash] 配置导出结果
     def export(data)
       @client.api_request(method: "configuration.export", params: data)
     end
 
-    # 使用 Zabbix API 导入配置数据
+    # 通过 Zabbix API 导入配置数据。
+    #
+    # @param data [Hash] 配置导入参数及内容
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
+    # @return [Hash] 配置导入结果
     def import(data)
       @client.api_request(method: "configuration.import", params: data)
     end

data/lib/zabbix_manager/classes/drules.rb

@@ -2,40 +2,28 @@
 
 class ZabbixManager
   class Drules < Basic
-    # 用于通过 Zabbix API 与 Drules 交互的方法名称
+    # 返回网络发现规则对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "drule"
     end
 
-    # 用于通过 Zabbix API 标识特定 Drule 对象的 id 字段名称
+    # 返回网络发现规则用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end
 
-    # 创建 Drule 对象时使用的默认选项
+    # 返回创建网络发现规则时使用的默认周期和启用状态。
+    #
+    # @return [Hash] 网络发现规则默认属性
     def default_options
       {
-        name:    nil,
-        iprange: nil,
-        delay:   3600,
-        status:  0
+        delay: "1h",
+        status: 0
       }
     end
-
-    # 通过 Zabbix API 获取或创建 Drule 对象
-    def get_or_create(data)
-      log "[DEBUG] 调用 get_or_create，参数为：#{data.inspect}"
-
-      unless (id = get_id(name: data[:name]))
-        id = create(data)
-      end
-      id
-    end
-
-    # 通过 Zabbix API 创建或更新 Drule 对象
-    def create_or_update(data)
-      druleid = get_id(name: data[:name])
-      druleid ? update(data.merge(druleid: druleid)) : create(data)
-    end
   end
 end

data/lib/zabbix_manager/classes/errors.rb

@@ -1,39 +1,27 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  # BaseError 是 ZabbixManager 模块中处理异常的基类
-  class BaseError < RuntimeError
-    # 用于存储响应对象
-    attr_accessor :response
-    # 用于存储 Zabbix API 错误信息
-    attr_accessor :error
-    # 用于存储格式化后的错误消息
-    attr_accessor :error_message
+  # 表示调用方输入或配置无效。
+  class Invalid < ArgumentError; end
 
-    # 初始化异常对象
-    def initialize(message, response = nil)
+  # 表示 Zabbix JSON-RPC 返回的业务错误或无效响应。
+  class ApiError < StandardError
+    attr_reader :response
+
+    # 保存经过脱敏的远端响应，便于调用方诊断。
+    # @return [ApiError]
+    def initialize(message = nil, response = nil)
       super(message)
       @response = response
-      set_error! if @response
-    end
-
-    private
-
-    # 从响应中提取 Zabbix API 错误信息
-    def set_error!
-      @error = @response["error"]
-      @error_message = "#{@error["message"]}: #{@error["data"]}"
-    rescue StandardError
-      @error = nil
-      @error_message = nil
     end
   end
 
-  # ZbxError 是 ZabbixManager 模块中处理 Zabbix API 异常的类
-  class ZbxError < BaseError
-  end
+  # 表示资源不唯一、身份冲突或无法安全收敛。
+  class Conflict < ApiError; end
 
-  # HttpError 是 ZabbixManager 模块中处理 HTTP 异常的类
-  class HttpError < BaseError
-  end
+  # 表示 HTTP 状态或传输层失败。
+  class TransportError < StandardError; end
+
+  # 表示远端可能已完成写入，调用方不得自动重放。
+  class ResultUnknown < TransportError; end
 end

data/lib/zabbix_manager/classes/events.rb

@@ -2,12 +2,16 @@
 
 class ZabbixManager
   class Events < Basic
-    # 用于通过 Zabbix API 与 Events 交互的方法名称
+    # 返回事件对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "event"
     end
 
-    # 用于通过 Zabbix API 标识特定 Event 对象的 id 字段名称
+    # 返回事件对象用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end