zabbix_manager 5.1.6 → 6.0.1

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 版本。
     #

data/lib/zabbix_manager/classes/templates.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Templates < Basic
+  # 按模板技术名称解析 ID；返回引用供主机或模板关联操作使用。
+  class Templates < Resource
     # 返回 Zabbix API 中模板对象的方法名前缀。
     #
     # @return [String] 模板对象的方法名前缀
@@ -16,17 +17,6 @@ class ZabbixManager
       "host"
     end
 
-    # 删除指定模板并返回首个已删除模板的 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
-
     # 根据查询条件获取模板 ID 列表。
     #
     # @param data [Hash] Zabbix template.get 查询参数
@@ -39,59 +29,6 @@ class ZabbixManager
       end
     end
 
-    # 批量更新主机与模板的关联关系。
-    #
-    # @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 } },
-          templates: data[:templates_id].map { |t| { templateid: t } }
-        }
-      )
-      result.empty? ? false : true
-    end
-
-    # 批量为主机添加模板关联。
-    #
-    # @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 } },
-          templates: data[:templates_id].map { |t| { templateid: t } }
-        }
-      )
-      result.empty? ? false : true
-    end
-
-    # 批量移除主机的模板或主机组关联。
-    #
-    # @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],
-          templateids: data[:templates_id],
-          groupids: data[:group_id],
-          force: 1
-        }
-      )
-      result.empty? ? false : true
-    end
-
     # 按模板技术名称查询，并返回可直接用于主机或模板更新的引用对象。
     #
     # @param data [String, Array<String>] 一个或多个模板技术名称

data/lib/zabbix_manager/classes/triggers.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Triggers < Basic
+  # 触发器与依赖对账；受管身份使用标签，创建结果不明时只回读、不重放。
+  class Triggers < Resource
     DEFAULT_UNCERTAIN_WRITE_DELAYS = [0, 0.25, 1, 2].freeze
+    MAX_MANAGED_KEY_LENGTH = 200
     # 返回触发器对应的 Zabbix API 模块名。
     #
     # @return [String]
@@ -19,13 +21,11 @@ class ZabbixManager
 
     # 按触发器 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]
+    # @param data [Hash] 包含目标触发器 ID 字段及其值
+    # @raise [ApiError] Zabbix API 明确返回业务错误
+    # @raise [TransportError] HTTP 或网络请求失败，可能无法确认远端结果
+    # @return [Array<Hash>] 匹配的触发器及其关联对象
     def dump_by_id(data)
-      log "[DEBUG] Call dump_by_id with parameters: #{data.inspect}"
-
       @client.api_request(
         method: "trigger.get",
         params: {
@@ -43,7 +43,7 @@ class ZabbixManager
     # @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?
+      positive_id_attribute(hostid, "hostid")
 
       params = { hostids: hostid, output: output }
       params[:selectItems] = select_items if select_items
@@ -51,12 +51,13 @@ class ZabbixManager
       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)
+      response_objects(@client.api_request(method: "trigger.get", params: params))
     end
 
     # 按主机、描述和可选标签查询唯一触发器。
     # @return [Hash, nil]
     def find_for_host(hostid:, description:, tags: nil)
+      positive_id_attribute(hostid, "hostid")
       params = {
         hostids: hostid,
         filter: { description: description },
@@ -68,23 +69,33 @@ class ZabbixManager
         method: "trigger.get",
         params: params
       )
+      response_objects(result)
+      result.each { |trigger| response_identifier(trigger["triggerid"]) }
       raise Conflict, "multiple triggers match #{description} on host #{hostid}" if result.length > 1
 
       result.first
     end
 
     # 按管理标签查询唯一触发器。
+    # 展开表达式并读取依赖，供不确定写入后的完整期望状态核对。
+    # @param hostid [Integer, String] 触发器所属主机
+    # @param managed_key [String] 稳定、非秘密的受管身份
     # @return [Hash, nil]
     def find_managed_for_host(hostid:, managed_key:)
+      positive_id_attribute(hostid, "hostid")
       result = @client.api_request(
         method: "trigger.get",
         params: {
           hostids: hostid,
           tags: [{ tag: "zabbix_manager_id", value: managed_key, operator: 1 }],
-          output: ["triggerid", "description"],
+          output: "extend",
+          expandExpression: true,
+          selectDependencies: ["triggerid"],
           selectTags: "extend"
         }
       )
+      response_objects(result)
+      result.each { |trigger| response_identifier(trigger["triggerid"]) }
       raise Conflict, "multiple triggers use managed key #{managed_key}" if result.length > 1
 
       result.first
@@ -96,7 +107,12 @@ class ZabbixManager
       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)
+      result = response_objects(@client.api_request(method: "trigger.get", params: params))
+      result.each do |trigger|
+        unless response_identifier(trigger["triggerid"]).to_s == id
+          raise ProtocolError, "trigger.get returned an unexpected trigger ID"
+        end
+      end
       raise Conflict, "multiple triggers use triggerid #{id}" if result.length > 1
 
       result.first
@@ -106,7 +122,8 @@ class ZabbixManager
     # 可通过 Client 的 upsert_lock 接入跨进程锁。
     # @return [Integer]
     def upsert_for_host(data)
-      attributes = data.deep_symbolize_keys
+      attributes = data.deep_symbolize_keys.deep_dup
+      positive_id_attribute(attributes[:hostid], "hostid")
       lock_key = "trigger:#{attributes[:hostid]}:#{attributes[:managed_key] || attributes[:description]}"
       @client.with_upsert_lock(lock_key) { perform_upsert_for_host(attributes) }
     end
@@ -114,13 +131,14 @@ class ZabbixManager
     # 批量启用或停用触发器。
     # @return [Array<Integer>]
     def set_status(hostid:, triggerids:, enabled:)
+      validate_boolean!(enabled, "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)
+      response_ids(result, expected: ids)
     end
 
     # 批量删除明确指定的触发器。
@@ -129,13 +147,14 @@ class ZabbixManager
       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)
+      response_ids(result, expected: ids)
     end
 
     # 使用 trigger.update 完整替换一个触发器的依赖集合。
     # 传入空集合可清除依赖，返回被更新的触发器 ID。
     # @return [Integer]
     def replace_dependencies(hostid:, triggerid:, depends_on:, allow_cross_host_dependencies: false)
+      validate_boolean!(allow_cross_host_dependencies, "allow_cross_host_dependencies")
       id = normalized_ids([triggerid]).first
       dependency_ids = normalized_ids(depends_on, allow_empty: true)
       dependencies = dependency_ids.map { |value| { triggerid: value } }
@@ -143,13 +162,14 @@ class ZabbixManager
 
       verify_host_ownership!(hostid, [id])
       verify_host_ownership!(hostid, dependency_ids) if dependency_ids.any? && !allow_cross_host_dependencies
-      update_dependencies(id, dependencies)
+      @client.with_upsert_lock("trigger-dependencies:#{id}") { update_dependencies(id, dependencies) }
     end
 
     # 在保留现有依赖的前提下，为触发器追加一个或多个依赖。
     # 读改写过程按触发器 ID 加锁，跨进程可通过 Client 的 upsert_lock 协调。
     # @return [Integer]
     def add_dependencies(hostid:, triggerid:, depends_on:, allow_cross_host_dependencies: false)
+      validate_boolean!(allow_cross_host_dependencies, "allow_cross_host_dependencies")
       id = normalized_ids([triggerid]).first
       additions = normalized_ids(depends_on)
       raise Invalid, "trigger cannot depend on itself" if additions.include?(id)
@@ -177,26 +197,18 @@ class ZabbixManager
       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?
+      positive_id_attribute(hostid, "hostid")
       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
+        raise Invalid, "managed_key is too long" if managed_key.length > MAX_MANAGED_KEY_LENGTH
 
         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
         ownership_tags = Array(attributes[:tags]).select do |tag|
           tag[:tag].to_s == "managed_by" || tag["tag"].to_s == "managed_by"
@@ -204,50 +216,57 @@ class ZabbixManager
         current = find_for_host(hostid: hostid, description: attributes[:description], tags: ownership_tags)
       end
       if current
-        triggerid = current.fetch("triggerid")
+        triggerid = current["triggerid"]
+        response_identifier(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
+        result = @client.api_request(method: "trigger.update", params: attributes.merge(triggerid: triggerid))
+        response_id(result, expected: [triggerid])
       else
         create_managed_trigger(hostid, managed_key, attributes)
       end
     end
 
-    # 创建触发器；若响应丢失或并发冲突则按管理键回读收敛。
+    # 创建触发器；响应丢失时按管理键回读并核对期望状态。
     # @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
+      response_id(result)
     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
+      if managed_key.present?
+        current = recover_created_trigger(hostid: hostid, managed_key: managed_key, attributes: attributes)
+      end
+      return response_identifier(current["triggerid"]) 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
+              "#{original_error.message}"
     end
 
     # 对结果不确定的创建执行短暂退避回读，不重放写请求。
     # @return [Hash, nil]
     # @api private
-    private def recover_created_trigger(hostid:, managed_key:)
+    private def recover_created_trigger(hostid:, managed_key:, attributes:)
       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
+        if current && recovered_trigger_matches?(current, attributes)
+          response_identifier(current["triggerid"])
+          return current
+        end
       rescue ApiError, TransportError
         next
       end
       nil
     end
 
+    private def recovered_trigger_matches?(current, attributes)
+      desired_tags = Array(attributes[:tags]).map(&:deep_symbolize_keys)
+      actual_tags = Array(current["tags"]).map(&:deep_symbolize_keys)
+      attributes_match?(current, attributes.except(:tags)) && (desired_tags - actual_tags).empty?
+    end
+
     # 合并受管标签，同时保留调用方未覆盖的运维标签。
     # @return [Array<Hash>]
     # @api private
@@ -260,24 +279,14 @@ class ZabbixManager
       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?
+      positive_id_attribute(hostid, "hostid")
 
       result = @client.api_request(
         method: "trigger.get", params: { hostids: hostid, triggerids: ids, output: ["triggerid"] }
       )
-      owned_ids = result.map { |trigger| trigger.fetch("triggerid").to_s }
+      owned_ids = response_objects(result).map { |trigger| response_identifier(trigger["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
@@ -287,7 +296,7 @@ class ZabbixManager
       result = @client.api_request(
         method: "trigger.update", params: { triggerid: triggerid, dependencies: dependencies }
       )
-      result.fetch("triggerids").first.to_i
+      response_id(result, expected: [triggerid])
     end
   end
 end

data/lib/zabbix_manager/classes/user_groups.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 用户组成员和主机组权限替换；空数组表示清空，省略字段不参与更新。
+  class UserGroups < Resource
+    # @return [String] 原生用户组 API 前缀
+    def method_name
+      "usergroup"
+    end
+
+    # @return [String] 用户组 ID 字段
+    def key
+      "usrgrpid"
+    end
+
+    # 完整替换主机组权限；空数组明确清空，Zabbix 6.2 起保留独立的模板组权限。
+    # @param user_group_id [Integer, String] 目标用户组 ID
+    # @param host_group_ids [Array<Integer, String>] 完整期望主机组集合
+    # @param permission [Integer, String] 0 拒绝、2 只读、3 读写
+    # @return [Integer] 回执确认的用户组 ID
+    def replace_host_group_permissions(user_group_id:, host_group_ids:, permission: 2)
+      group_id = normalized_ids([user_group_id]).first
+      host_ids = collection_ids(host_group_ids, "host_group_ids", allow_empty: true)
+      access = integer_attribute(permission, "permission")
+      raise Invalid, "permission must be 0, 2, or 3" unless [0, 2, 3].include?(access)
+
+      rights_field = api_version >= Gem::Version.new("6.2") ? :hostgroup_rights : :rights
+      result = @client.api_request(
+        method: "usergroup.update",
+        params: { usrgrpid: group_id, rights_field => host_ids.map { |id| { id: id, permission: access } } }
+      )
+      response_id(result, expected: [group_id])
+    end
+
+    # 完整替换各用户组成员；空 user_ids 明确移除现有成员。
+    # @param user_group_ids [Array<Integer, String>] 待更新用户组 ID
+    # @param user_ids [Array<Integer, String>] 每组的完整期望用户集合
+    # @return [Array<Integer>] 回执确认的全部用户组 ID
+    def replace_users(user_group_ids:, user_ids:)
+      group_ids = collection_ids(user_group_ids, "user_group_ids")
+      users = collection_ids(user_ids, "user_ids", allow_empty: true)
+      membership = api_version >= Gem::Version.new("6.0") ?
+                     { users: users.map { |id| { userid: id } } } : { userids: users }
+      result = @client.api_request(
+        method: "usergroup.update",
+        params: group_ids.map { |id| membership.merge(usrgrpid: id) }
+      )
+      response_ids(result, expected: group_ids)
+    end
+
+    private
+
+    def api_version
+      Gem::Version.new(@client.api_version)
+    end
+
+    def collection_ids(values, name, allow_empty: false)
+      raise Invalid, "#{name} must be an Array" unless values.is_a?(Array)
+
+      normalized_ids(values, allow_empty: allow_empty)
+    end
+  end
+end

data/lib/zabbix_manager/classes/user_macros.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 主机宏由 hostid + macro 唯一定位，全局宏由 macro 唯一定位。
+  class UserMacros < Resource
+    # @return [String] 宏业务标识
+    def identify
+      "macro"
+    end
+
+    # @return [String] API 模块名
+    def method_name
+      "usermacro"
+    end
+
+    # @return [String] 主机宏 ID 字段
+    def key
+      "hostmacroid"
+    end
+
+    # @return [Hash] 主机宏复合身份
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      { macro: attributes.fetch(:macro), hostid: attributes.fetch(:hostid) }
+    end
+
+    # @return [Integer, nil] 唯一主机宏 ID
+    def get_id(data)
+      attributes = identity_filter(data)
+      unique_macro_id(get_full_data(attributes), "hostmacroid")
+    end
+
+    # @return [Integer, nil] 唯一全局宏 ID
+    def get_id_global(data)
+      attributes = data.deep_symbolize_keys
+      unique_macro_id(get_full_data_global(macro: attributes.fetch(:macro)), "globalmacroid")
+    end
+
+    # @return [Array<Hash>] 主机宏查询结果
+    def get_full_data(data)
+      attributes = data.deep_symbolize_keys
+      params = { filter: attributes.except(:hostid) }
+      params[:hostids] = attributes[:hostid] if attributes.key?(:hostid)
+      get_raw(params)
+    end
+
+    # @return [Array<Hash>] 全局宏查询结果
+    def get_full_data_global(data)
+      get_raw(globalmacro: true, filter: data.deep_symbolize_keys)
+    end
+
+    # @return [Integer, nil] 新建主机宏 ID
+    def create(data)
+      write_macro("create", data, "hostmacroids")
+    end
+
+    # @return [Integer, nil] 新建全局宏 ID
+    def create_global(data)
+      write_macro("createglobal", data, "globalmacroids")
+    end
+
+    # @return [Integer, nil] 删除主机宏 ID
+    def delete(ids)
+      requested = normalized_ids(ids)
+      write_macro("delete", requested, "hostmacroids", expected: requested)
+    end
+
+    # @return [Integer, nil] 删除全局宏 ID
+    def delete_global(ids)
+      requested = normalized_ids(ids)
+      write_macro("deleteglobal", requested, "globalmacroids", expected: requested)
+    end
+
+    # @return [Integer, nil] 更新主机宏 ID
+    def update(data)
+      write_macro("update", data, "hostmacroids", expected: [data.with_indifferent_access[:hostmacroid]])
+    end
+
+    # @return [Integer, nil] 更新全局宏 ID
+    def update_global(data)
+      write_macro("updateglobal", data, "globalmacroids", expected: [data.with_indifferent_access[:globalmacroid]])
+    end
+
+    # @return [Integer, nil] 已存在或新建全局宏 ID
+    def get_or_create_global(data)
+      get_id_global(data) || create_global(data)
+    end
+
+    # @return [Integer, nil] 新建或更新全局宏 ID
+    def create_or_update_global(data)
+      attributes = data.deep_symbolize_keys
+      id = get_id_global(attributes)
+      id ? update_global(attributes.merge(globalmacroid: id)) : create_global(attributes)
+    end
+
+    private
+
+    def unique_macro_id(result, id_field)
+      response_objects(result)
+      raise Conflict, "multiple macros match the requested identity" if result.length > 1
+
+      response_identifier(result.first[id_field], id_field) if result.first
+    end
+
+    def write_macro(operation, params, id_field, expected: nil)
+      normalized_ids(expected) if expected
+      result = @client.api_request(method: "usermacro.#{operation}", params: params)
+      expected ? response_ids(result, id_field, expected: expected).first : response_id(result, id_field)
+    end
+  end
+end

data/lib/zabbix_manager/classes/users.rb

@@ -1,71 +1,32 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Users < Basic
-    # 返回 Zabbix API 中用户对象的方法名前缀。
-    #
-    # @return [String] 用户对象的方法名前缀
+  # 用户资源与媒介配置替换；字段名称按服务器版本转换。
+  class Users < Resource
+    # @return [String] API 模块名
     def method_name
       "user"
     end
 
-    # 返回用户对象批量结果中的 ID 字段名。
-    #
-    # @return [String] 用户 ID 复数字段名
-    def keys
-      "userids"
-    end
-
-    # 返回用户对象的主键字段名。
-    #
-    # @return [String] 用户对象的主键字段名
-    def key
-      "userid"
-    end
-
-    # 返回用于唯一识别用户的业务字段名。
-    #
-    # @return [String] 用户对象的业务标识字段名
+    # @return [String] 用户名字段
     def identify
-      "alias"
+      Gem::Version.new(@client.api_version) >= Gem::Version.new("5.4") ? "username" : "alias"
     end
 
-    # 按指定动作批量更新用户媒介配置。
-    #
+    # 替换指定用户的完整媒介配置。
     # @param data [Hash] 包含 userids 和 media
-    # @param action [String] user API 的动作名
-    # @return [Integer, nil] 首个已更新用户的 ID
-    def medias_helper(data, action)
+    # @return [Integer, nil] 首个更新用户的 ID
+    def update_medias(data)
+      attributes = data.deep_symbolize_keys
+      ids = normalized_ids(attributes.fetch(:userids))
+      media_field = Gem::Version.new(@client.api_version) >= Gem::Version.new("5.4") ? :medias : :user_medias
       result = @client.api_request(
-        method: "user.#{action}",
-        params: data[:userids].map do |t|
-          {
-            userid: t,
-            user_medias: data[:media]
-          }
+        method: "user.update",
+        params: attributes.fetch(:userids).map do |userid|
+          { userid: userid, media_field => attributes.fetch(:media) }
         end
       )
-      result ? result["userids"][0].to_i : nil
-    end
-
-    # 为指定用户添加媒介配置，当前通过 user.update 完成。
-    #
-    # @param data [Hash] 包含 userids 和 media
-    # @raise [ApiError] Zabbix API 返回业务错误时抛出
-    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
-    # @return [Integer, nil] 首个已更新用户的 ID
-    def add_medias(data)
-      medias_helper(data, "update")
-    end
-
-    # 批量替换指定用户的媒介配置。
-    #
-    # @param data [Hash] 包含 userids 和 media
-    # @raise [ApiError] Zabbix API 返回业务错误时抛出
-    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
-    # @return [Integer, nil] 首个已更新用户的 ID
-    def update_medias(data)
-      medias_helper(data, "update")
+      response_ids(result, expected: ids).first
     end
   end
 end