zabbix_manager 5.1.5 → 6.0.0

data/lib/zabbix_manager/classes/roles.rb

@@ -1,52 +1,72 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Roles < Basic
-    # 与 Zabbix API 交互的角色方法名称
+  # 角色查询与权限规则更新；权限内容由调用方定义，服务端负责权限校验。
+  class Roles < Resource
+    # 返回 Zabbix API 中角色对象的方法名前缀。
+    #
+    # @return [String] 角色对象的方法名前缀
     def method_name
       "role"
     end
 
-    # 识别特定角色对象的 id 字段名称
-    def identify
-      "name"
-    end
-
-    # 使用 Zabbix API 为用户组设置权限
+    # 更新指定角色的权限规则。
+    #
+    # @param data [Hash] 包含 roleid 和 rules 的角色规则数据
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer] 已更新角色的 ID
     def rules(data)
-      rules  = data[:rules] || 2
+      attributes = data.deep_symbolize_keys
+      raise Invalid, "roleid is required" if attributes[:roleid].blank?
+      raise Invalid, "rules is required" if attributes[:rules].blank?
+
+      normalized_ids([attributes[:roleid]])
+
       result = @client.api_request(
         method: "role.update",
         params: {
-          roleid: data[:roleid],
-          rules:  data[:hostgroupids].map { |t| { permission: permission, id: t } }
+          roleid: attributes[:roleid],
+          rules: attributes[:rules]
         }
       )
-      result ? result["usrgrpids"][0].to_i : nil
+      response_id(result, expected: [attributes[:roleid]])
     end
 
-    # 使用 Zabbix API 将用户添加到用户组
-    def add_user(data)
-      update_users(data)
-    end
-
-    # 从 Zabbix API 中根据指定键和值获取角色对象的数据
+    # 按角色 ID 获取角色详情及完整规则。
+    #
+    # @param data [Hash] 包含 roleid 的查询参数；旧 id 引用仍可使用，但不得矛盾
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Array<Hash>] 匹配的角色详情
     def dump_by_id(data)
-      log "[DEBUG] 调用 dump_by_id 方法，参数: #{data.inspect}"
+      attributes = data.deep_symbolize_keys
+      if attributes.key?(:roleid) && attributes.key?(:id) &&
+         normalized_ids([attributes[:roleid]]) != normalized_ids([attributes[:id]])
+        raise Invalid, "roleid and id disagree"
+      end
 
-      get_raw(
-        {
-          output:      "extend",
+      id = normalized_ids([attributes.fetch(:roleid) { attributes[:id] }]).first
+      @client.api_request(
+        method: "role.get",
+        params: {
+          output: "extend",
           selectRules: "extend",
-          roleids:     data[:id]
+          roleids: id
         }
       )
     end
 
-    # 通过角色名称从 Zabbix API 获取角色 id
+    # 按角色名称查询所有匹配的角色 ID。
+    #
+    # @param data [Hash] 包含 name 的角色查询参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Array<String>] 匹配的角色 ID 数组
     def get_ids_by_name(data)
-      result = get_raw(
-        {
+      result = @client.api_request(
+        method: "role.get",
+        params: {
           filter: {
             name: data[:name]
           },
@@ -58,20 +78,5 @@ class ZabbixManager
         rule["roleid"]
       end
     end
-
-    # 使用 Zabbix API 更新用户角色中的用户
-    def update_users(data)
-      user_groups = data[:usrgrpids].map do |t|
-        {
-          usrgrpid: t,
-          userids:  data[:userids]
-        }
-      end
-      result      = @client.api_request(
-        method: "usergroup.update",
-        params: user_groups
-      )
-      result ? result["usrgrpids"][0].to_i : nil
-    end
   end
 end

data/lib/zabbix_manager/classes/screens.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Screens < Basic
-    # extracted from frontends/php/include/defines.inc.php
+  # 旧版聚合图形的网格创建入口；目标服务器须提供 screen API。
+  class Screens < Resource
+    # 以下资源类型取自 frontends/php/include/defines.inc.php。
     # SCREEN_RESOURCE_GRAPH => 0,
     # SCREEN_RESOURCE_SIMPLE_GRAPH => 1,
     # SCREEN_RESOURCE_MAP => 2,
@@ -21,45 +22,43 @@ class ZabbixManager
     # SCREEN_RESOURCE_SYSTEM_STATUS => 15,
     # SCREEN_RESOURCE_HOST_TRIGGERS => 16
 
-    # 与 Zabbix API 交互的屏幕方法名称
+    # 返回 Zabbix API 中聚合图形对象的方法名前缀。
+    #
+    # @return [String] 聚合图形对象的方法名前缀
     def method_name
       "screen"
     end
 
-    # 用于通过 Zabbix API 标识特定屏幕对象的 ID 字段名称
-    def identify
-      "name"
-    end
-
-    # 删除 Zabbix API 中的屏幕对象
-    def delete(data)
-      result = @client.api_request(method: "screen.delete", params: [data])
-      result.empty? ? nil : result["screenids"][0].to_i
-    end
-
-    # 使用 Zabbix API 为主机获取或创建屏幕对象
+    # 按名称获取聚合图形，不存在时按图形 ID 网格化创建。
+    #
+    # @param data [Hash] 包含 screen_name、graphids 及可选布局参数
+    # @raise [ApiError] Zabbix API 返回业务错误时抛出
+    # @raise [TransportError] Zabbix 服务返回非成功 HTTP 状态时抛出
+    # @return [Integer] 聚合图形 ID
     def get_or_create_for_host(data)
       screen_name = data[:screen_name]
-      graphids = data[:graphids]
-      screenitems = []
-      hsize = data[:hsize] || 3
+      graphids = Array(data[:graphids])
+      raise Invalid, "screen_name is required" if screen_name.blank?
+      raise Invalid, "graphids must contain at least one graph" if graphids.empty?
+
+      hsize = positive_hsize(data.fetch(:hsize, 3))
+
       valign = data[:valign] || 2
       halign = data[:halign] || 2
       rowspan = data[:rowspan] || 1
       colspan = data[:colspan] || 1
       height = data[:height] || 320
       width = data[:width] || 200
-      vsize = data[:vsize] || [1, (graphids.size / hsize).to_i].max
+      vsize = data[:vsize] || graphids.length.fdiv(hsize).ceil
       screenid = get_id(name: screen_name)
 
       unless screenid
-        # 创建屏幕
-        graphids.each_with_index do |graphid, index|
-          screenitems << {
+        screenitems = graphids.each_with_index.map do |graphid, index|
+          {
             resourcetype: 0,
             resourceid: graphid,
-            x: (index % hsize).to_i,
-            y: (index % graphids.size / hsize).to_i,
+            x: index % hsize,
+            y: index / hsize,
             valign: valign,
             halign: halign,
             rowspan: rowspan,
@@ -78,5 +77,18 @@ class ZabbixManager
       end
       screenid
     end
+
+    private
+
+    # 将横向格数转换为正整数，非法值直接拒绝。
+    #
+    # @param value [Object] 待校验的横向格数
+    # @return [Integer] 正整数横向格数
+    def positive_hsize(value)
+      size = integer_attribute(value, "hsize")
+      raise Invalid, "hsize must be a positive integer" unless size.positive?
+
+      size
+    end
   end
 end

data/lib/zabbix_manager/classes/scripts.rb

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Scripts < Basic
-    # 与 Zabbix API 交互的方法名称
+  # 远端脚本执行与可用脚本查询；执行请求可能产生 API 之外的设备副作用。
+  class Scripts < Resource
+    # 返回 Zabbix API 中脚本对象的方法名前缀。
+    #
+    # @return [String] 脚本对象的方法名前缀
     def method_name
       "script"
     end
 
-    # 用于通过 Zabbix API 标识特定脚本对象的 ID 字段名称
-    def identify
-      "name"
-    end
-
-    # 执行 Zabbix API 中特定主机上的脚本
+    # 在指定主机上执行 Zabbix 脚本。
     #
-    # 示例:
-    #   execute({ scriptid: '12', hostid: '32' })
+    # 示例：
+    #   execute({ scriptid: '12', hostid: '32 })
+    #
+    # @param data [Hash] 包含 scriptid 和 hostid 的执行参数
+    # @return [Hash] Zabbix API 返回的脚本执行结果
     def execute(data)
       @client.api_request(
         method: "script.execute",
@@ -26,8 +27,11 @@ class ZabbixManager
       )
     end
 
-    # 使用 Zabbix API 通过主机获取脚本
-    def get_scripts_by_host(data)
+    # 查询指定主机可用的脚本。
+    #
+    # @param data [Hash] Zabbix scripts.getscriptsbyhosts 查询参数
+    # @return [Array<Hash>] 主机可用脚本列表
+    def getscriptsbyhost(data)
       @client.api_request(method: "script.getscriptsbyhosts", params: data)
     end
   end

data/lib/zabbix_manager/classes/server.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 
 class ZabbixManager
+  # 已连接服务器的版本快照；复用 Client 初始化结果，不发起额外版本查询。
   class Server
+    # 返回连接对应的 Zabbix API 版本。
+    #
+    # @return [String] Zabbix API 版本号
     attr_reader :version
 
-    # 初始化一个新的 Server 对象，使用 ZabbixManager 客户端，并获取 Zabbix 服务器 API 版本
+    # 使用客户端初始化服务信息，并立即读取 Zabbix API 版本。
+    #
+    # @param client [ZabbixManager::Client] 已建立配置的 Zabbix 客户端
+    # @return [Server] 已初始化的服务信息对象
     def initialize(client)
       @client = client
       @version = @client.api_version

data/lib/zabbix_manager/classes/templates.rb

@@ -1,75 +1,50 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Templates < Basic
-    # Zabbix API 中与模板交互的方法名称
+  # 按模板技术名称解析 ID；返回引用供主机或模板关联操作使用。
+  class Templates < Resource
+    # 返回 Zabbix API 中模板对象的方法名前缀。
+    #
+    # @return [String] 模板对象的方法名前缀
     def method_name
       "template"
     end
 
-    # 用于通过 Zabbix API 标识特定模板对象的 id 字段名称
+    # 返回用于唯一识别模板的业务字段名。
+    #
+    # @return [String] 模板对象的业务标识字段名
     def identify
       "host"
     end
 
-    # 通过 Zabbix API 删除模板对象
-    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 批量更新主机的模板
-    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
-
-    # 通过 Zabbix API 批量添加模板到主机
-    def mass_add(data)
+    # 按模板技术名称查询，并返回可直接用于主机或模板更新的引用对象。
+    #
+    # @param data [String, Array<String>] 一个或多个模板技术名称
+    # @return [Array<Hash>, nil] templateid 引用数组，未找到时返回 nil
+    def get_template_ids(data)
       result = @client.api_request(
-        method: "template.massAdd",
+        method: "template.get",
         params: {
-          hosts:     data[:hosts_id].map { |t| { hostid: t } },
-          templates: data[:templates_id].map { |t| { templateid: t } }
+          output: "extend",
+          filter: {
+            host: Array(data)
+          }
         }
-      )
-      result.empty? ? false : true
-    end
+      ).map { |template| { templateid: template.fetch("templateid") } }
 
-    # 通过 Zabbix 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
+      result.presence
     end
   end
 end