.. _attribute:

****
属性
****

属性是从设备获取到的最基础数据。它是一个单一的动态数据指标，直接获取于设备，或者由另一个属性处理而得。

产品的属性会完全被应用它的设备继承。设备里继承自产品的属性，只有以下字段可以被编辑：\ **取数间隔**\ 、\ **描述**\ 、\ **标签**\ 。

设备上的属性有两种实现方式：

* 从产品继承：一般推荐通过本方式实现，以方便后期统一维护；
* 直接在设备上添加：仅当某一设备比较特殊，需要给它设置独有的属性、或者属性内有独有且不通用的配置要求时，才需要采用本方式。

.. contents::
    :local:

在产品或设备详情页内，点击\ **属性管理**\ 进入其属性的列表页，可对它的属性进行管理。

基础字段
========

属性拥有以下基础字段。

.. image:: /_static/images/doc/zh/user_guide/attribute/attribute_baseinfo.*

具体说明如下。

属性名称
--------

属性的显示名称，可以使用中文、英文等字符。

.. _attr_id:

属性标识符
----------

可以包含数字、大小写字母、-_.，更多特殊形式请见 :zabbix_manual:`Zabbix 官方文档 <config/items/item/key>`\ 。

标识符内可使用本产品 **变量** 的键，且键必须包含在\ ``{$}``\ 内；比如若变量的键为 PWD，则完整标识符可以为\ ``xx{$PWD}xxx``\ ，其中\ ``x``\ 可以是符合上述要求的任意字符。

.. note::
    在一个产品或设备下的所有属性中，标识符必须唯一。

.. _attr_type:

来源类型
--------

属性数据可能有多种获取方式，目前平台支持以下几种：

* :ref:`主动上报 <attr_active>`\ ；
* :ref:`被动上报 <attr_passive>`\ ；
* :ref:`根据单个属性预处理 <attr_single_source>`\ 。

.. _attr_active:

主动上报
^^^^^^^^

设备主动将数据上报给平台，这适用于任何主动将数据推送给平台的情况。

.. TODO 

具体开发逻辑请参照\ :ref:`开发指南-设备接入 <dev_index>`\ 。

.. _attr_passive:

被动上报\ |专业版|
^^^^^^^^^^^^^^^^^^

平台发起问询后，设备被动将数据上报给平台。此时需要配置字段\ **取数间隔**\ ，平台发起取数请求的周期将以此为准。

.. TODO 

具体开发逻辑请参照\ :ref:`开发指南-设备接入 <dev_index>`\ 。

.. _attr_single_source:

根据单个属性预处理
^^^^^^^^^^^^^^^^^^

有些设备提供的一条信息内包含着多个应分给不同属性的数据，此时就可以使用\ ``根据单个属性预处理``\ 来处理。

需要同时配置字段\ **来源属性**\ 和\ **数据预处理**\ 。

每当\ **来源属性**\ 里的属性收到数据，平台会自动根据本属性内\ **数据预处理**\ 定义的流程来处理数据，处理后的结果内容将作为本属性的数据最终保存入数据库。

.. note::
    来源类型为\ ``根据单个属性预处理``\ 的属性，最多可以嵌套3层。比如\ ``A属性``\ 、\ ``B属性``\ 、\ ``C属性``\ 的\ **来源类型**\ 都是\ ``根据单个属性预处理``\  ，且\ ``C属性``\ 的\ **来源属性**\ 是\ ``B属性``\ ，\ ``B属性``\ 的\ **来源属性**\ 是\ ``A属性``\ ，则\ ``C属性``\ 不能再作为任意属性的\ **来源属性**\ 。

.. _data_type:

数据类型
--------

属性的数据类型，包括\ **整数**\ 、\ **小数**\ 、\ **字符**\ 、\ **文本**\ 。

* \ **整数**\ ：64位无符号整数。
* \ **小数**\ ：64位浮点数。
* \ **字符**\ ：短文本，不超过255字节。
* \ **文本**\ ：长文本，不超过65536字节。

更详细的介绍请见 :zabbix_manual:`Zabbix 官方文档 <config/items/item#text_data_limits>`\ 。

.. _preprocessing:

数据预处理
==========

数据预处理可以对接收的的原始数据进行多步处理，处理后的值才最终保存入库。

单个属性的预处理，按照预处理里定义的步骤顺序来执行。预处理的计算工作，由 Zabbix Server 或代理执行。

.. note::
    * 在预处理的步骤都执行完后，平台会自动附加一步，以将计算得到的数据转换为属性里定义的\ **数据类型**\ 。
    * 在预处理的任何一步（包括上面提到的平台自动附加的步骤）里处理失败，则属性的状态都会变为\ ``不受支持``\ 。

预处理支持的方法
----------------

文本
^^^^

.. csv-table::
    :header: "方法名称", "描述"
    :widths: 20, 80

    "Replace", "搜寻所有符合特定字符串的内容并用另一个字符串来替代。匹配失败则属性的状态会变为\ ``不受支持``\ 。
    
    参数：
    
    * **被替换文本**\ ：必填，大小写敏感。
    * **替换为**\ ：替换为的字符串，可以为空。"
    "Trim", "从文本的开头和结尾移除特定的字符串。"
    "Left trim", "从文本的开头移除特定的字符串。"
    "Right trim", "从文本的结尾移除特定的字符串。"

结构化数据
^^^^^^^^^^^

.. csv-table::
    :header: "方法名称", "描述"
    :widths: 20, 80

    "XML XPath", "用 XPath 功能从 XML 内获取要素。
    
    要想使用本功能， Zabbix Server 必须在编译时启用 libxml 功能。
    
    XPath 的详细说明请见 `XPath 教程 <https://www.w3school.com.cn/xpath/index.asp>`_\ 。
    
    几个简单示例如下：
    
    * ``number(/msg/attr/value)``\ 会从\ ``<msg><attr><value>27</value></attr></msg>``\ 中获取\ ``27``\ 。
    * ``string(/msg/attr/value/@unit)``\ 会从\ ``<msg><attr><value unit='%'>27</value></attr></msg>``\ 中获取\ ``%``\ 。
    * ``/msg/attr/``\ 会从\ ``<msg><attr><value>27</value></attr></msg>``\ 中获取\ ``<attr><value>27</value></attr>``\ 。"
    "JSONPath", "用 JSONPath 功能从 JSON 内获取要素。
    
    Zabbix 关于 JSONPath 的详细说明请见 :zabbix_manual:`JSONPath 功能 <config/items/preprocessing/jsonpath_functionality>`\ 。"

数制转换
^^^^^^^^

.. csv-table::
    :header: "方法名称", "描述"
    :widths: 20, 80

    "十六转十进制", "将值从十六进制转为十进制。"
    "八转十进制", "将值从八进制转为十进制。"

自定义脚本
^^^^^^^^^^

.. csv-table::
    :header: "方法名称", "描述"
    :widths: 20, 80

    "JavaScript", "利用 JavaScript 代码来处理数据。详细的信息请见 :zabbix_manual:`JavaScript 的预处理 <config/items/preprocessing/javascript>` \ 。"

验证
^^^^

.. csv-table::
    :header: "方法名称", "描述"
    :widths: 20, 80

    "In range", "定义输入数值应该满足的范围，可以等于最大值或最小值。若不满足则属性的状态会变为\ ``不受支持``\ 。
    
    最大值、最小值中至少要填写一个，可以使用产品或设备上的\ **变量**\ 。"

.. _value_mapping:

值映射
======

值映射方案可以被用在产品或设备下的属性和事件上，以使属性和事件的值的可读性更好，同时不影响入库保存的原始值。

.. note::
    * 产品的值映射方案可以被用在产品下的属性和事件上。
    * 产品内的值映射方案本身，不会被应用它的设备继承，也就不能被设备独有的属性或事件使用。

为了在属性上应用值映射，首先需要在产品或设备下添加值映射方案，然后在属性的\ **值映射**\ 内选择对应的值映射方案即可。

另可参考\ :ref:`在产品上添加值映射方案 <product_value_mapping>`\ 。

.. _attr_tag:

标签
====

属性上的标签，也会自动被标记到相关的告警上，从而方便查询与统计分析。

标签的详细信息请见\ :ref:`标签 <tag>`\ 。

.. important::
    产品属性、设备属性上的标签有如下关系：

    * 在创建设备时，产品属性上的标签，会自动应用在设备的属性上。
    * 设备属性上的标签可以任意增删改。
    * 在产品的任一属性里，进行标签的新增或编辑操作时，所有该产品的设备里的该属性的标签都会变得与该产品属性内的标签同步，并且丢失所有之前针对该属性下标签的手动调整。