基础数据收集器

名称：基础数据采集器

描述：库存数据采集器工具包用于为iTop创建自己的数据收藏家

版本:1.1.4

发布:2020-07-07

状态：稳定

扩散：客户商店，Combodo网站

该模块为创建用于iTop的工业数据集合和同步应用提供了基础。开发人员可以依靠此模块来执行与iTop数据导入和同步数据相关的所有繁重工作，以便专注于数据集合。

下载1.1.4

特征

• 简单的API，使创建新的采集器变得容易快捷。
• 根据JSON定义在iTop中自动创建和更新Synchronization数据源。
• 通过明确的“可选”属性，支持对目标数据模型的细微变化
• CSV格式的基本验证与同步数据源中的预期字段进行了比较。
• 数据通过max_chunk_size（可配置）的块进行上传和同步。
• 用于处理参数配置的可扩展机制。
• JSON定义中占位符的可扩展列表。
• 通知联系人的自动管理（通过占位符）和用于运行同步的用户。
• PHP的最小版本的验证和所需的扩展（由采集器指定）。
• 命令行工具，用于从iTop中的现有同步数据源生成JSON定义。
• 能力独立运行：数据源的配置，数据集合和数据同步。
• 可配置的日志级别（用于控制台输出或syslog日志记录）
• 快速创建基于SQL的收集器的简单框架
  

修订记录

发布日期	版本	注释
2020-10-28	1.2.0	* 新的JSON收集器. * CSV器配置：格式+新参数的变化 defaults / field / ignored_columns / has_header * 添加testcon/ection. php脚本 * 配置文件的路径现在可以通过选项--config_file在命令指定线.
2020-06-24	1.1.4	*现在可以通过命令行上的--config_file选项指定配置文件的路径。 *现在，存储收集到的数据的位置是配置文件中的参数：data_path。 *更好地检查数据源定义以捕获丢失的对帐键 * Lookuptable类的选项将查找错误视为正常错误
2020-04-30	1.1.3	*新的CSV采集器 *在日志中添加了可配置的时间戳 *用法的新选项：–帮助
2019-11-07	1.1.2	修复“未定义常量TABLENAME_PATTERN”
2019-10-28	1.1.1	包含从1.0.13和1.1.0的升级 *拒绝database_table_name的无效字符
2019-10-28	1.1.0	基于1.0.9 *添加了特定的类MySQLCollector，该类强制数据库连接使用UTF-8字符
2019-10-28	1.0.13	* LookupTables现在可以不区分大小写了（因为MySQL不区分大小写） *防止在SQLCollector中为每个“忽略的”属性警告 *改进了对iTop 2.4+（废弃标志）的支持
2019-10-28	1.0.12	*删除了PHP 7.2中的警告
2018-06-26	1.0.11	添加了调试跟踪（如果console_log_level = 9，则可见）以显示应用了常规表达式的映射（应用时）。 漏洞修复：正确处理映射表正则表达式中的utf-8字符（（u修饰符） 使cUrllSSL选项可配置为适合所有可能的组合和安全注意事项。
2015-06-30	1.0.10	采集器的新类：MySQLCollector，它强制将检索到的数据编码为U-8。
2015-06-09	1.0.9	性能增强功能：构建查找表时仅检索所需的字段。
2015-06-02	1.0.8	更好地检查文件访问权利以进行写入。 SQL连接字符串（用于SQL收集器）现在可以完全配置。
2015-05-20	1.0.7	错误修复：支持在文件名中使用反斜杠。通过将Utils :: Substitute（）标记为静态，删除了警告。
2015-05-13	1.0.6	添加了在重新处理数据时“忽略”某些行的支持。可以将SQL采集器配置为安全地忽略某些字段。
2015-02-16	1.0.4	添加了配置参数stop_on_同步_错误。
2015-01-06	1.0.3	处理非U-8数据（通过GetCharset（）的重载），错误检查数据数据阶段，iTop 2.1.0的优化：忽略变更_table_name字段中的任何导入。
2014-11-03	1.0.2	添加了基类SQLCollector，可轻松创建基于SQL的收集器。
2014-10-11	1.0.1	添加了AttributeIsOptional方法来处理目标数据模型中的变化。
2014-05-13	1.0.0	第一个版本

局限性

• 仅通过syncho_import Web服务将数据上传到iTop（可以使用命令行版本或直接使用SQL命令。也许稍后再使用）
• 在SVN的iTop版本3805之前（从2015-10-12开始！），如果用于连接到iTop的账号未配置为使用英语作为语言，则采集器将无法正常工作！
  

要求

• PHP版本5.3.0（某些收集器可能需要支持名称空间）
• 访问iTop Web服务（(REST + synchro_import.php and synchro_exec.php）
• 我们建议安装php_curl以使用采集器基本参数 itop_synchro_timeout ，否则超时将被硬编码为200秒，并且不能被采集器覆盖。
  

在1000个同步对象下，如果没有php_curl，它应该可以工作，而在上面不能！

安装

• 在将运行采集器的机器上的文件夹中，展开zip归档的内容。
• 编辑文件conf/params.local.xml的内容以适合您的安装。
  

配置
原则

params.distrib.xml文件包含参数的默认值。这两个文件（params.distrib.xml和params.local.xml）使用完全相同的格式。但是，params.distrib.xml被视为引用，应保持不变。如果您需要变更的变更和价值，请复制并修改其定义inparams.local.xml。 params.local.xml中的值优先于params.distrib.xml中的值

配置

params.local.xml是唯一可编辑以配置采集器的文件。

至少必须在此文件中设置以下参数：

<itop_url>https://localhost/</itop_url> <itop_login>admin</itop_login>

<itop_password>admin</itop_password>

参数	含义	样品价值
itop_login	连接到iTop的登录名（用户账号）。必须具有管理员权利才能执行数据同步。	管理员
itop_password	iTop账号的密码。
itop_url	iTop应用的URL	https://localhost/itop

可选参数

可以重新定义以下参数以更改采集器的默认行为：

参数	含义	默认价值
max_chunk_size	一次迭代中流程的最大元素数（用于iTop中的上载和同步）。如果元素数超过此数目，则流程将自动进行迭代。	1000
itop_synchro_timeout	等待执行一个数据同步任务的超时（以秒为单位）-需要php_curl	600
stop_on_synchro_error	在同步期间发生错误时是否停止（是或否）。	没有
console_log_level	控制台的输出级别。从-1（无）到9（调试）。	6（信息）
console_log_dateformat	记录器时间戳格式	[Y-m-d H:i:s]
curl_options	使用cUrl连接到iTop Web服务时，可以在本节中指定cUrl选项。语法是<CURLOPT_NAME_OF_THE_OPTION1>价值_1 << CURLOPT_NAME_OF_THE_OPTION1>，其中价值_x是： 选项的数字价值， 或相应PHP“定义”的字符串表示形式（区分大小写）。 可以定义几个php_curl选项，如下例所示
数据_path	1.1.4中的新增功能存储采集器生成的临时文件的路径。您可以使用特殊的占位符％APPROOT％来指定相对于采集器根文件夹的pth。	％APPROOT %%数据

<curl_options>
    <CURLOPT_SSL_VERIFYHOST>0</CURLOPT_SSL_VERIFYHOST>   
   <CURLOPT_SSL_VERIFYPEER>1</CURLOPT_SSL_VERIFYPEER>
</curl_options>


数据源的配置中的占位符

用于配置数据源的JSON文件包含从以上配置初始化的几个占位符（$联系人_to_notify $），以及特定于数据源的其他占位符。这些占位符可以在参数文件的<json_placeholders>数据内部进行配置：

参数	含义	默认价值
synchro_user	如果用于运行此同步的用户账号不是管理员，则必须在此处指定其登录名，因为iTop仅允许管理员和指定的用户运行同步。
contact_to_notify	iTop中现有联系人的发送邮件地址，将被通知同步结果
full_load_interval	两次完整导入数据之间的延迟（以秒为单位）。如果采集器在超过此间隔的时间间隔内未检测到对象，则将其视为过时并在iTop中进行标记。调整此价值依赖的计划周期。	604800
prefix	iTop中所有Synchronization数据Sources名称的前缀。如果您运行采集器的多个实例（以从多个vSphere服务器收集信息），请变更此价值，以便每个数据源具有唯一的名称。

用法

要启动数据集合并与iTop同步，请运行以下命令（从安装应用的根目录）：

php exec.php

以下（可选）命令行选项可用：

选项	含义	默认价值
--config_file	指定配置文件的完整路径。如果忽略此参数，则默认使用文件conf/params.local.xml。	空的
--console_log_level = <level>	控制台的输出级别。从-1（无）到9（调试）。	6（信息）
--collect_only	仅运行数据集合，但不运行带有iTop的动态数据	假
--synchro_only	将先前收集的数据（存储在数据目录中）与iTop同步。不要运行该集合。	假
--configure_only	在iTop中检查（并根据需要更新）同步数据源并退出。不要运行收集或同步
--max_chunk_size = <size>	一次保存流程的最大项目数，以保留系统的内存。如果流程还有更多项目，则流程将进行迭代。	1000
-help	使用模式显示exec.php帮助。

运行采集器的多个实例

在许多情况下，使用一组不同的参数运行采集器几次可能会很有用。例如，从多个LDAP服务器（iTop LDAP数据采集器）收集人员信息，或从多个vSphere服务器（iTop vSphere数据采集器）收集虚拟机信息。

在框架版本1.1.4之前，您必须完全复制采集器应用并在每个副本上调整文件conf/params.local.xml。

从版本1.1.4开始，您只能拥有一份采集器应用的副本，并为要运行的每个集合指定一个不同的配置文件（使用命令行选项--config_file）（即每个LDAP或vSphere配置一个配置文件）。

但是，为避免在收集数据以及与iTop同步期间出现任何麻烦，必须在配置文件中正确配置以下参数：

• 在每个不同的配置文件中使用不同的<prefix>。这样可以确保为每个配置文件创建一组特定的同步数据源。
• 为每个配置文件使用不同的<数据_path>变量。这将导致采集器将其收集的所有数据（包括一些临时文件）存储在专用目录中。这样可以防止采集器的一个实例覆盖另一实例的数据。您可以使用数据<数据_path>％APPROOT %% data/collector1 <<数据>在数据文件夹中创建一个子文件夹collector1。
  

创建一个采集器

有关采集器的详细信息位于“收集器”文件夹中。此文件夹内必须至少有一个文件main.php。 main.php的目的是为模块注册所有采集器类，并加载相应的类（通过require_once（…）或通过注册自动加载器）。

采集器是一个PHP类，它为给定的同步数据源提供数据。采集器类是从抽象采集器类派生的。每个采集器与一个以JSON格式定义的同步数据源关联。默认的数据只是在collectors文件夹中查找与采集器类名称相同且扩展名为“ .json”的JSON文件。

指定所需的扩展

如果您的采集器需求是特定扩展名（或最低PHP版本），则可以通过在main.php中调用静态方法Orchestrator ::

AddRequirement（$ sMinRequiredVersion，$ sExtension ='PHP'）来指示此依赖：

例如：

Orchestrator::AddRequirement('5.4.0'); //This requires at least PHP 5.4
Orchestrator::AddRequirement('1.2.0', 'ldap'); //This requires at least the ldap extension version 1.2.0


创建JSON定义文件

为同步数据源创建JSON文件的更简单方法是，对导出定义现有数据源。

• 在iTop中创建同步数据源，并调整其参数（属性等）以适合您的需求
• 使用命令行工具dump_tasks.php（在工具包文件夹中提供）来生成JSON文件：
  

php toolkit/dump_tasks.php --task_name="name of the task to export" > collectors/myCollector.json

在数据源定义中，可以使用特殊的占位符使数据源可以由应用的数据配置，或通过一些特殊设置来调整其行为：

占位符代码	含义	样品价值
$version$	模块的版本。用于对应用进行版本控制，例如在同步数据源的“描述”中。	1.0.0
$synchro_user$	用户运行同步，由配置文件中的登录名指定。用户对象的标识符可通过此占位符获得。	12
$contact_to_notify$	由配置文件中的发送邮件地址指定的联系人进行通知。联系人的标识符通过此占位符提供。	48

在上面列出的3个特殊参数配置之上，配置文件的“ json_placeholders”部分中定义的所有参数也可用作JSON文件内的占位符。

示例配置文件：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=6]params.local.xml[/url]


<?xml version="1.0" encoding="UTF-8"?>
<!--  Local values for parameters. -->
<!--  The values defined in this file have precedence over the ones defined in


params.distrib.xml -->
<parameters>
  <itop_url>https://localhost/trunk</itop_url>
  <itop_login>admin</itop_login>
  <itop_password>admin</itop_password>
  <console_log_level>9</console_log_level>
  <contact_to_notify>denis.flaven@ </contact_to_notify>
  <synchro_user>admin</synchro_user>
  <json_placeholders type="hash">
    <test>Test 1</test>
  </json_placeholders>
</parameters>

示例同步数据源定义文件，请注意$version$, $synchro_user$, $contact_to_notify$ and$test$ placeholders:的使用：

如果为database_table_name, this name MUST BEGIN WITH <table-prefix>synchro_data。其中<prefix>是iTop中所有表使用的前缀（使用iTop配置文件中的db_subname参数配置）。

如果修改已经收集的类的字段列表，则必须更新JSON定义文件，以指定如何处理新字段。默认情况下，它们被添加到现有数据同步中，没有更新且没有锁定。

实施采集器

您的采集器必须是从采集器派生的类。它必须（至少）实现Fetch（）方法。对于每个要加载的对象，访存必须返回格式为属性_code =>价值的数组，或者在到达对象集的末尾时返回false。

Fetch（）返回的数组必须包含：

• 条目primary_key唯一标识正在与iTop同步的对象。该条目可以包含可以从库存集合中获得的任何唯一ID，也可以包含作为对象的各个字段的组合而生成的唯一标识符。由采集器应用来保证此标识符的唯一性（及其时间稳定性）
• 要在iTop中加载的对象的每个属性的条目。
  

下面的示例代码生成了一组10个服务器，分别名为“服务器1”，“服务器2” ...“服务器10”，并初始化了服务器的3个字段：它们的名称，它们的组织（始终为“ Demo”）及其描述。

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=7]main.php[/url]

如果采集器返回的数据未使用U-8字符集编码，请重载采集器的GetCharset（）方法以返回字符集的名称（必须返回iTop采集器上iconv接受的价值）

注册您的采集器

要注册采集器，请调用静态方法Orchestrator :: AddCollector（）。这两个参数是：

• 采集器的运行顺序（当您需要一个接一个地运行多个收集器时）
• 实现采集器的类的名称（从采集器派生）。
  

参数的默认值

采集器模块可以通过在collectors文件夹中提供文件params.distrib.xml来为其参数提供默认值。如果存在这样的文件，则将其值合并到conf目录中的等效文件上。

现有的基础收藏家

要创建新的采集器，可以将其基于标准或使用最近添加的那些收集器之一，这些收集器已经在数据来源上完成了依赖的工作：

CSV采集器

SQL采集器

JSON采集器（将于2021年发布）

SQL收集器

“核心”文件夹提供了一个抽象类SQLCollector，它可以用作快速创建通过SQL查询检索其数据的收集器的基础。

要创建这样的采集器，您需要：

• 创建从SQLCollector派生的类
• 为数据同步源创建json定义文件
• 添加配置参数（在params.distrib.xml中）以定义要运行的SQL查询
• 在collectors/main.php中注册您的采集器
  

用于SQL收集器的参数配置是：

参数	含义	默认价值
sql_engine	的[  /manual/en/pdo.drivers.php]PDO驱动引擎[/url] 用于数据库连接。	MySQL的
sql_host	要连接的数据库服务器的名称或IP地址。	本地主机
sql_database	要连接的数据库的名称。	空的
sql_login	连接到数据库时要使用的登录名	根
sql_password	连接到数据库时使用的密码	n/a
sql_connection_string	1.0.8中的新增功能PDO连接字符串的格式。格式字符串内有3个占位符：％1 $ s = sql_engine，％2 $ s = sql_数据库和％3 $ s = sql_host	％1 $ s：dbname =％2 $ s;host=％3 $ s
collector_class_query	为采集器运行的查询，PHP类为collector_class
collector_class_ignored_attribute	1.0.6中的新增功能为了将数据模型的可能的变种纳入账号中，而不必每次都重写采集器，可以将某些收集的属性标记为“可选”，以便即使相应的采集器也可以运行采集器。在数据模型中不存在。供应在此忽略采集器代码数组。

要指定端口号（或任何其他驱动程序特定的选项），请使用变更sql_connection_string的格式。例如：％1 $ s：dbname =％2 $ s; host =％3 $ s; port = 3307

对于1.0.8之前的版本，要指定端口号（默认端口除外），请使用语法主机； sql_host参数使用port = xxxx。例如：localhost; port = 3307

从版本1.0.10开始，该框架提供了采集器的新类：MySQLCollector。该类与SQLCollector相同，除了它通过在与数据库的每个连接的开始处发出SQL命令SET NAMES'u8'来强制将检索到的数据编码为U-8之外。为了避免任何带有数据字符集的问题，建议对与MySQLLMariaDB数据库的所有连接使用此新类。

简单SQL采集器的示例

让我们创建一个非常简单的SQL采集器，它将“笔记”文档（类DocumentNote）从一个iTop实例复制到另一个。由于采集器从基类继承了所有行为，因此采集器的PHP代码很简单：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=8]DocumentNotesCollector.class.inc.php[/url]

<?php class DocumentNoteCollector extends SQLCollector { }

Find here a sample of an SQL collector definition file.

Then in params.distrib.xml, add the following entries:

  <sql_database>test</sql_database>

  <sql_login>root</sql_login>

  <sql_password>s3cret</sql_password>

  <documentnotecollector_query>SELECT id as primary_key, name, text, description,

status, '2.0' as version, documenttype_id, 1 as org_id FROM

view_DocumentNote</documentnotecollector_query>

  <documentnotecollector_ignored_attributes type="array">

    <attribute>location_id</attribute>

    <attribute>version_id</attribute>

  </documentnotecollector_ignored_attributes>

然后在params.distrib.xml中，添加以下条目：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=10]main.php[/url]
<?phprequire_once(APPROOT.'collectors/DocumentNoteCollector.class.inc.php');
Orchestrator::AddCollector(1 /* $iRank */, 'DocumentNoteCollector');


CSV采集器

“核心”文件夹提供了一个抽象类CSVCollector，它可作为快速创建从CSV文件检索其数据的收集器的基础。

要创建这样的采集器，您需要：

• 创建从CSVCollector派生的类
• 为数据同步源创建json定义文件
• 添加配置参数（在params.distrib.xml中）以定义要解析的CSV文件
• 在collectors/main.php中注册您的采集器
  

CSV收集器的参数配置是：

参数	含义	默认价值
collector_class_csv	要为采集器解析哪个PHP类的csv文件。您可以指定此文件的完整路径（（tmppmyfile.csv）或collector_class的相对路径。此采集器是必需的
collector_class_command	CLI命令，用于在采集器解析csv文件之前执行该操作，PHP类是采集器_class。该采集器是可选的
collector_class_encoding	采集器的csv文件编码，其PHP类为collector_class。该采集器是可选的	UTF-8
collector_class_separator	用于csv文件解析的分隔符。该参数是可选的	;

简单CSV采集器的示例

让我们创建一个非常简单的CSV采集器，它复制“ Person”对象（Person类）

由于采集器从基类继承了所有行为，因此采集器的PHP代码很简单：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=11]iTopPersonCsvCollector.class.inc.php[/url]

<?php class iTopPersonCsvCollector extends CSVCollector { }

在这里找到一个收集器定义的示例[ ttps://www.itophub.io/wiki/page?id=extensions%3Asample-collector-csv]CSV[/url]

然后在params.distrib.xml中，添加以下条目：

<?xml version="1.0" encoding="UTF-8"?>
<parameters>
        


<itoppersonjsoncollector_jsonurl>http://localhost/iTop/webservices/rest.php</itoppe


rsonjsoncollector_jsonurl>
        <itoppersonjsoncollector_jsonpost>
                <auth_user>restuser</auth_user>
                <auth_pwd>restuserpassword</auth_pwd>
                <json_data>{"operation": "core/get", "class": "Person", "key":


"SELECT Person WHERE email LIKE '%.com'", "output_fields": "friendlyname, email,


first_name, function, name, id, org_id,phone"}</json_data>
                <version>1.3</version>
        </itoppersonjsoncollector_jsonpost>
        <itoppersonjsoncollector_way>objects/*/fields</itoppersonjsoncollector_way>
        <itoppersonjsoncollector_fields>
                <primary_key>id</primary_key><!-- also this is not a field of the


itop object, that column is mandatory -->
                <name>name</name>
                <status>status</status>
                <first_name>first_name</first_name>
                <email>email</email>
                <phone>phone</phone>
                <mobile_phone>mobile</mobile_phone>
                <function>function</function>
                <employee_number>employee_number</employee_number>
                <org_id>org_id</org_id>
        </itoppersonjsoncollector_fields>
        <itoppersonjsoncollector_defaults>
                <org_id>Demo</org_id>
                <status>active</status>
        </itoppersonjsoncollector_defaults>
        <json_placeholders>
                <!-- For compatibility with the version 1.1.x of the collector,


define the data table names as following:
             <prefix></prefix>
             <persons_data_table>synchro_data_PersonAD</persons_data_table>
             <users_data_table></users_data_table>
              -->
                <prefix>$prefix$</prefix>
                <persons_data_table>synchro_data_person</persons_data_table>
        </json_placeholders>
</parameters>

最后，在collectors/main.php中添加以下行：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=13]main.php[/url] <?phprequire_once(APPROOT.'collectors/iTopPersonCsvCollector.class.inc.php');Orchestrator::AddCollector($index++, 'iTopPersonCsvCollector');


JSON采集器

“核心”文件夹提供了一个抽象类JSONCollector，它可以用作快速创建从JSON文件检索其数据的收集器的基础。

要创建这样的采集器，您需要：

• 创建从JSONCollector派生的类
• 为数据同步源创建json定义文件
• 添加一个配置参数（在params.distrib.xml中）以定义要解析的JSON文件
• 在collectors/main.php中注册您的采集器
  

JSON收集器的参数配置是：

参数	含义
jsonflie	定义要解析的采集器的json文件的相对或绝对路径，该PHP类是采集器collector_class。此采集器或collector_class_jsonurl是强制性的
jsonurl	要为采集器解析哪个php类的json文件的URL。此参数或collector_class_jsonpath是必需的
jsonpost	带有URL的参数Xml用来获取Json文件<name_of_param>价值<< name_of_param>
command	CLI命令，用于在采集器（其PHP类为collector_class）解析json文件之前执行。该采集器是可选的
path	在json分隔符中找到数据到动态的方法是，并且*用示例aaabb替换{“ aa”：{“ bb”：{mydata}，“ cc”：“ xxx”}和aaa * bb替换任何单词aa“：{cc”：{“ bb”：{mydata1}}，“ dd”：{“ bb”：{mydata2}}}
fields	xml女巫描述json中的名称与itop中的名称之间的连接<name_in_json> name_in_itop << name_in_json>

一个简单的JSON采集器的示例

让我们创建一个非常简单的JSON采集器，它将“ Person”对象（类Person）从一个iTop复制到另一个

由于采集器从基类继承了所有行为，因此采集器的PHP代码很简单：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=14]ITopPersonJsonCollector.class.inc.php[/url]

<?php class ITopPersonJsonCollector extends JsonCollector { }

JSON定义文件是

ITopPersonJsonCollector.json

然后在params.distrib.xml中，添加以下条目：

<?xml version="1.0" encoding="UTF-8"?>

<parameters>

        

<itoppersonjsoncollector_jsonurl>http://localhost/iTop/webservices/rest.php</itoppe

rsonjsoncollector_jsonurl>

        <itoppersonjsoncollector_jsonpost>

                <auth_user>restuser</auth_user>

                <auth_pwd>restuserpassword</auth_pwd>

                <json_data>{"operation": "core/get", "class": "Person", "key":

"SELECT Person WHERE email LIKE '%.com'", "output_fields": "friendlyname, email,

first_name, function, name, id, org_id,phone"}</json_data>

                <version>1.3</version>

        </itoppersonjsoncollector_jsonpost>

        <itoppersonjsoncollector_way>objects/*/fields</itoppersonjsoncollector_way>

        <itoppersonjsoncollector_fields>

                <primary_key>id</primary_key><!-- also this is not a field of the

itop object, that column is mandatory -->

                <name>name</name>

                <status>status</status>

                <first_name>first_name</first_name>

                <email>email</email>

                <phone>phone</phone>

                <mobile_phone>mobile</mobile_phone>

                <function>function</function>

                <employee_number>employee_number</employee_number>

                <org_id>org_id</org_id>

        </itoppersonjsoncollector_fields>

        <itoppersonjsoncollector_defaults>

                <org_id>Demo</org_id>

                <status>active</status>

        </itoppersonjsoncollector_defaults>

        <json_placeholders>

                <!-- For compatibility with the version 1.1.x of the collector,

define the data table names as following:

             <prefix></prefix>

             <persons_data_table>synchro_data_PersonAD</persons_data_table>

             <users_data_table></users_data_table>

              -->

                <prefix>$prefix$</prefix>

                <persons_data_table>synchro_data_person</persons_data_table>

        </json_placeholders>

</parameters>

最后，在collectors/main.php中添加以下行：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=16]main.php[/url]
<?php
require_once(APPROOT.'collectors/ITopPersonJsonCollector.class.inc.php');
Orchestrator::AddCollector($index++, 'ITopPersonJsonCollector');


高级收藏家

采集器框架为现实的收集器提供了执行一些高级处理的方法：

• 用于可配置数据规范化的DataMapping
• 基于多个字段的高级对帐的LookupTable
  

数据映射

由库存脚本收集的原始数据有时需要进行规范化，然后才能导入iTop，以便获得同质的数据。该框架提供了用于执行简单规范化任务的帮助程序类MappingTable。

映射表（在params.xxx.xml配置文件中）配置为模式的有序列表，并且每个模式都关联有价值。映射表返回的“干净”价值是与匹配输入价值的第一个模式相关联的价值。模式表示为正则表达式。值可以使用占位符来引用匹配模式的某些部分（％1 $ s是整个模式，％2 $ s是常规价值中的第一组，等等）。

配置的示例（品牌标准化）：

<brand_mapping type="array">

    <!-- Syntax /pattern/replacement where:

      any delimiter can be used (not only /)

      but the delimiter cannot be present in the "replacement" string

      pattern is a RegExpr pattern

      replacement is a sprintf string in which:

          %1$s will be replaced by the whole matched text,

          %2$s will be replaced by the first matched group, if any group is defined

in the RegExpr

          %3$s will be replaced by the second matched group, etc...

    -->

    <pattern>/IBM/IBM</pattern>

    <pattern>/Hewlett.Packard/Hewlett-Packard</pattern>

    <pattern>/Dell/Dell</pattern>

    <pattern>/.*/%1$s</pattern>

  </brand_mapping>

此示例文件执行以下规范化：

• 每个包含“ IBM”的字符串都将转换为“ IBM”，
• 每个包含“ Hewlett”，后跟任何字符和“ Packard”的字符串都将转换为“ Hewlett-Packard”，
• 每个包含“ Dell”的字符串都将转换为“ Dell”，
• 所有其他字符串保持原样。
  

在代码中使用映射表

• 创建MappingTable类的实例，并将其传递给XML标签的名称，以在其中查找其配置（在XML param文件内部）
• 根据需要使用MapValue方法对每个价值进行流程处理（当在映射表中找不到匹配项时，第二个参数是默认的价值）。
  

用法示例：

// Turns the raw brand string ('brand_id') into a normalized brand // Use 'Other' for brands not found in the normalization table class TestCollector extends SQLCollector { protected $oBrandMapping; public function Prepare() { $bRet = parent::Prepare(); // Create the MappingTable once at the initialization of your collector $this->oBrandMapping = new MappingTable('brand_mapping'); return $bRet; } public function Fetch() { $aData = parent::Fetch(); if ($aData !== false) { // Then process each collected brand $aData['brand_id'] = $this->oBrandMapping->MapValue($aData['brand_id'], 'Other'); } return $aData; } }

高级查找

嵌入在iTop中的数据同步机制无法执行基于多个字段的协调（例如，基于品牌名称和模型名称搜索模型）。 LookupTable类为任何数量的字段提供此协调模型。

LookupTable类通过检索一组iTop对象的指定字段并将对象的结果标识符存储在iTo&#8203;&#8203;p中来构建查找表。

通过指定OQL查询（要检索的iTop对象的集合）和将用于映射的对象的字段来创建LookupTable的实例。

在创建LookupTable实例期间指定的字段列表（和顺序）是稍后执行Lookup（…）时要传递的字段列表。

初始化LookupTable后，对Lookup（$ aData，array（Field1，Field2，…），desield）方法的调用将在$ aData中用iTop对象的标识符替换desield列的价值，其指定字段与值在$ aData中作为字段Field1，Field2…传递。

从版本1.0.6开始，如果未找到相应的查找，则Lookup方法将返回false。在这种情况下，代码可以供应的默认价值抛出IgnoredRowException异常，以告知采集器拒绝所收集的数据的整个行。

从版本1.1.4开始，LookupTable的构造函数接受一个额外的（可选）参数：$ bIgnoreMappingErrors（默认为false）。如果将此参数设置为true，则LookupTable将认为查找错误是正常的，并且不会报告将其作为警告（但仍在调试模式下列出）。当Lookuptable用于根据iTop中定义的目录过滤收集的数据时，这很有用。在这种情况下，查找错误是预期的行为。

例

在iTop中，运行中的系统版本表示为版本OS家族上的版本依赖。 iTop中可以包含以下对象：

• Windows 7.0和8.1版，
• Debian版本12.0.0。
  

它将存储在iTo&#8203;&#8203;p中，如下所示：

对象类	id	名称
OSFamily	1	视窗
OSFamily	2	Linux Debian
对象类	id	osfamily_id	名称
操作系统版本	1	1	7.0.0
操作系统版本	2	1	8.1.0
操作系统版本	3	2	12.0.0

现在，让我们想象一下，我们的采集器脚本为我们提供了两个信息：“ Windows”和“ 8.1.0”。我们可以将“ Windows”文本字符串存储在数据同步表的“ osfamily_id”字段中，并配置同步数据源以基于“名称”执行对帐（这将正确地将“ Windows”替换为1）。

但是要检索Windows的版本8.1.0的标识符（在我们的示例中为2），我们需要OS家族（“ Windows”）和版本号（“ 8.1.0”）。同步版本源无法执行此复合查找，而LookupTable才起作用。

$oOSVersionLookup = new LookupTable('SELECT OSVersion', ('osfamily_id_friendlyname', 'name'));

这将构建-在内存中-下表：

lookup_key	id
Windows_7.0.0	1
Windows_8.1.0	2
Debian_12.0.0	3

因此，如果我们在$ aData中具有以下值：

osfamily_id	osversion_id
Windows	8.1.0

致电：

$oOSVersionLookup->Lookup($aData, ('osfamily_id', 'osversion_id'), 'osversion_id', 0);

将查找结果$ aData ['osfamily_id']和$ aData ['osversion_id']的结果放入“ osversion_id”列。

$ aData将包含以下值：

osfamily_id	osversion_id
Windows	2

然后，我们必须配置同步数据源，以便它按原样接受oversion_id，而无需对其进行任何协调。

Lookup（...）的最后一个参数必须包含正在处理的CSV文件中的行号。在内部使用它仅在处理文件的第一行时执行一次初始化。

高级协调通过在数据集合之后但在将数据推到iTop之前（通过RESTTJSON API）检索要与组合键匹配的对象来进行。因此，为了使用此高级查找机制，必须告知框架采集器必须在实际数据之前重新处理收集的数据。这是通过重载采集器的

MustProces/BeforeSynchro方法来实现的；然后返回true。

采集器框架提供了两个可以重载的其他方法：

• 在数据收集之后但在开始重新处理收集的数据的每一行之前，将调用InitProces/BeforeSynchro。这是在其中创建LookupTable实例的地方
• 对收集的数据的每一行（包括CSV文件的标题行，索引为零）调用ProcessLineBeforeSynchro。
  

使用范例

以下代码片段显示了使用表的全部情况：一种用于品牌+模型，一种用于OS家族+ OS版本。

数据模型的变体

目标数据模型可能会发生一些变化（安装过程中选择的模块上的依赖）。如果某些配置中缺少给定的属性，则可以通过重载AttributeIsOptional方法来告诉采集器接受这种变化。 （这比为每种组合编写特定的采集器更为简单）。

如果缺少同步数据Source的JSON定义中指定的属性，除非属性声明为可选，否则处理将以错误停止。在后一种情况下，跳过的属性的名称记录在受保护的成员变量$ this-> aSkippedAttributes中，然后继续处理。属性的代码以后可以检查数组$ this-> aSkippedAttributes的内容，以确定是否必须收集哪些字段。

AttributeIsOptional的实施的示例作为VirtualMachineCollector类的方法：

故障排除

对协调机制进行故障排除时，将库存脚本报告的原始（原始）值与协调流程的结果进行比较非常有用。只要采集器的MustProcessBeforeSynchro方法返回true，框架就会在数据子目录中生成两个文件。通过比较两个CSV文件，您可以轻松地在查找之前比较这些值：

• <collector_name>.raw-<index>.csv: ：由库存脚本生成的原始数据，
• <collector_name>-<index>.csv: 重新处理的数据，将上传到iTop。
  

基础数据收集器

名称：基础数据采集器

描述：库存数据采集器工具包用于为iTop创建自己的数据收藏家

版本:1.1.4

发布:2020-07-07

状态：稳定

扩散：客户商店，Combodo网站

该模块为创建用于iTop的工业数据集合和同步应用提供了基础。开发人员可以依靠此模块来执行与iTop数据导入和同步数据相关的所有繁重工作，以便专注于数据集合。

下载1.1.4

特征

• 简单的API，使创建新的采集器变得容易快捷。
• 根据JSON定义在iTop中自动创建和更新Synchronization数据源。
• 通过明确的“可选”属性，支持对目标数据模型的细微变化
• CSV格式的基本验证与同步数据源中的预期字段进行了比较。
• 数据通过max_chunk_size（可配置）的块进行上传和同步。
• 用于处理参数配置的可扩展机制。
• JSON定义中占位符的可扩展列表。
• 通知联系人的自动管理（通过占位符）和用于运行同步的用户。
• PHP的最小版本的验证和所需的扩展（由采集器指定）。
• 命令行工具，用于从iTop中的现有同步数据源生成JSON定义。
• 能力独立运行：数据源的配置，数据集合和数据同步。
• 可配置的日志级别（用于控制台输出或syslog日志记录）
• 快速创建基于SQL的收集器的简单框架
  

修订记录

发布日期	版本	注释
2020-10-28	1.2.0	* 新的JSON收集器. * CSV器配置：格式+新参数的变化 defaults / field / ignored_columns / has_header * 添加testcon/ection. php脚本 * 配置文件的路径现在可以通过选项--config_file在命令指定线.
2020-06-24	1.1.4	*现在可以通过命令行上的--config_file选项指定配置文件的路径。 *现在，存储收集到的数据的位置是配置文件中的参数：data_path。 *更好地检查数据源定义以捕获丢失的对帐键 * Lookuptable类的选项将查找错误视为正常错误
2020-04-30	1.1.3	*新的CSV采集器 *在日志中添加了可配置的时间戳 *用法的新选项：–帮助
2019-11-07	1.1.2	修复“未定义常量TABLENAME_PATTERN”
2019-10-28	1.1.1	包含从1.0.13和1.1.0的升级 *拒绝database_table_name的无效字符
2019-10-28	1.1.0	基于1.0.9 *添加了特定的类MySQLCollector，该类强制数据库连接使用UTF-8字符
2019-10-28	1.0.13	* LookupTables现在可以不区分大小写了（因为MySQL不区分大小写） *防止在SQLCollector中为每个“忽略的”属性警告 *改进了对iTop 2.4+（废弃标志）的支持
2019-10-28	1.0.12	*删除了PHP 7.2中的警告
2018-06-26	1.0.11	添加了调试跟踪（如果console_log_level = 9，则可见）以显示应用了常规表达式的映射（应用时）。 漏洞修复：正确处理映射表正则表达式中的utf-8字符（（u修饰符） 使cUrllSSL选项可配置为适合所有可能的组合和安全注意事项。
2015-06-30	1.0.10	采集器的新类：MySQLCollector，它强制将检索到的数据编码为U-8。
2015-06-09	1.0.9	性能增强功能：构建查找表时仅检索所需的字段。
2015-06-02	1.0.8	更好地检查文件访问权利以进行写入。 SQL连接字符串（用于SQL收集器）现在可以完全配置。
2015-05-20	1.0.7	错误修复：支持在文件名中使用反斜杠。通过将Utils :: Substitute（）标记为静态，删除了警告。
2015-05-13	1.0.6	添加了在重新处理数据时“忽略”某些行的支持。可以将SQL采集器配置为安全地忽略某些字段。
2015-02-16	1.0.4	添加了配置参数stop_on_同步_错误。
2015-01-06	1.0.3	处理非U-8数据（通过GetCharset（）的重载），错误检查数据数据阶段，iTop 2.1.0的优化：忽略变更_table_name字段中的任何导入。
2014-11-03	1.0.2	添加了基类SQLCollector，可轻松创建基于SQL的收集器。
2014-10-11	1.0.1	添加了AttributeIsOptional方法来处理目标数据模型中的变化。
2014-05-13	1.0.0	第一个版本

局限性

• 仅通过syncho_import Web服务将数据上传到iTop（可以使用命令行版本或直接使用SQL命令。也许稍后再使用）
• 在SVN的iTop版本3805之前（从2015-10-12开始！），如果用于连接到iTop的账号未配置为使用英语作为语言，则采集器将无法正常工作！
  

要求

• PHP版本5.3.0（某些收集器可能需要支持名称空间）
• 访问iTop Web服务（(REST + synchro_import.php and synchro_exec.php）
• 我们建议安装php_curl以使用采集器基本参数 itop_synchro_timeout ，否则超时将被硬编码为200秒，并且不能被采集器覆盖。
  

在1000个同步对象下，如果没有php_curl，它应该可以工作，而在上面不能！

安装

• 在将运行采集器的机器上的文件夹中，展开zip归档的内容。
• 编辑文件conf/params.local.xml的内容以适合您的安装。
  

配置
原则

params.distrib.xml文件包含参数的默认值。这两个文件（params.distrib.xml和params.local.xml）使用完全相同的格式。但是，params.distrib.xml被视为引用，应保持不变。如果您需要变更的变更和价值，请复制并修改其定义inparams.local.xml。 params.local.xml中的值优先于params.distrib.xml中的值

配置

params.local.xml是唯一可编辑以配置采集器的文件。

至少必须在此文件中设置以下参数：

<itop_url>https://localhost/</itop_url> <itop_login>admin</itop_login>

<itop_password>admin</itop_password>

参数	含义	样品价值
itop_login	连接到iTop的登录名（用户账号）。必须具有管理员权利才能执行数据同步。	管理员
itop_password	iTop账号的密码。
itop_url	iTop应用的URL	https://localhost/itop

可选参数

可以重新定义以下参数以更改采集器的默认行为：

参数	含义	默认价值
max_chunk_size	一次迭代中流程的最大元素数（用于iTop中的上载和同步）。如果元素数超过此数目，则流程将自动进行迭代。	1000
itop_synchro_timeout	等待执行一个数据同步任务的超时（以秒为单位）-需要php_curl	600
stop_on_synchro_error	在同步期间发生错误时是否停止（是或否）。	没有
console_log_level	控制台的输出级别。从-1（无）到9（调试）。	6（信息）
console_log_dateformat	记录器时间戳格式	[Y-m-d H:i:s]
curl_options	使用cUrl连接到iTop Web服务时，可以在本节中指定cUrl选项。语法是<CURLOPT_NAME_OF_THE_OPTION1>价值_1 << CURLOPT_NAME_OF_THE_OPTION1>，其中价值_x是： 选项的数字价值， 或相应PHP“定义”的字符串表示形式（区分大小写）。 可以定义几个php_curl选项，如下例所示
数据_path	1.1.4中的新增功能存储采集器生成的临时文件的路径。您可以使用特殊的占位符％APPROOT％来指定相对于采集器根文件夹的pth。	％APPROOT %%数据

<curl_options>
    <CURLOPT_SSL_VERIFYHOST>0</CURLOPT_SSL_VERIFYHOST>   
   <CURLOPT_SSL_VERIFYPEER>1</CURLOPT_SSL_VERIFYPEER>
</curl_options>


数据源的配置中的占位符

用于配置数据源的JSON文件包含从以上配置初始化的几个占位符（$联系人_to_notify $），以及特定于数据源的其他占位符。这些占位符可以在参数文件的<json_placeholders>数据内部进行配置：

参数	含义	默认价值
synchro_user	如果用于运行此同步的用户账号不是管理员，则必须在此处指定其登录名，因为iTop仅允许管理员和指定的用户运行同步。
contact_to_notify	iTop中现有联系人的发送邮件地址，将被通知同步结果
full_load_interval	两次完整导入数据之间的延迟（以秒为单位）。如果采集器在超过此间隔的时间间隔内未检测到对象，则将其视为过时并在iTop中进行标记。调整此价值依赖的计划周期。	604800
prefix	iTop中所有Synchronization数据Sources名称的前缀。如果您运行采集器的多个实例（以从多个vSphere服务器收集信息），请变更此价值，以便每个数据源具有唯一的名称。

用法

要启动数据集合并与iTop同步，请运行以下命令（从安装应用的根目录）：

php exec.php

以下（可选）命令行选项可用：

选项	含义	默认价值
--config_file	指定配置文件的完整路径。如果忽略此参数，则默认使用文件conf/params.local.xml。	空的
--console_log_level = <level>	控制台的输出级别。从-1（无）到9（调试）。	6（信息）
--collect_only	仅运行数据集合，但不运行带有iTop的动态数据	假
--synchro_only	将先前收集的数据（存储在数据目录中）与iTop同步。不要运行该集合。	假
--configure_only	在iTop中检查（并根据需要更新）同步数据源并退出。不要运行收集或同步
--max_chunk_size = <size>	一次保存流程的最大项目数，以保留系统的内存。如果流程还有更多项目，则流程将进行迭代。	1000
-help	使用模式显示exec.php帮助。

运行采集器的多个实例

在许多情况下，使用一组不同的参数运行采集器几次可能会很有用。例如，从多个LDAP服务器（iTop LDAP数据采集器）收集人员信息，或从多个vSphere服务器（iTop vSphere数据采集器）收集虚拟机信息。

在框架版本1.1.4之前，您必须完全复制采集器应用并在每个副本上调整文件conf/params.local.xml。

从版本1.1.4开始，您只能拥有一份采集器应用的副本，并为要运行的每个集合指定一个不同的配置文件（使用命令行选项--config_file）（即每个LDAP或vSphere配置一个配置文件）。

但是，为避免在收集数据以及与iTop同步期间出现任何麻烦，必须在配置文件中正确配置以下参数：

• 在每个不同的配置文件中使用不同的<prefix>。这样可以确保为每个配置文件创建一组特定的同步数据源。
• 为每个配置文件使用不同的<数据_path>变量。这将导致采集器将其收集的所有数据（包括一些临时文件）存储在专用目录中。这样可以防止采集器的一个实例覆盖另一实例的数据。您可以使用数据<数据_path>％APPROOT %% data/collector1 <<数据>在数据文件夹中创建一个子文件夹collector1。
  

创建一个采集器

有关采集器的详细信息位于“收集器”文件夹中。此文件夹内必须至少有一个文件main.php。 main.php的目的是为模块注册所有采集器类，并加载相应的类（通过require_once（…）或通过注册自动加载器）。

采集器是一个PHP类，它为给定的同步数据源提供数据。采集器类是从抽象采集器类派生的。每个采集器与一个以JSON格式定义的同步数据源关联。默认的数据只是在collectors文件夹中查找与采集器类名称相同且扩展名为“ .json”的JSON文件。

指定所需的扩展

如果您的采集器需求是特定扩展名（或最低PHP版本），则可以通过在main.php中调用静态方法Orchestrator ::

AddRequirement（$ sMinRequiredVersion，$ sExtension ='PHP'）来指示此依赖：

例如：

Orchestrator::AddRequirement('5.4.0'); //This requires at least PHP 5.4
Orchestrator::AddRequirement('1.2.0', 'ldap'); //This requires at least the ldap extension version 1.2.0


创建JSON定义文件

为同步数据源创建JSON文件的更简单方法是，对导出定义现有数据源。

• 在iTop中创建同步数据源，并调整其参数（属性等）以适合您的需求
• 使用命令行工具dump_tasks.php（在工具包文件夹中提供）来生成JSON文件：
  

php toolkit/dump_tasks.php --task_name="name of the task to export" > collectors/myCollector.json

在数据源定义中，可以使用特殊的占位符使数据源可以由应用的数据配置，或通过一些特殊设置来调整其行为：

占位符代码	含义	样品价值
$version$	模块的版本。用于对应用进行版本控制，例如在同步数据源的“描述”中。	1.0.0
$synchro_user$	用户运行同步，由配置文件中的登录名指定。用户对象的标识符可通过此占位符获得。	12
$contact_to_notify$	由配置文件中的发送邮件地址指定的联系人进行通知。联系人的标识符通过此占位符提供。	48

在上面列出的3个特殊参数配置之上，配置文件的“ json_placeholders”部分中定义的所有参数也可用作JSON文件内的占位符。

示例配置文件：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=6]params.local.xml[/url]


<?xml version="1.0" encoding="UTF-8"?>
<!--  Local values for parameters. -->
<!--  The values defined in this file have precedence over the ones defined in


params.distrib.xml -->
<parameters>
  <itop_url>https://localhost/trunk</itop_url>
  <itop_login>admin</itop_login>
  <itop_password>admin</itop_password>
  <console_log_level>9</console_log_level>
  <contact_to_notify>denis.flaven@ </contact_to_notify>
  <synchro_user>admin</synchro_user>
  <json_placeholders type="hash">
    <test>Test 1</test>
  </json_placeholders>
</parameters>

示例同步数据源定义文件，请注意$version$, $synchro_user$, $contact_to_notify$ and$test$ placeholders:的使用：

如果为database_table_name, this name MUST BEGIN WITH <table-prefix>synchro_data。其中<prefix>是iTop中所有表使用的前缀（使用iTop配置文件中的db_subname参数配置）。

如果修改已经收集的类的字段列表，则必须更新JSON定义文件，以指定如何处理新字段。默认情况下，它们被添加到现有数据同步中，没有更新且没有锁定。

实施采集器

您的采集器必须是从采集器派生的类。它必须（至少）实现Fetch（）方法。对于每个要加载的对象，访存必须返回格式为属性_code =>价值的数组，或者在到达对象集的末尾时返回false。

Fetch（）返回的数组必须包含：

• 条目primary_key唯一标识正在与iTop同步的对象。该条目可以包含可以从库存集合中获得的任何唯一ID，也可以包含作为对象的各个字段的组合而生成的唯一标识符。由采集器应用来保证此标识符的唯一性（及其时间稳定性）
• 要在iTop中加载的对象的每个属性的条目。
  

下面的示例代码生成了一组10个服务器，分别名为“服务器1”，“服务器2” ...“服务器10”，并初始化了服务器的3个字段：它们的名称，它们的组织（始终为“ Demo”）及其描述。

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=7]main.php[/url]

如果采集器返回的数据未使用U-8字符集编码，请重载采集器的GetCharset（）方法以返回字符集的名称（必须返回iTop采集器上iconv接受的价值）

注册您的采集器

要注册采集器，请调用静态方法Orchestrator :: AddCollector（）。这两个参数是：

• 采集器的运行顺序（当您需要一个接一个地运行多个收集器时）
• 实现采集器的类的名称（从采集器派生）。
  

参数的默认值

采集器模块可以通过在collectors文件夹中提供文件params.distrib.xml来为其参数提供默认值。如果存在这样的文件，则将其值合并到conf目录中的等效文件上。

现有的基础收藏家

要创建新的采集器，可以将其基于标准或使用最近添加的那些收集器之一，这些收集器已经在数据来源上完成了依赖的工作：

CSV采集器

SQL采集器

JSON采集器（将于2021年发布）

SQL收集器

“核心”文件夹提供了一个抽象类SQLCollector，它可以用作快速创建通过SQL查询检索其数据的收集器的基础。

要创建这样的采集器，您需要：

• 创建从SQLCollector派生的类
• 为数据同步源创建json定义文件
• 添加配置参数（在params.distrib.xml中）以定义要运行的SQL查询
• 在collectors/main.php中注册您的采集器
  

用于SQL收集器的参数配置是：

参数	含义	默认价值
sql_engine	的[  /manual/en/pdo.drivers.php]PDO驱动引擎[/url] 用于数据库连接。	MySQL的
sql_host	要连接的数据库服务器的名称或IP地址。	本地主机
sql_database	要连接的数据库的名称。	空的
sql_login	连接到数据库时要使用的登录名	根
sql_password	连接到数据库时使用的密码	n/a
sql_connection_string	1.0.8中的新增功能PDO连接字符串的格式。格式字符串内有3个占位符：％1 $ s = sql_engine，％2 $ s = sql_数据库和％3 $ s = sql_host	％1 $ s：dbname =％2 $ s;host=％3 $ s
collector_class_query	为采集器运行的查询，PHP类为collector_class
collector_class_ignored_attribute	1.0.6中的新增功能为了将数据模型的可能的变种纳入账号中，而不必每次都重写采集器，可以将某些收集的属性标记为“可选”，以便即使相应的采集器也可以运行采集器。在数据模型中不存在。供应在此忽略采集器代码数组。

要指定端口号（或任何其他驱动程序特定的选项），请使用变更sql_connection_string的格式。例如：％1 $ s：dbname =％2 $ s; host =％3 $ s; port = 3307

对于1.0.8之前的版本，要指定端口号（默认端口除外），请使用语法主机； sql_host参数使用port = xxxx。例如：localhost; port = 3307

从版本1.0.10开始，该框架提供了采集器的新类：MySQLCollector。该类与SQLCollector相同，除了它通过在与数据库的每个连接的开始处发出SQL命令SET NAMES'u8'来强制将检索到的数据编码为U-8之外。为了避免任何带有数据字符集的问题，建议对与MySQLLMariaDB数据库的所有连接使用此新类。

简单SQL采集器的示例

让我们创建一个非常简单的SQL采集器，它将“笔记”文档（类DocumentNote）从一个iTop实例复制到另一个。由于采集器从基类继承了所有行为，因此采集器的PHP代码很简单：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=8]DocumentNotesCollector.class.inc.php[/url]

<?php class DocumentNoteCollector extends SQLCollector { }

Find here a sample of an SQL collector definition file.

Then in params.distrib.xml, add the following entries:

  <sql_database>test</sql_database>

  <sql_login>root</sql_login>

  <sql_password>s3cret</sql_password>

  <documentnotecollector_query>SELECT id as primary_key, name, text, description,

status, '2.0' as version, documenttype_id, 1 as org_id FROM

view_DocumentNote</documentnotecollector_query>

  <documentnotecollector_ignored_attributes type="array">

    <attribute>location_id</attribute>

    <attribute>version_id</attribute>

  </documentnotecollector_ignored_attributes>

然后在params.distrib.xml中，添加以下条目：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=10]main.php[/url]
<?phprequire_once(APPROOT.'collectors/DocumentNoteCollector.class.inc.php');
Orchestrator::AddCollector(1 /* $iRank */, 'DocumentNoteCollector');


CSV采集器

“核心”文件夹提供了一个抽象类CSVCollector，它可作为快速创建从CSV文件检索其数据的收集器的基础。

要创建这样的采集器，您需要：

• 创建从CSVCollector派生的类
• 为数据同步源创建json定义文件
• 添加配置参数（在params.distrib.xml中）以定义要解析的CSV文件
• 在collectors/main.php中注册您的采集器
  

CSV收集器的参数配置是：

参数	含义	默认价值
collector_class_csv	要为采集器解析哪个PHP类的csv文件。您可以指定此文件的完整路径（（tmppmyfile.csv）或collector_class的相对路径。此采集器是必需的
collector_class_command	CLI命令，用于在采集器解析csv文件之前执行该操作，PHP类是采集器_class。该采集器是可选的
collector_class_encoding	采集器的csv文件编码，其PHP类为collector_class。该采集器是可选的	UTF-8
collector_class_separator	用于csv文件解析的分隔符。该参数是可选的	;

简单CSV采集器的示例

让我们创建一个非常简单的CSV采集器，它复制“ Person”对象（Person类）

由于采集器从基类继承了所有行为，因此采集器的PHP代码很简单：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=11]iTopPersonCsvCollector.class.inc.php[/url]

<?php class iTopPersonCsvCollector extends CSVCollector { }

在这里找到一个收集器定义的示例[ ttps://www.itophub.io/wiki/page?id=extensions%3Asample-collector-csv]CSV[/url]

然后在params.distrib.xml中，添加以下条目：

<?xml version="1.0" encoding="UTF-8"?>
<parameters>
        


<itoppersonjsoncollector_jsonurl>http://localhost/iTop/webservices/rest.php</itoppe


rsonjsoncollector_jsonurl>
        <itoppersonjsoncollector_jsonpost>
                <auth_user>restuser</auth_user>
                <auth_pwd>restuserpassword</auth_pwd>
                <json_data>{"operation": "core/get", "class": "Person", "key":


"SELECT Person WHERE email LIKE '%.com'", "output_fields": "friendlyname, email,


first_name, function, name, id, org_id,phone"}</json_data>
                <version>1.3</version>
        </itoppersonjsoncollector_jsonpost>
        <itoppersonjsoncollector_way>objects/*/fields</itoppersonjsoncollector_way>
        <itoppersonjsoncollector_fields>
                <primary_key>id</primary_key><!-- also this is not a field of the


itop object, that column is mandatory -->
                <name>name</name>
                <status>status</status>
                <first_name>first_name</first_name>
                <email>email</email>
                <phone>phone</phone>
                <mobile_phone>mobile</mobile_phone>
                <function>function</function>
                <employee_number>employee_number</employee_number>
                <org_id>org_id</org_id>
        </itoppersonjsoncollector_fields>
        <itoppersonjsoncollector_defaults>
                <org_id>Demo</org_id>
                <status>active</status>
        </itoppersonjsoncollector_defaults>
        <json_placeholders>
                <!-- For compatibility with the version 1.1.x of the collector,


define the data table names as following:
             <prefix></prefix>
             <persons_data_table>synchro_data_PersonAD</persons_data_table>
             <users_data_table></users_data_table>
              -->
                <prefix>$prefix$</prefix>
                <persons_data_table>synchro_data_person</persons_data_table>
        </json_placeholders>
</parameters>

最后，在collectors/main.php中添加以下行：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=13]main.php[/url] <?phprequire_once(APPROOT.'collectors/iTopPersonCsvCollector.class.inc.php');Orchestrator::AddCollector($index++, 'iTopPersonCsvCollector');


JSON采集器

“核心”文件夹提供了一个抽象类JSONCollector，它可以用作快速创建从JSON文件检索其数据的收集器的基础。

要创建这样的采集器，您需要：

• 创建从JSONCollector派生的类
• 为数据同步源创建json定义文件
• 添加一个配置参数（在params.distrib.xml中）以定义要解析的JSON文件
• 在collectors/main.php中注册您的采集器
  

JSON收集器的参数配置是：

参数	含义
jsonflie	定义要解析的采集器的json文件的相对或绝对路径，该PHP类是采集器collector_class。此采集器或collector_class_jsonurl是强制性的
jsonurl	要为采集器解析哪个php类的json文件的URL。此参数或collector_class_jsonpath是必需的
jsonpost	带有URL的参数Xml用来获取Json文件<name_of_param>价值<< name_of_param>
command	CLI命令，用于在采集器（其PHP类为collector_class）解析json文件之前执行。该采集器是可选的
path	在json分隔符中找到数据到动态的方法是，并且*用示例aaabb替换{“ aa”：{“ bb”：{mydata}，“ cc”：“ xxx”}和aaa * bb替换任何单词aa“：{cc”：{“ bb”：{mydata1}}，“ dd”：{“ bb”：{mydata2}}}
fields	xml女巫描述json中的名称与itop中的名称之间的连接<name_in_json> name_in_itop << name_in_json>

一个简单的JSON采集器的示例

让我们创建一个非常简单的JSON采集器，它将“ Person”对象（类Person）从一个iTop复制到另一个

由于采集器从基类继承了所有行为，因此采集器的PHP代码很简单：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=14]ITopPersonJsonCollector.class.inc.php[/url]

<?php class ITopPersonJsonCollector extends JsonCollector { }

JSON定义文件是

ITopPersonJsonCollector.json

然后在params.distrib.xml中，添加以下条目：

<?xml version="1.0" encoding="UTF-8"?>

<parameters>

        

<itoppersonjsoncollector_jsonurl>http://localhost/iTop/webservices/rest.php</itoppe

rsonjsoncollector_jsonurl>

        <itoppersonjsoncollector_jsonpost>

                <auth_user>restuser</auth_user>

                <auth_pwd>restuserpassword</auth_pwd>

                <json_data>{"operation": "core/get", "class": "Person", "key":

"SELECT Person WHERE email LIKE '%.com'", "output_fields": "friendlyname, email,

first_name, function, name, id, org_id,phone"}</json_data>

                <version>1.3</version>

        </itoppersonjsoncollector_jsonpost>

        <itoppersonjsoncollector_way>objects/*/fields</itoppersonjsoncollector_way>

        <itoppersonjsoncollector_fields>

                <primary_key>id</primary_key><!-- also this is not a field of the

itop object, that column is mandatory -->

                <name>name</name>

                <status>status</status>

                <first_name>first_name</first_name>

                <email>email</email>

                <phone>phone</phone>

                <mobile_phone>mobile</mobile_phone>

                <function>function</function>

                <employee_number>employee_number</employee_number>

                <org_id>org_id</org_id>

        </itoppersonjsoncollector_fields>

        <itoppersonjsoncollector_defaults>

                <org_id>Demo</org_id>

                <status>active</status>

        </itoppersonjsoncollector_defaults>

        <json_placeholders>

                <!-- For compatibility with the version 1.1.x of the collector,

define the data table names as following:

             <prefix></prefix>

             <persons_data_table>synchro_data_PersonAD</persons_data_table>

             <users_data_table></users_data_table>

              -->

                <prefix>$prefix$</prefix>

                <persons_data_table>synchro_data_person</persons_data_table>

        </json_placeholders>

</parameters>

最后，在collectors/main.php中添加以下行：

[ ttps://www.itophub.io/wiki/page?do=export_code&id=extensions%3Aitop-data-collector-base&codeblock=16]main.php[/url]
<?php
require_once(APPROOT.'collectors/ITopPersonJsonCollector.class.inc.php');
Orchestrator::AddCollector($index++, 'ITopPersonJsonCollector');


高级收藏家

采集器框架为现实的收集器提供了执行一些高级处理的方法：

• 用于可配置数据规范化的DataMapping
• 基于多个字段的高级对帐的LookupTable
  

数据映射

由库存脚本收集的原始数据有时需要进行规范化，然后才能导入iTop，以便获得同质的数据。该框架提供了用于执行简单规范化任务的帮助程序类MappingTable。

映射表（在params.xxx.xml配置文件中）配置为模式的有序列表，并且每个模式都关联有价值。映射表返回的“干净”价值是与匹配输入价值的第一个模式相关联的价值。模式表示为正则表达式。值可以使用占位符来引用匹配模式的某些部分（％1 $ s是整个模式，％2 $ s是常规价值中的第一组，等等）。

配置的示例（品牌标准化）：

<brand_mapping type="array">

    <!-- Syntax /pattern/replacement where:

      any delimiter can be used (not only /)

      but the delimiter cannot be present in the "replacement" string

      pattern is a RegExpr pattern

      replacement is a sprintf string in which:

          %1$s will be replaced by the whole matched text,

          %2$s will be replaced by the first matched group, if any group is defined

in the RegExpr

          %3$s will be replaced by the second matched group, etc...

    -->

    <pattern>/IBM/IBM</pattern>

    <pattern>/Hewlett.Packard/Hewlett-Packard</pattern>

    <pattern>/Dell/Dell</pattern>

    <pattern>/.*/%1$s</pattern>

  </brand_mapping>

此示例文件执行以下规范化：

• 每个包含“ IBM”的字符串都将转换为“ IBM”，
• 每个包含“ Hewlett”，后跟任何字符和“ Packard”的字符串都将转换为“ Hewlett-Packard”，
• 每个包含“ Dell”的字符串都将转换为“ Dell”，
• 所有其他字符串保持原样。
  

在代码中使用映射表

• 创建MappingTable类的实例，并将其传递给XML标签的名称，以在其中查找其配置（在XML param文件内部）
• 根据需要使用MapValue方法对每个价值进行流程处理（当在映射表中找不到匹配项时，第二个参数是默认的价值）。
  

用法示例：

// Turns the raw brand string ('brand_id') into a normalized brand // Use 'Other' for brands not found in the normalization table class TestCollector extends SQLCollector { protected $oBrandMapping; public function Prepare() { $bRet = parent::Prepare(); // Create the MappingTable once at the initialization of your collector $this->oBrandMapping = new MappingTable('brand_mapping'); return $bRet; } public function Fetch() { $aData = parent::Fetch(); if ($aData !== false) { // Then process each collected brand $aData['brand_id'] = $this->oBrandMapping->MapValue($aData['brand_id'], 'Other'); } return $aData; } }

高级查找

嵌入在iTop中的数据同步机制无法执行基于多个字段的协调（例如，基于品牌名称和模型名称搜索模型）。 LookupTable类为任何数量的字段提供此协调模型。

LookupTable类通过检索一组iTop对象的指定字段并将对象的结果标识符存储在iTo&#8203;&#8203;p中来构建查找表。

通过指定OQL查询（要检索的iTop对象的集合）和将用于映射的对象的字段来创建LookupTable的实例。

在创建LookupTable实例期间指定的字段列表（和顺序）是稍后执行Lookup（…）时要传递的字段列表。

初始化LookupTable后，对Lookup（$ aData，array（Field1，Field2，…），desield）方法的调用将在$ aData中用iTop对象的标识符替换desield列的价值，其指定字段与值在$ aData中作为字段Field1，Field2…传递。

从版本1.0.6开始，如果未找到相应的查找，则Lookup方法将返回false。在这种情况下，代码可以供应的默认价值抛出IgnoredRowException异常，以告知采集器拒绝所收集的数据的整个行。

从版本1.1.4开始，LookupTable的构造函数接受一个额外的（可选）参数：$ bIgnoreMappingErrors（默认为false）。如果将此参数设置为true，则LookupTable将认为查找错误是正常的，并且不会报告将其作为警告（但仍在调试模式下列出）。当Lookuptable用于根据iTop中定义的目录过滤收集的数据时，这很有用。在这种情况下，查找错误是预期的行为。

例

在iTop中，运行中的系统版本表示为版本OS家族上的版本依赖。 iTop中可以包含以下对象：

• Windows 7.0和8.1版，
• Debian版本12.0.0。
  

它将存储在iTo&#8203;&#8203;p中，如下所示：

对象类	id	名称
OSFamily	1	视窗
OSFamily	2	Linux Debian
对象类	id	osfamily_id	名称
操作系统版本	1	1	7.0.0
操作系统版本	2	1	8.1.0
操作系统版本	3	2	12.0.0

现在，让我们想象一下，我们的采集器脚本为我们提供了两个信息：“ Windows”和“ 8.1.0”。我们可以将“ Windows”文本字符串存储在数据同步表的“ osfamily_id”字段中，并配置同步数据源以基于“名称”执行对帐（这将正确地将“ Windows”替换为1）。

但是要检索Windows的版本8.1.0的标识符（在我们的示例中为2），我们需要OS家族（“ Windows”）和版本号（“ 8.1.0”）。同步版本源无法执行此复合查找，而LookupTable才起作用。

$oOSVersionLookup = new LookupTable('SELECT OSVersion', ('osfamily_id_friendlyname', 'name'));

这将构建-在内存中-下表：

lookup_key	id
Windows_7.0.0	1
Windows_8.1.0	2
Debian_12.0.0	3

因此，如果我们在$ aData中具有以下值：

osfamily_id	osversion_id
Windows	8.1.0

致电：

$oOSVersionLookup->Lookup($aData, ('osfamily_id', 'osversion_id'), 'osversion_id', 0);

将查找结果$ aData ['osfamily_id']和$ aData ['osversion_id']的结果放入“ osversion_id”列。

$ aData将包含以下值：

osfamily_id	osversion_id
Windows	2

然后，我们必须配置同步数据源，以便它按原样接受oversion_id，而无需对其进行任何协调。

Lookup（...）的最后一个参数必须包含正在处理的CSV文件中的行号。在内部使用它仅在处理文件的第一行时执行一次初始化。

高级协调通过在数据集合之后但在将数据推到iTop之前（通过RESTTJSON API）检索要与组合键匹配的对象来进行。因此，为了使用此高级查找机制，必须告知框架采集器必须在实际数据之前重新处理收集的数据。这是通过重载采集器的

MustProces/BeforeSynchro方法来实现的；然后返回true。

采集器框架提供了两个可以重载的其他方法：

• 在数据收集之后但在开始重新处理收集的数据的每一行之前，将调用InitProces/BeforeSynchro。这是在其中创建LookupTable实例的地方
• 对收集的数据的每一行（包括CSV文件的标题行，索引为零）调用ProcessLineBeforeSynchro。
  

使用范例

以下代码片段显示了使用表的全部情况：一种用于品牌+模型，一种用于OS家族+ OS版本。

数据模型的变体

目标数据模型可能会发生一些变化（安装过程中选择的模块上的依赖）。如果某些配置中缺少给定的属性，则可以通过重载AttributeIsOptional方法来告诉采集器接受这种变化。 （这比为每种组合编写特定的采集器更为简单）。

如果缺少同步数据Source的JSON定义中指定的属性，除非属性声明为可选，否则处理将以错误停止。在后一种情况下，跳过的属性的名称记录在受保护的成员变量$ this-> aSkippedAttributes中，然后继续处理。属性的代码以后可以检查数组$ this-> aSkippedAttributes的内容，以确定是否必须收集哪些字段。

AttributeIsOptional的实施的示例作为VirtualMachineCollector类的方法：

故障排除

对协调机制进行故障排除时，将库存脚本报告的原始（原始）值与协调流程的结果进行比较非常有用。只要采集器的MustProcessBeforeSynchro方法返回true，框架就会在数据子目录中生成两个文件。通过比较两个CSV文件，您可以轻松地在查找之前比较这些值：

• <collector_name>.raw-<index>.csv: ：由库存脚本生成的原始数据，
• <collector_name>-<index>.csv: 重新处理的数据，将上传到iTop。