zabbix_manager 5.1.4 → 5.1.6

data/lib/zabbix_manager/classes/templates.rb

@@ -2,74 +2,112 @@
 
 class ZabbixManager
   class Templates < Basic
-    # Zabbix API 中与模板交互的方法名称
+    # 返回 Zabbix API 中模板对象的方法名前缀。
+    #
+    # @return [String] 模板对象的方法名前缀
     def method_name
       "template"
     end
 
-    # 用于通过 Zabbix API 标识特定模板对象的 id 字段名称
+    # 返回用于唯一识别模板的业务字段名。
+    #
+    # @return [String] 模板对象的业务标识字段名
     def identify
       "host"
     end
 
-    # 通过 Zabbix API 删除模板对象
+    # 删除指定模板并返回首个已删除模板的 ID。
+    #
+    # @param data [Array] 要删除的 templateid 数组
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer, nil] 已删除模板的 ID，无结果时返回 nil
     def delete(data)
       result = @client.api_request(method: "template.delete", params: [data])
       result.empty? ? nil : result["templateids"][0].to_i
     end
 
-    # 从 Zabbix API 获取主机的模板 id
+    # 根据查询条件获取模板 ID 列表。
+    #
+    # @param data [Hash] Zabbix template.get 查询参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Array<String>] 模板 ID 数组
     def get_ids_by_host(data)
       @client.api_request(method: "template.get", params: data).map do |tmpl|
         tmpl["templateid"]
       end
     end
 
-    # 通过 Zabbix API 获取或创建模板对象
-    # def get_or_create(data)
-    #   if (templateid = get_id(host: data[:host]))
-    #     templateid
-    #   else
-    #     create(data)
-    #   end
-    # end
-
-    # 通过 Zabbix API 批量更新主机的模板
+    # 批量更新主机与模板的关联关系。
+    #
+    # @param data [Hash] 包含 hosts_id 和 templates_id 数组
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Boolean] API 是否返回有效结果
     def mass_update(data)
       result = @client.api_request(
         method: "template.massUpdate",
         params: {
-          hosts:     data[:hosts_id].map { |t| { hostid: t } },
+          hosts: data[:hosts_id].map { |t| { hostid: t } },
           templates: data[:templates_id].map { |t| { templateid: t } }
         }
       )
       result.empty? ? false : true
     end
 
-    # 通过 Zabbix API 批量添加模板到主机
+    # 批量为主机添加模板关联。
+    #
+    # @param data [Hash] 包含 hosts_id 和 templates_id 数组
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Boolean] API 是否返回有效结果
     def mass_add(data)
       result = @client.api_request(
         method: "template.massAdd",
         params: {
-          hosts:     data[:hosts_id].map { |t| { hostid: t } },
+          hosts: data[:hosts_id].map { |t| { hostid: t } },
           templates: data[:templates_id].map { |t| { templateid: t } }
         }
       )
       result.empty? ? false : true
     end
 
-    # 通过 Zabbix API 批量从主机移除模板
+    # 批量移除主机的模板或主机组关联。
+    #
+    # @param data [Hash] 包含 hosts_id、templates_id 及可选 group_id
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Boolean] API 是否返回有效结果
     def mass_remove(data)
       result = @client.api_request(
         method: "template.massRemove",
         params: {
-          hostids:     data[:hosts_id],
+          hostids: data[:hosts_id],
           templateids: data[:templates_id],
-          groupids:    data[:group_id],
-          force:       1
+          groupids: data[:group_id],
+          force: 1
         }
       )
       result.empty? ? false : true
     end
+
+    # 按模板技术名称查询，并返回可直接用于主机或模板更新的引用对象。
+    #
+    # @param data [String, Array<String>] 一个或多个模板技术名称
+    # @return [Array<Hash>, nil] templateid 引用数组，未找到时返回 nil
+    def get_template_ids(data)
+      result = @client.api_request(
+        method: "template.get",
+        params: {
+          output: "extend",
+          filter: {
+            host: Array(data)
+          }
+        }
+      ).map { |template| { templateid: template.fetch("templateid") } }
+
+      result.presence
+    end
   end
 end

data/lib/zabbix_manager/classes/triggers.rb

@@ -2,105 +2,292 @@
 
 class ZabbixManager
   class Triggers < Basic
-    # 与 Zabbix API 交互的触发器方法名称
+    DEFAULT_UNCERTAIN_WRITE_DELAYS = [0, 0.25, 1, 2].freeze
+    # 返回触发器对应的 Zabbix API 模块名。
+    #
+    # @return [String]
     def method_name
       "trigger"
     end
 
-    # 用于通过 Zabbix API 标识特定触发器对象的 id 字段名称
+    # 使用描述作为通用 CRUD 的业务标识。
+    #
+    # @return [String]
     def identify
       "description"
     end
 
-    # 创建 Zabbix 触发器的默认选项
-    def default_options
-      {
-        recovery_mode: 1,
-        type:          0,
-        manual_close:  1
+    # 按触发器 ID 查询完整对象及关联项和函数。
+    #
+    # @param data [Hash] Should include desired object's key and value
+    # @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 [Hash]
+    def dump_by_id(data)
+      log "[DEBUG] Call dump_by_id with parameters: #{data.inspect}"
+
+      @client.api_request(
+        method: "trigger.get",
+        params: {
+          filter: {
+            key.to_sym => data[key.to_sym]
+          },
+          output: "extend",
+          selectItems: "extend",
+          selectFunctions: "extend"
+        }
+      )
+    end
+
+    # 查询主机触发器，并按需返回监控项、函数、依赖和标签。
+    # @return [Array<Hash>]
+    def for_host(hostid, output: "extend", select_items: nil, select_functions: nil,
+                 select_dependencies: nil, select_tags: nil, filter: nil)
+      raise Invalid, "hostid is required" if hostid.blank?
+
+      params = { hostids: hostid, output: output }
+      params[:selectItems] = select_items if select_items
+      params[:selectFunctions] = select_functions if select_functions
+      params[:selectDependencies] = select_dependencies if select_dependencies
+      params[:selectTags] = select_tags if select_tags
+      params[:filter] = filter if filter.present?
+      @client.api_request(method: "trigger.get", params: params)
+    end
+
+    # 按主机、描述和可选标签查询唯一触发器。
+    # @return [Hash, nil]
+    def find_for_host(hostid:, description:, tags: nil)
+      params = {
+        hostids: hostid,
+        filter: { description: description },
+        output: ["triggerid", "description"],
+        selectTags: "extend"
       }
+      params[:tags] = tags if tags.present?
+      result = @client.api_request(
+        method: "trigger.get",
+        params: params
+      )
+      raise Conflict, "multiple triggers match #{description} on host #{hostid}" if result.length > 1
+
+      result.first
     end
 
-    # 通过键值对从 Zabbix API 转储触发器对象数据
-    def dump_by_id(data)
-      log "[DEBUG] 调用 dump_by_id 方法，参数: #{data.inspect}"
-
-      get_raw(
-        {
-          triggerids:       data[keys.to_sym],
-          output:           "extend",
-          select_items:     "extend",
-          select_functions: "extend"
+    # 按管理标签查询唯一触发器。
+    # @return [Hash, nil]
+    def find_managed_for_host(hostid:, managed_key:)
+      result = @client.api_request(
+        method: "trigger.get",
+        params: {
+          hostids: hostid,
+          tags: [{ tag: "zabbix_manager_id", value: managed_key, operator: 1 }],
+          output: ["triggerid", "description"],
+          selectTags: "extend"
         }
       )
+      raise Conflict, "multiple triggers use managed key #{managed_key}" if result.length > 1
+
+      result.first
     end
 
-    # 安全地使用 Zabbix API 更新触发器对象，通过删除和替换触发器
-    def safe_update(data)
-      log "[DEBUG] 调用 safe_update 方法，参数: #{data.inspect}"
+    # 按触发器 ID 查询唯一对象，并可返回当前依赖集合。
+    # @return [Hash, nil]
+    def find_by_id(triggerid, select_dependencies: nil)
+      id = normalized_ids([triggerid]).first
+      params = { triggerids: id, output: "extend" }
+      params[:selectDependencies] = select_dependencies if select_dependencies
+      result = @client.api_request(method: "trigger.get", params: params)
+      raise Conflict, "multiple triggers use triggerid #{id}" if result.length > 1
 
-      dump    = {}
-      item_id = data[key.to_sym].to_i
-      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
-      end
+      result.first
+    end
 
-      expression        = "#{dump[:items][0][:key_]}.#{dump[:functions][0][:function]}(#{dump[:functions][0][:parameter]})"
-      dump[:expression] = dump[:expression].gsub(/\{(\d*)\}/, "{#{expression}}") # TODO: ugly regexp
-      dump.delete(:functions)
-      dump.delete(:items)
+    # 按稳定管理键串行创建或更新主机触发器。
+    # 可通过 Client 的 upsert_lock 接入跨进程锁。
+    # @return [Integer]
+    def upsert_for_host(data)
+      attributes = data.deep_symbolize_keys
+      lock_key = "trigger:#{attributes[:hostid]}:#{attributes[:managed_key] || attributes[:description]}"
+      @client.with_upsert_lock(lock_key) { perform_upsert_for_host(attributes) }
+    end
 
-      old_expression    = data[:expression]
-      data[:expression] = data[:expression].gsub(/\{.*:/, "{") # TODO: ugly regexp
-      data.delete(:templateid)
+    # 批量启用或停用触发器。
+    # @return [Array<Integer>]
+    def set_status(hostid:, triggerids:, enabled:)
+      ids = normalized_ids(triggerids)
+      verify_host_ownership!(hostid, ids)
+      result = @client.api_request(
+        method: "trigger.update",
+        params: ids.map { |triggerid| { triggerid: triggerid, status: enabled ? 0 : 1 } }
+      )
+      Array(result.fetch("triggerids")).map(&:to_i)
+    end
 
-      log "[DEBUG] expression: #{dump[:expression]}\n data: #{data[:expression]}"
+    # 批量删除明确指定的触发器。
+    # @return [Array<Integer>]
+    def delete_many(hostid:, triggerids:)
+      ids = normalized_ids(triggerids)
+      verify_host_ownership!(hostid, ids)
+      result = @client.api_request(method: "trigger.delete", params: ids)
+      Array(result.fetch("triggerids")).map(&:to_i)
+    end
 
-      if hash_equals?(dump, data)
-        log "[DEBUG] 键 #{dump} 和 #{data} 相等，跳过 safe_update"
-        item_id
-      else
-        data[:expression] = old_expression
-        # disable old trigger
-        log "[DEBUG] disable :" + @client.api_request(method: "#{method_name}.update",
-                                                      params: [{
-                                                                 triggerid: data[:triggerid], status: "1"
-                                                               }]).inspect
-        # create new trigger
-        data.delete(:triggerid)
-        create(data)
+    # 使用 trigger.update 完整替换一个触发器的依赖集合。
+    # 传入空集合可清除依赖，返回被更新的触发器 ID。
+    # @return [Integer]
+    def replace_dependencies(hostid:, triggerid:, depends_on:, allow_cross_host_dependencies: false)
+      id = normalized_ids([triggerid]).first
+      dependency_ids = normalized_ids(depends_on, allow_empty: true)
+      dependencies = dependency_ids.map { |value| { triggerid: value } }
+      raise Invalid, "trigger cannot depend on itself" if dependencies.any? { |item| item[:triggerid] == id }
+
+      verify_host_ownership!(hostid, [id])
+      verify_host_ownership!(hostid, dependency_ids) if dependency_ids.any? && !allow_cross_host_dependencies
+      update_dependencies(id, dependencies)
+    end
+
+    # 在保留现有依赖的前提下，为触发器追加一个或多个依赖。
+    # 读改写过程按触发器 ID 加锁，跨进程可通过 Client 的 upsert_lock 协调。
+    # @return [Integer]
+    def add_dependencies(hostid:, triggerid:, depends_on:, allow_cross_host_dependencies: false)
+      id = normalized_ids([triggerid]).first
+      additions = normalized_ids(depends_on)
+      raise Invalid, "trigger cannot depend on itself" if additions.include?(id)
+
+      verify_host_ownership!(hostid, [id])
+
+      @client.with_upsert_lock("trigger-dependencies:#{id}") do
+        current = find_by_id(id, select_dependencies: ["triggerid"])
+        raise ApiError, "Zabbix trigger #{id} was not found" unless current
+
+        existing = Array(current["dependencies"]).filter_map { |dependency| dependency["triggerid"] }
+        dependency_ids = (existing + additions).uniq
+        unless allow_cross_host_dependencies
+          verify_host_ownership!(hostid, dependency_ids)
+        end
+        dependencies = dependency_ids.map { |value| { triggerid: value } }
+        update_dependencies(id, dependencies)
       end
     end
 
-    # 通过 Zabbix API 获取或创建触发器对象
-    def get_or_create(data)
-      log "[DEBUG] 调用 #{method_name}.get_or_create 方法，参数: #{data.inspect}"
+    # 执行已加锁的触发器幂等写入。
+    # @return [Integer]
+    # @api private
+    private def perform_upsert_for_host(data)
+      attributes = data.deep_symbolize_keys
+      hostid = attributes.delete(:hostid)
+      managed_key = attributes.delete(:managed_key)&.to_s
+      legacy_identity_tags = attributes.delete(:legacy_identity_tags)
+      raise Invalid, "hostid is required" if hostid.blank?
+      raise Invalid, "description is required" if attributes[:description].blank?
+      raise Invalid, "expression is required" if attributes[:expression].blank?
+
+      if managed_key.present?
+        raise Invalid, "managed_key is too long" if managed_key.length > 200
 
-      if (id = get_id(description: data[:description], hostid: data[:hostid]))
-        id
+        attributes[:tags] = Array(attributes[:tags]).reject do |tag|
+          tag[:tag].to_s == "zabbix_manager_id" || tag["tag"].to_s == "zabbix_manager_id"
+        end
+        attributes[:tags] << { tag: "zabbix_manager_id", value: managed_key }
+        current = find_managed_for_host(hostid: hostid, managed_key: managed_key)
+        if current.nil? && legacy_identity_tags.present?
+          current = find_for_host(
+            hostid: hostid,
+            description: attributes[:description],
+            tags: legacy_identity_tags
+          )
+        end
       else
-        create(data)
+        ownership_tags = Array(attributes[:tags]).select do |tag|
+          tag[:tag].to_s == "managed_by" || tag["tag"].to_s == "managed_by"
+        end
+        current = find_for_host(hostid: hostid, description: attributes[:description], tags: ownership_tags)
+      end
+      if current
+        triggerid = current.fetch("triggerid")
+        attributes[:tags] = merge_tags(current["tags"], attributes[:tags]) if attributes[:tags]
+        @client.api_request(method: "trigger.update", params: attributes.merge(triggerid: triggerid))
+        triggerid.to_i
+      else
+        create_managed_trigger(hostid, managed_key, attributes)
       end
     end
 
-    # 使用 Zabbix API 创建或更新触发器对象
-    def create_or_update(data)
-      triggerid = get_id(description: data[:description], hostid: data[:hostid])
-      triggerid ? update(data.merge(triggerid: triggerid)) : create(data)
+    # 创建触发器；若响应丢失或并发冲突则按管理键回读收敛。
+    # @return [Integer]
+    # @api private
+    private def create_managed_trigger(hostid, managed_key, attributes)
+      result = @client.api_request(method: "trigger.create", params: attributes)
+      result.fetch("triggerids").first.to_i
+    rescue TransportError => original_error
+      current = recover_created_trigger(hostid: hostid, managed_key: managed_key) if managed_key.present?
+      return current.fetch("triggerid").to_i if current
+
+      raise ResultUnknown,
+            "trigger create result is unknown; inspect managed key #{managed_key.inspect} before retrying: " \
+            "#{original_error.message}"
+    rescue ApiError => original_error
+      current = recover_created_trigger(hostid: hostid, managed_key: managed_key) if managed_key.present?
+      return current.fetch("triggerid").to_i if current
+
+      raise original_error
     end
 
-    # 使用 Zabbix API 添加触发器依赖关系
-    def add_trigger_dependency(triggerid, depend_on_trigger_id)
-      log "[DEBUG] 调用 add_trigger_dependency 方法，参数: #{triggerid} #{depend_on_trigger_id}"
+    # 对结果不确定的创建执行短暂退避回读，不重放写请求。
+    # @return [Hash, nil]
+    # @api private
+    private def recover_created_trigger(hostid:, managed_key:)
+      delays = @client.options.fetch(:uncertain_write_delays, DEFAULT_UNCERTAIN_WRITE_DELAYS)
+      delays.each do |delay|
+        sleep(delay) if delay.positive?
+        current = find_managed_for_host(hostid: hostid, managed_key: managed_key)
+        return current if current
+      rescue ApiError, TransportError
+        next
+      end
+      nil
+    end
+
+    # 合并受管标签，同时保留调用方未覆盖的运维标签。
+    # @return [Array<Hash>]
+    # @api private
+    private def merge_tags(existing_tags, desired_tags)
+      desired = Array(desired_tags).map(&:deep_symbolize_keys)
+      desired_names = desired.map { |tag| tag.fetch(:tag).to_s }
+      retained = Array(existing_tags).map(&:deep_symbolize_keys).reject do |tag|
+        desired_names.include?(tag[:tag].to_s)
+      end
+      retained + desired
+    end
+
+    # 统一触发器 ID 并拒绝空集合。
+    # @return [Array<String>]
+    # @api private
+    private def normalized_ids(values, allow_empty: false)
+      ids = Array(values).filter_map { |value| value.to_s.strip.presence }.uniq
+      raise Invalid, "triggerids are required" if ids.empty? && !allow_empty
+
+      ids
+    end
+
+    # 回查触发器归属，阻止共享高权限令牌跨主机修改。
+    private def verify_host_ownership!(hostid, ids)
+      raise Invalid, "hostid is required" if hostid.blank?
 
       result = @client.api_request(
-        method: "trigger.adddependencies",
-        params: {
-          triggerid:          triggerid,
-          dependsOnTriggerid: depend_on_trigger_id
-        }
+        method: "trigger.get", params: { hostids: hostid, triggerids: ids, output: ["triggerid"] }
+      )
+      owned_ids = result.map { |trigger| trigger.fetch("triggerid").to_s }
+      foreign_ids = ids - owned_ids
+      raise Conflict, "triggers do not belong to host #{hostid}: #{foreign_ids.join(", ")}" if foreign_ids.any?
+    end
+
+    # 使用官方 trigger.update 完整写入依赖集合。
+    private def update_dependencies(triggerid, dependencies)
+      result = @client.api_request(
+        method: "trigger.update", params: { triggerid: triggerid, dependencies: dependencies }
       )
-      result.empty? ? nil : result["triggerids"]
+      result.fetch("triggerids").first.to_i
     end
   end
 end

data/lib/zabbix_manager/classes/usergroups.rb

@@ -2,22 +2,33 @@
 
 class ZabbixManager
   class Usergroups < Basic
-    # 用于通过 Zabbix API 与 Usergroups 交互的方法名称
+    # 返回 Zabbix API 中用户组对象的方法名前缀。
+    #
+    # @return [String] 用户组对象的方法名前缀
     def method_name
       "usergroup"
     end
 
-    # 用于 Usergroup 对象通过 Zabbix API 的键字段名称
+    # 返回用户组对象的主键字段名。
+    #
+    # @return [String] 用户组对象的主键字段名
     def key
       "usrgrpid"
     end
 
-    # 用于通过 Zabbix API 识别特定 Usergroup 对象的 id 字段名称
+    # 返回用于唯一识别用户组的业务字段名。
+    #
+    # @return [String] 用户组对象的业务标识字段名
     def identify
       "name"
     end
 
-    # 使用 Zabbix API 设置用户组的权限
+    # 更新用户组对主机组的访问权限。
+    #
+    # @param data [Hash] 包含 usrgrpid、hostgroupids 及可选 permission
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer, nil] 已更新用户组的 ID
     def permissions(data)
       permission = data[:permission] || 2
       result = @client.api_request(
@@ -30,12 +41,23 @@ class ZabbixManager
       result ? result["usrgrpids"][0].to_i : nil
     end
 
-    # 使用 Zabbix API 将用户添加到用户组
+    # 将用户加入用户组；兼容旧调用并委托给 update_users。
+    #
+    # @deprecated Zabbix 已移除 massAdd，请使用 update_users。
+    # @param data [Hash] 包含 userids 和 usrgrpids
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer, nil] 已更新用户组的 ID
     def add_user(data)
       update_users(data)
     end
 
-    # 使用 Zabbix API 更新用户组中的用户
+    # 批量替换指定用户组中的用户列表。
+    #
+    # @param data [Hash] 包含 userids 和 usrgrpids
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer, nil] 首个已更新用户组的 ID
     def update_users(data)
       user_groups = data[:usrgrpids].map do |t|
         {