zabbix_manager 5.1.3 → 5.1.5

data/lib/zabbix_manager/classes/valuemaps.rb

@@ -2,35 +2,19 @@
 
 class ZabbixManager
   class ValueMaps < Basic
-    # The method name used for interacting with ValueMaps via Zabbix API
-    #
-    # @return [String]
+    # 用于通过 Zabbix API 与 ValueMaps 交互的方法名称
     def method_name
       "valuemap"
     end
 
-    # The key field name used for ValueMap objects via Zabbix API
-    #
-    # @return [String]
-    def key
-      "valuemapid"
-    end
-
-    # The id field name used for identifying specific ValueMap objects via Zabbix API
-    #
-    # @return [String]
+    # 用于通过 Zabbix API 识别特定 ValueMap 对象的 id 字段名称
     def identify
       "name"
     end
 
-    # Get or Create ValueMap object using Zabbix API
-    #
-    # @param data [Hash] Needs to include valuemapids [List] to properly identify ValueMaps via Zabbix API
-    # @raise [ZbxError] Error returned when there is a problem with the Zabbix API call.
-    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
-    # @return [Integer, TrueClass, FalseClass] Zabbix object id
+    # 通过 Zabbix API 获取或创建 ValueMap 对象
     def get_or_create(data)
-      log "[DEBUG] Call get_or_create with parameters: #{data.inspect}"
+      log "[DEBUG] 调用 get_or_create 方法，参数: #{data.inspect}"
 
       if (id = get_id(valuemapids: data[:valuemapids]))
         id
@@ -39,12 +23,7 @@ class ZabbixManager
       end
     end
 
-    # Create or update Item object using Zabbix API
-    #
-    # @param data [Hash] Needs to include valuemapids to properly identify ValueMaps via Zabbix API
-    # @raise [ZbxError] Error returned when there is a problem with the Zabbix API call.
-    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
-    # @return [Integer, TrueClass, FalseClass] Zabbix object id
+    # 通过 Zabbix API 创建或更新 Item 对象
     def create_or_update(data)
       valuemapid = get_id(name: data[:name])
       valuemapid ? update(data.merge(valuemapids: [:valuemapid])) : create(data)

data/lib/zabbix_manager/client.rb

@@ -4,46 +4,34 @@ require "net/http"
 require "json"
 require "openssl"
 
-# @author: WENWU YAN
-# @email: 968828@gmail.com
-# @date: 2023/3/25下午4:47
 class ZabbixManager
   class Client
-    # @param
-    # @return [Hash]
+    # 用于读取配置选项
     attr_reader :options
 
-    # @return [Integer]
+    # 生成一个随机的请求标识符
     def id
-      @id ||= rand 100_000
+      @id ||= rand 100_00
     end
 
-    # Returns the API version from the Zabbix Server
-    # @note 获取 zabbix api 版本
-    # @return [String, Hash]
+    # 获取 Zabbix API 版本
     def api_version
       api_request(method: "apiinfo.version", params: {})
     end
 
-    # ZabbixManager::Basic.log does not like @client.options[:debug]
-    # @note 是否启用 debug 模式
-    # @return [boolean]
+    # 是否启用 debug 模式
     def debug?
       !@options || @options[:debug]
     end
 
-    # Log messages to stdout when debugging
-    # @note debug 打印信息
-    # @param message [String]
+    # Debug 打印信息
     def log(message)
       puts message if debug?
     end
 
-    # Log in to the Zabbix Server and generate an auth token using the API
-    # @note 用户鉴权，登录成功即可获取令牌
-    # @raise [ZbxError] Error returned when there is a problem with the Zabbix API call.
-    # @return [Hash, String]
+    # 用户鉴权方法，登录成功即可获取令牌
     def auth
+      # 发起 "user.login" 方法的 API 请求, 并传递用户信息（用户名和密码）作为参数
       api_request(
         method: "user.login",
         params: {
@@ -53,25 +41,17 @@ class ZabbixManager
       )
     end
 
-    # Initializes a new Client object
-    # @see 实例化 HTTP 客户端，同时进行用户权限签证
-    # @param options [Hash]
-    # @option opts [String] :url The url of zabbix
-    # @example 'http://zabbix.com/api_jsonrpc.php'
-    # @see 'https://www.zabbix.com/documentation/current/en/manual/api/reference'
-    # @option opts [String] :user A user for api auth.(required)
-    # @option opts [String] :password A password for api auth.(required)
-    # @option opts [String] :http_user A user for basic auth.(optional)
-    # @option opts [String] :http_password A password for basic auth.(optional)
-    # @option opts [Integer] :timeout Set timeout for requests in seconds.(default: 60)
-    # @raise [ZbxError] Error raised when api_version not support.
-    # @return [ZabbixManager::Client]
+    # HTTP 客户端初始化方法，同时进行用户权限签证
     def initialize(options = {})
+      # 设置实例变量 @options 以便在整个类中访问
       @options = options
-      raise ZabbixManager::ZbxError, "Missing required argument: :url" unless @options.key?(:url)
-      raise ZabbixManager::ZbxError, "Missing required argument: :user" unless @options.key?(:user)
-      raise ZabbixManager::ZbxError, "Missing required argument: :password" unless @options.key?(:password)
 
+      # 检查必要的配置属性是否存在
+      raise ZbxError, "必须正确提供 :url 属性" unless @options.key?(:url)
+      raise ZbxError, "必须正确提供 :user 属性" unless @options.key?(:user)
+      raise ZbxError, "必须正确提供 :password 属性" unless @options.key?(:password)
+
+      # 配置代理信息
       if !ENV["http_proxy"].nil? && options[:no_proxy] != true
         @proxy_uri               = URI.parse(ENV["http_proxy"])
         @proxy_host              = @proxy_uri.host
@@ -79,24 +59,24 @@ class ZabbixManager
         @proxy_user, @proxy_pass = @proxy_uri.userinfo&.split(/:/) if @proxy_uri.userinfo
       end
 
-      if api_version.match?(/^7\.\d+\.\d+$/)
-        message = "Zabbix API version: #{api_version} is not supported by this version of zabbix_manager"
+      # 检查 Zabbix API 版本是否受支持
+      unless api_version.match?(/^[4-7]\.\d+\.\d+$/)
+        message = "Zabbix API版本：#{api_version} 不受此版本的 zabbix_manager 支持"
         if @options[:ignore_version]
           log "[WARNING] #{message}"
         else
-          raise ZabbixManager::ZbxError, message
+          raise ZbxError, message
         end
       end
 
+      # 进行用户鉴权，获取令牌
       @auth_hash = auth
       log "[DEBUG] Auth token: #{@auth_hash}"
     end
 
-    # Convert payload body to JSON string for the Zabbix API
-    # @note 将 ruby 数据结构转换为 json 字符串，除用户登录和获取API版本外均添加令牌
-    # @param body [Hash]
-    # @return [String]
+    # 定义一个方法，用于将 Ruby 数据结构转换为 JSON 字符串，并根据条件添加令牌
     def json_payload(body)
+      # 构建基本的 JSON 负载，包括方法名、参数、请求 ID 和 JSON-RPC 版本
       payload        = {
         method:  body[:method],
         params:  body[:params],
@@ -104,24 +84,22 @@ class ZabbixManager
         jsonrpc: "2.0"
       }
 
+      # 检查请求方法是否是 "apiinfo.version" 或 "user.login"，如果不是，则添加令牌信息
       payload[:auth] = @auth_hash unless body[:method] == "apiinfo.version" || body[:method] == "user.login"
 
+      # 将构建好的负载转换为 JSON 字符串并返回
       JSON(payload)
     end
 
-    # HTTP Request with the Zabbix API
-    # @note 实例化 Net::HTTP 对象，并发起 api 请求
-    # @param body [String]
-    # @raise [ZbxError] Error returned when there is a problem with the Zabbix API call.
-    # @raise [HttpError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
-    # @return [String]
+    # 实例化 Net::HTTP 对象，并发起 API 请求的方法
     def http_request(body)
       uri = URI.parse(@options[:url])
 
-      # set the time out the default (60) or to what the user passed
+      # 设置超时时间，默认为 60 秒
       timeout = @options[:timeout].nil? ? 60 : @options[:timeout]
       log "[DEBUG] Timeout for request set to #{timeout} seconds"
 
+      # 创建 Net::HTTP 对象，支持代理设置
       http =
         if @proxy_uri
           Net::HTTP.Proxy(@proxy_host, @proxy_port, @proxy_user, @proxy_pass).new(uri.host, uri.port)
@@ -129,64 +107,83 @@ class ZabbixManager
           Net::HTTP.new(uri.host, uri.port)
         end
 
+      # 配置 HTTPS 请求
       if uri.scheme == "https"
         http.use_ssl     = true
         http.verify_mode = OpenSSL::SSL::VERIFY_NONE
       end
 
+      # 配置请求超时时间
       http.open_timeout = timeout
       http.read_timeout = timeout
 
+      # 创建 POST 请求
       request = Net::HTTP::Post.new(uri.request_uri)
-      request.basic_auth @options[:http_user], @options[:http_password] if @options[:http_user]
+
+      # 添加基本身份验证信息（如果提供了用户名和密码）
+      request.basic_auth(@options[:http_user], @options[:http_password]) if @options[:http_user]
+
+      # 设置请求头的 Content-Type 为 application/json-rpc
       request.add_field("Content-Type", "application/json-rpc")
+
+      # 设置请求体为传入的 JSON 字符串
       request.body = body
       log "[DEBUG] HTTP request params: #{pretty_body(request.body)}"
 
+      # 发起请求并获取响应
       response = http.request(request)
+
+      # 检查响应状态码，如果不是 200，则抛出 HttpError 异常
       raise HttpError.new("HTTP Error: #{response.code} on #{@options[:url]}", response) unless response.code == "200"
 
       log "[DEBUG] HTTP response answer: #{pretty_body(response.body)}"
+
+      # 返回响应体
       response.body
     end
 
-    # Check the result returned by zabbix api is ok or not
-    # @note 发起 api 调用并对响应结果进行解析，如接口报错则抛出异常
-    # @@note 返回的数据为基于字符串索引，需要自行适配为符号索引
-    # @param body [String]
-    # @raise [ZbxError] Error returned when there is a problem with the Zabbix API call.
-    # @return [Hash, String]
+    # 对 API 响应结果进行解析的方法
     def _request(body)
+      # 发起 HTTP 请求并解析 JSON 格式的响应
       result = JSON.parse(http_request(body))
+
+      # 如果响应结果中包含错误信息，则抛出 ZbxError 异常
       if result["error"]
-        raise ZbxError.new(
-          "Server answer API error\n #{JSON.pretty_unparse(result["error"])}\n on request:\n #{pretty_body(body)}", result
-        )
+        # 构建错误消息，包括服务器返回的错误信息和请求的详细信息
+        msg = <<~MOJO
+
+          ---------------------------------------------------------------
+          Server answer API error: #{JSON.pretty_unparse(result["error"])}
+            on request: #{pretty_body(body)}
+          ---------------------------------------------------------------
+
+        MOJO
+
+        # 抛出自定义异常 ZbxError，并传递错误消息和完整的响应结果
+        raise ZbxError.new(msg, result)
       else
+        # 如果没有错误信息，则返回响应结果中的 "result" 部分
         result["result"]
       end
     end
 
-    # Pretty print json body
-    # @note 将 ruby 数据结构美化成 json 字符串后打印输出
-    # @param body [String]
-    # @return [Hash, String]
+    # 将 Ruby 数据结构美化成 JSON 字符串后打印输出的方法
     def pretty_body(body)
+      # 解析 JSON 字符串
       data = JSON.parse(body)
 
-      # If password is in body hide it
+      # 如果参数中包含密码字段，则将密码字段的值替换为 "***"
       if data["params"].is_a?(Hash) && data["params"].key?("password")
         data["params"]["password"] = "***"
       end
 
+      # 将美化后的数据转换为 JSON 字符串并返回
       JSON.pretty_unparse(data)
     end
 
-    # Execute Zabbix API requests and return response
-    # @note 通用的 api 调用发起方法
-    # @param body [Hash]
-    # @return [Hash, String]
+    # 通用的 API 调用发起方法
     def api_request(body)
+      # 调用之前定义的 json_payload 方法，将请求信息转换为 JSON 字符串
       _request json_payload(body)
     end
   end

data/lib/zabbix_manager/version.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  # @note find ./* -type f -exec sed -i 's/\[X\]/\[Y\]/g' {} +
-  VERSION = "5.1.3"
+  VERSION = "5.1.5"
 end

data/lib/zabbix_manager.rb

@@ -3,178 +3,165 @@
 require "zabbix_manager/version"
 require "zabbix_manager/client"
 
-# Dynamically load Basic Classes
+# 动态加载基础类
 Dir.glob(File.join(__dir__, "zabbix_manager/basic", "**", "*.rb")).sort.each do |basic_class|
   require basic_class
 end
 
-# Dynamically load Extend Classes
+# 动态加载扩展类
 Dir.glob(File.join(__dir__, "zabbix_manager/classes", "**", "*.rb")).sort.each do |extend_class|
   require extend_class
 end
 
 class ZabbixManager
-  # @return [ZabbixManager::Client]
   attr_reader :client
 
-  # Initializes a new ZabbixManager object
-  #
-  # @param options [Hash]
-  # @return [ZabbixManager]
+  # 初始化一个新的 ZabbixManager 对象
   def self.connect(options = {})
     new(options)
   end
 
-  # @note TODO
-  # @return [ZabbixManager]
+  # 获取当前 ZabbixManager 对象
   def self.current
-    @current ||= ZabbixManager.new
+    @current ||= new
   end
 
-  # Executes an API request directly using a custom query
-  # @note 通用的查询方法，自行提供 method 和 params
-  # @param data [Hash]
-  # @return [Hash, String]
+  # 直接使用自定义查询执行 API 请求
   def query(data)
     @client.api_request(method: data[:method], params: data[:params])
   end
 
-  # Invalidate current authentication token
-  # @note TODO
-  # @return [Boolean]
+  # 注销当前身份验证令牌
   def logout
     @client.logout
   end
 
-  # Initializes a new ZabbixManager object
-  # @note 实例化 ZabbixManager 对象，Client.new 进行参数检查
-  # @param options [Hash]
-  # @return [ZabbixManager::Client]
+  # 初始化一个新的 ZabbixManager 对象
   def initialize(options = {})
     @client = Client.new(options)
   end
 
-  # @return [ZabbixManager::Actions]
+  # 返回 ZabbixManager::Actions 对象
   def actions
     @actions ||= Actions.new(@client)
   end
 
-  # @return [ZabbixManager::Applications]
+  # 返回 ZabbixManager::Applications 对象
   def applications
     @applications ||= Applications.new(@client)
   end
 
-  # @return [ZabbixManager::Configurations]
+  # 返回 ZabbixManager::Configurations 对象
   def configurations
     @configurations ||= Configurations.new(@client)
   end
 
-  # @return [ZabbixManager::Events]
+  # 返回 ZabbixManager::Events 对象
   def events
     @events ||= Events.new(@client)
   end
 
-  # @return [ZabbixManager::Graphs]
+  # 返回 ZabbixManager::Graphs 对象
   def graphs
     @graphs ||= Graphs.new(@client)
   end
 
-  # @return [ZabbixManager::HostGroups]
+  # 返回 ZabbixManager::HostGroups 对象
   def hostgroups
     @hostgroups ||= HostGroups.new(@client)
   end
 
-  # @return [ZabbixManager::HostInterfaces]
+  # 返回 ZabbixManager::HostInterfaces 对象
   def hostinterfaces
     @hostinterfaces ||= HostInterfaces.new(@client)
   end
 
-  # @return [ZabbixManager::Hosts]
+  # 返回 ZabbixManager::Hosts 对象
   def hosts
     @hosts ||= Hosts.new(@client)
   end
 
-  # @return [ZabbixManager::HttpTests]
+  # 返回 ZabbixManager::HttpTests 对象
   def httptests
     @httptests ||= HttpTests.new(@client)
   end
 
-  # @return [ZabbixManager::Items]
+  # 返回 ZabbixManager::Items 对象
   def items
     @items ||= Items.new(@client)
   end
 
-  # @return [ZabbixManager::Maintenance]
+  # 返回 ZabbixManager::Maintenance 对象
   def maintenance
     @maintenance ||= Maintenance.new(@client)
   end
 
-  # @return [ZabbixManager::Mediatypes]
+  # 返回 ZabbixManager::Mediatypes 对象
   def mediatypes
     @mediatypes ||= Mediatypes.new(@client)
   end
 
-  # @return [ZabbixManager::Problems]
+  # 返回 ZabbixManager::Problems 对象
   def problems
     @problems ||= Problems.new(@client)
   end
 
-  # @return [ZabbixManager::Proxies]
+  # 返回 ZabbixManager::Proxies 对象
   def proxies
     @proxies ||= Proxies.new(@client)
   end
 
-  # @return [ZabbixManager::Roles]
+  # 返回 ZabbixManager::Roles 对象
   def roles
     @roles ||= Roles.new(@client)
   end
 
-  # @return [ZabbixManager::Screens]
+  # 返回 ZabbixManager::Screens 对象
   def screens
     @screens ||= Screens.new(@client)
   end
 
-  # @return [ZabbixManager::Scripts]
+  # 返回 ZabbixManager::Scripts 对象
   def scripts
     @scripts ||= Scripts.new(@client)
   end
 
-  # @return [ZabbixManager::Server]
+  # 返回 ZabbixManager::Server 对象
   def server
     @server ||= Server.new(@client)
   end
 
-  # @return [ZabbixManager::Templates]
+  # 返回 ZabbixManager::Templates 对象
   def templates
     @templates ||= Templates.new(@client)
   end
 
-  # @return [ZabbixManager::Triggers]
+  # 返回 ZabbixManager::Triggers 对象
   def triggers
     @triggers ||= Triggers.new(@client)
   end
 
-  # @return [ZabbixManager::Usergroups]
+  # 返回 ZabbixManager::Usergroups 对象
   def usergroups
     @usergroups ||= Usergroups.new(@client)
   end
 
-  # @return [ZabbixManager::Usermacros]
+  # 返回 ZabbixManager::Usermacros 对象
   def usermacros
     @usermacros ||= Usermacros.new(@client)
   end
 
-  # @return [ZabbixManager::Users]
+  # 返回 ZabbixManager::Users 对象
   def users
     @users ||= Users.new(@client)
   end
 
-  # @return [ZabbixManager::ValueMaps]
+  # 返回 ZabbixManager::ValueMaps 对象
   def valuemaps
     @valuemaps ||= ValueMaps.new(@client)
   end
 
-  # @return [ZabbixManager::Drules]
+  # 返回 ZabbixManager::Drules 对象
   def drules
     @drules ||= Drules.new(@client)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zabbix_manager
 version: !ruby/object:Gem::Version
-  version: 5.1.3
+  version: 5.1.5
 platform: ruby
 authors:
 - WENWU YAN
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-03-26 00:00:00.000000000 Z
+date: 2023-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -120,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
 summary: Common code for Zabbix API clients