zabbix_manager 5.1.5 → 6.0.0

data/lib/zabbix_manager/classes/triggers.rb

@@ -1,106 +1,290 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Triggers < Basic
-    # 与 Zabbix API 交互的触发器方法名称
+  # 触发器与依赖对账；受管身份使用标签，创建结果不明时只回读、不重放。
+  class Triggers < Resource
+    DEFAULT_UNCERTAIN_WRITE_DELAYS = [0, 0.25, 1, 2].freeze
+    MAX_MANAGED_KEY_LENGTH = 200
+    # 返回触发器对应的 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] 包含目标触发器 ID 字段及其值
+    # @raise [ApiError] Zabbix API 明确返回业务错误
+    # @raise [TransportError] HTTP 或网络请求失败，可能无法确认远端结果
+    # @return [Array<Hash>] 匹配的触发器及其关联对象
+    def dump_by_id(data)
+      @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"
+    # 按管理标签查询唯一触发器。
+    # 展开表达式并读取依赖，供不确定写入后的完整期望状态核对。
+    # @param hostid [Integer, String] 触发器所属主机
+    # @param managed_key [String] 稳定、非秘密的受管身份
+    # @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: "extend",
+          expandExpression: true,
+          selectDependencies: ["triggerid"],
+          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
+
+    # 按稳定管理键串行创建或更新主机触发器。
+    # 可通过 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
 
-      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)
+    # 批量启用或停用触发器。
+    # @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 } }
+      )
+      response_ids(result, expected: ids)
+    end
 
-      old_expression    = data[:expression]
-      data[:expression] = data[:expression].gsub(/\{.*:/, "{") # TODO: ugly regexp
-      data.delete(:templateid)
+    # 批量删除明确指定的触发器。
+    # @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)
+      response_ids(result, expected: ids)
+    end
 
-      log "[DEBUG] expression: #{dump[:expression]}\n data: #{data[:expression]}"
+    # 使用 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 } }
+      raise Invalid, "trigger cannot depend on itself" if dependencies.any? { |item| item[:triggerid] == id }
 
-      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)
+      verify_host_ownership!(hostid, [id])
+      verify_host_ownership!(hostid, dependency_ids) if dependency_ids.any? && !allow_cross_host_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)
+
+      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
+      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 > MAX_MANAGED_KEY_LENGTH
 
-      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)
       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["triggerid"]
+        response_identifier(triggerid)
+        attributes[:tags] = merge_tags(current["tags"], attributes[:tags]) if attributes[:tags]
+        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)
+      response_id(result)
+    rescue TransportError => original_error
+      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}"
+    end
+
+    # 对结果不确定的创建执行短暂退避回读，不重放写请求。
+    # @return [Hash, nil]
+    # @api private
+    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)
+        if current && recovered_trigger_matches?(current, attributes)
+          response_identifier(current["triggerid"])
+          return current
+        end
+      rescue ApiError, TransportError
+        next
       end
+      nil
     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)
+    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
+    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
 
-    # 使用 Zabbix API 添加触发器依赖关系
-    def add_trigger_dependency(triggerid, depend_on_trigger_id)
-      log "[DEBUG] 调用 add_trigger_dependency 方法，参数: #{triggerid} #{depend_on_trigger_id}"
+    # 回查触发器归属，阻止共享高权限令牌跨主机修改。
+    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"]
+      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,110 @@
+# 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)
+      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,39 +1,32 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Users < Basic
-    # 用于通过 Zabbix API 与 Users 交互的方法名称
+  # 用户资源与媒介配置替换；字段名称按服务器版本转换。
+  class Users < Resource
+    # @return [String] API 模块名
     def method_name
       "user"
     end
 
-    # 用于通过 Zabbix API 识别特定 User 对象的 id 字段名称
+    # @return [String] 用户名字段
     def identify
-      "alias"
+      Gem::Version.new(@client.api_version) >= Gem::Version.new("5.4") ? "username" : "alias"
     end
 
-    # 用于辅助处理添加或更新用户媒体信息的方法
-    def medias_helper(data, action)
+    # 替换指定用户的完整媒介配置。
+    # @param data [Hash] 包含 userids 和 media
+    # @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 |i|
-          {
-            userid: i,
-            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
-
-    # 通过 Zabbix API 为用户添加媒体信息
-    def add_medias(data)
-      medias_helper(data, "update")
-    end
-
-    # 通过 Zabbix API 更新用户媒体信息
-    def update_medias(data)
-      medias_helper(data, "update")
+      response_ids(result, expected: ids).first
     end
   end
 end

data/lib/zabbix_manager/classes/value_maps.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class ZabbixManager
+  # 原生值映射资源；所属范围与映射规则由调用方提供。
+  class ValueMaps < Resource
+    # 返回 Zabbix API 中值映射对象的方法名前缀。
+    #
+    # @return [String] 值映射对象的方法名前缀
+    def method_name
+      "valuemap"
+    end
+
+    # 返回用于唯一识别值映射的业务字段名。
+    #
+    # @return [String] 值映射对象的业务标识字段名
+    def identify
+      "name"
+    end
+
+    # 5.4 起值映射属于主机或模板；旧版仍按全局名称定位。
+    # @return [Hash] 带版本边界的精确身份条件
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      identity = super(attributes)
+      if host_scoped?
+        raise Invalid, "hostid is required for a host-scoped value map" unless attributes.key?(:hostid)
+
+        identity[:hostid] = normalized_ids([attributes[:hostid]]).first
+      end
+      identity
+    end
+
+    # 名称查询始终经过完整身份检查，避免跨主机合法重名造成误选。
+    # @return [Integer, nil] 唯一值映射 ID
+    def get_id(data)
+      super(identity_filter(data))
+    end
+
+    # hostid 用于身份查询和创建，不能用于移动已有值映射。
+    # @return [Integer] 已确认的值映射 ID
+    def update(data)
+      attributes = data.deep_symbolize_keys
+      super(host_scoped? ? attributes.except(:hostid) : attributes)
+    end
+
+    private
+
+    def host_scoped?
+      Gem::Version.new(@client.api_version) >= Gem::Version.new("5.4")
+    end
+  end
+end