Composer中的ThingWorx模型定义—建模

2024-04-12 08:43:26


1. 建模

模型是物理和解决方案环境的逻辑表示。它通过一组 REST API 来表现，这使得该模型易于使用。 事物中的各个 API 为您和您的合作伙伴创建的应用程序提供了句柄。构建模型的过程类似于面向对象的设计。您可以分解您的事物，定义它们的交互，并定义要向应用程序开发人员公开的 属性、 服务和 事件。

ThingWorx模型

在ThingWorx中构建IoT解决方案始于以事物为中心的解决方案，其中，事物是创建模型的关键部分。

ThingWorx模型是表示过程、解决方案和/或应用程序的实体的集合。

实体是在 ThingWorx 中创建和维护的*对象。

1.1 项目

项目用于组织 ThingWorx 内的实体。在项目中收集的实体可以一起导出或导入。实体只能属于一个项目

【创建项目】

详细操作以及注意事项

1.2 事物

事物是对物理设备、资产、产品、系统、人员或具有属性和业务逻辑的流程的表示。所有事物均基于 事物模板 (继承)，并且可以实现一个或多个 事物形态 (组合)。最佳做法是创建用于描述事物的事物模板，然后创建此事物模板的实例作为事物。这种做法充分利用模型中的继承，并减少了维护和更新模型所花费的时间。

事物可以有其自己的属性、服务、事件和订阅，且可以从其事物模板和事物形态继承其他属性、服务、事件和订阅。如何对相互关联的事物、事物模板和事物形态进行建模是使您的解决方案在物理资产发生变化时易于开发和维护的关键。最终用户将与事物相连接以获取应用程序中的信息以及读取/写入数据。

远离 ThingWorx 并通过网络 (Intranet/Internet/WAN/LAN) 访问的设备或数据源由远程事物表示。

定义了模型将要包含的事物类型 (使用事物形态和事物模板) 后，便可以开始创建特定的事物实例。

在卡车示例中，您可以为车队中的每辆卡车定义一个卡车事物实例。每个实例将跟踪与其自身相关的信息，并共享该信息以用于您的应用程序、报告和混搭。对于制造商，可以根据您的使用情况为每台计算机、工作中心或制造单位创建一个事物实例。资产管理、产品跟踪和数据收集的细化度会影响您对设备建模的方式。

1.2.1 命名实体

在 ThingWorx 中创建的所有实体都必须拥有一个名称。在**模型中命名实体的规则**：

  • 名称在同一个实体类型中必须是唯一的；但是，它们在不同的实体类型中可以是相同的。例如，您的事物和事物形态可以同名，但您的数据表和事物则不可同名。
  • 名称区分大小写
  • 名称不能超过255个字符

在 ThingWorx 中，实体中的**“说明”**字段无字符限制。

  • 名称不能包含特殊字符，如：+ / < > : * "

通常，支持UTF-8字符。

  • 允许使用连字符、空格和句点，但不能位于名称的开头或结尾。允许下划线出现在名称的任何位置。
  • 名称中不能连续使用多个空格。
  • 名称不能为保留关键字 “me”。
  • 用户名是特殊情况，因为您可以使用电子邮件地址。
1.2.2 事物事件

事件是“事物”发布给订阅者的有趣或重要属性状态。它们是用于启动 订阅中某项功能的启动器，所述功能基本上为触发式服务。

在服务定义中，如果双击事件，则系统会在为你提供服务中排除出发该事件所需的脚本。触发器是资产或系统（事物）的明确状态变化（例如电动机过热），通常需要执行操作来更正或响应变化（例如显示警告灯以表明割草机过热）。来自分析算法的复杂预测可触发事件，并允许应用程序开发人员调用业务逻辑对这些事件做出反应。

ThingWorx 应用程序中的业务逻辑和操作由事件驱动。

事件可以是来自计算机的简单新数据值，也可以是来自多个数据点及其依赖项中的较复杂事件。例如，ThingWorx Analytics实时评分可预测故障并触发IoT运行时引擎事件，以便执行操作。

事件可以通过应用程序中用户的API请求触发，或者设备可以基于本地数据分析或诊断例程来触发其自身的事件。

==模型中应存在事件的订阅者。==向订阅者发送数据包，然后启动订阅。如果无人订阅事件 (无人侦听)，则不执行任何操作。

ThingWorx 中有标准事件和相关数据包 (如 数据形状所定义)。最常见的事件类型为与事物属性相关的数据更改。定义属性时，将有多个配置特性。例如，仅当数据已更改，仅当数据的计算值为 true 或 false，或仅当更改的新值超出定义的阈值时，才可以在为属性提供了新数据时使用 DataChangeEvent 设置要触发的事件。

所有数据更改事件都会发送一个具有相同预定义数据形状的数据包。

可以在模型中创建自定义事件。例如，可以使用一台计算机来运行诊断检测。当诊断检测确定计算机需要校准时，可以为该类设备创建自定义校准警报（通常在“事物形态”或“事物模板”级别）。在定义中，可以创建一个数据形状，其中包括执行操作时所需的计算机中的数据。可以将计算机代理配置为在检测到条件时通过ThingWorx API触发该事件。在订阅中，可以通过实现业务逻辑来响应事件。还可以通过标准的 ThingWorx REST API 触发事件，以便混搭和自定义应用程序可以通过 ThingWorx Analytics 触发事件。

ThingWorx Analytics 可以检查数据并找出异常行为，也可以通过历史数据进行训练。它可以使用 ThingWorx 中的实时数据来预测结果。预测分析即为一个基本的示例。可以根据历史数据 (包括故障信息) 来训练一类设备的分析引擎。可以将单个事物的运行时数据发送到分析引擎。如果它检测到导致过去某一故障的模式，则会触发该事物的事件，并允许您通过订阅来执行操作。该操作可能是创建服务票证或者向服务部门发送通知。对自定义事件的警报或订阅允许您将特定的操作和业务逻辑链接到接近实时的事件。

1.2.3 事物属性

事物属性用于描述与事物相关的数据点。例如，客户可能具有名称属性和地址属性；卡车可能具有下列属性：驾驶员、容量和位置。

属性时了解事物当前状况的一种简便方法。属性可以是静态的（例如制造商和型号），也可以是动态的（例如温度）。可以根据资产结构、业务流程以及要交付的解决方案来设置属性。

创建属性时，可以选择下列几种属性之一：

• My Property

本地事物的属性，这是默认设置。

• Local Bound

将该属性链接到 ThingWorx 服务器上针对其他事物定义的属性。可以将此属性设置为只读，而它仍然可以接收来自服务器上另一个属性的值。此属性不会用于远程设备，除非您正在创建远程绑定属性的本地绑定。

• Remote

当远程设备首次连接到 ThingWorx 服务器时，服务器会将远程设备绑定到其相应的事物。远程设备绑定后，您需要在该远程设备上定义的每个属性和 ThingWorx 中表示该设备的远程事物之间创建一个远程绑定。ThingWorx 使用此绑定来通过活动的 WebSocket 连接向远程设备发送和接收来自远程设备的每个属性值的更新。

每个属性都有一个名称、说明和一个 ThingWorx 数据类型，在 ThingWorx 中称为**“基本类型”**。根据基本类型，可能会启用其他字段。简单标量类型 (如数字或字符串) 会添加基本字段 (如默认值)。更复杂的基本类型会有更多选项。例如，信息表基本类型包括通过定义数据形状来描述信息表数据结构的功能。

（1）特性

属性可具有下列特性设置：

  • “持久化”

    如果选中或设置为true，则每个值更改都会持久保存到数据库中。

    持久化属性数据库写入以异步的形式发生，以避免出现死锁。当设置属性立即发生时，数据库写入会在稍后的时间点以异步形式发生。在持久化属性值写入到数据库之前，会出现以下验证：

    1. 事物必须仍然存在；
    2. 事物必须有一个id;
    3. 事物id和待处理写入id必须匹配
    4. 事物必须仍然定义与待处理写入同名的属性
    5. 定义的属性必须仍为持久化属性

    更新并重新启动不会影响队列处理。

  • “只读”

    如果选中或设置为true，则数据是静态的，无法在运行时写入。要对值进行更改，唯一方法是更改默认值。这对静态配置数据很有用。

  • “已记录”

    如果选中或设置为true，则在数据更改时（基于数据更改类型），该属性值会自动记录到值流中。

（2）数据更改信息

“数据更改类型”

此设置指定何时通过属性值更改来触发数据更改事件。当需要根据属性的值启动其他进程时会用到此设置。每个订阅者都会收到一个更改通知以及一个包含旧属性值和新属性值的信息表。例如，您可能需要为 Delivery Schedule属性的更改设置订阅。如果计划发生变化，可以通过短信通知驱动程序。

“数据更改类型”选项如下所示：

• “始终”：针对任何属性值更改都会触发订阅者事件。

• “从不”：不会触发更改事件。

• “开启”：对于大多数值，任何更改都将触发事件。对于更为复杂的基本类型 (如信息表)，事件规则可能会有所不同。

• “关闭”：如果新值的计算结果为布尔值 false，则触发事件。

• “值”：对于数字而言，如果新值的更改超过了阈值，则触发更改事件。阈值使用 dataChangeThreshold 特性 (一个数字) 进行指定。对于非数字而言，此设置的作用与**“始终”**相同。

（3）远程绑定信息

详细介绍

（4）基本类型

详细介绍

1.2.3.1 命名属性

“名称”为必填字段，用于唯一标识属性。

名称区分大小写

不能在名称中包含以下内容：

  • 空格

  • 某些特殊字符

    可以包括 - (连字符)、_ (下划线)、$ (美元符号) 和 @。

    注意：如果持久化属性的名称中包含 @ 或 $ 符号，则无法将包含此属性的实体导出为 XML。

    如果名称中包含连字符，则==名称必须使用括号括起以表示已引用。==在下面的示例中，temp-01 为属性名称：

var result = me['temp-01'];

var result = Things['ThingName’]['temp-01’];

  • 前导数字

    您可以在名称内和末尾使用数字。

1.2.3.2 配置属性提供工具
1.2.3.3 管理属性绑定
1.2.3.4 以编程方式向事物添加属性
1.2.3.5 转换属性
1.2.4 事物服务

事物服务是指事物可执行的功能。每个事物都可以有一个或多个服务。可以在“事物形态”、“事物模板”或“事物”级别定义服务。服务的一个简单示例是为数据库事物编写的查询。

对于服务而言，有几种实现方法或处理程序，具体取决于所使用的模板。

处理程序的示例包括脚本、SQL 查询和 SQL 命令。根据事物 (例如 Edge 事物) 的特定功能，还可以使用其他处理程序。

用户定义服务的具体实现是通过服务器端脚本（目前通过SQL或JavaScript）完成的。然后，可以通过 URL、REST 客户端支持的应用程序或 ThingWorx 中的其他服务调用该服务。

创建新服务时，可以定义输入属性和输出。输入和输出可以是任何标准ThingWorx数据类型。每个服务还可以在服务定义中定义单独的运行时权限。服务不必包含输入和输出，但通常存在其中的一个或两者都存在。

例如，如果要将交付计划发送到卡车，那么卡车事物可能会有一个服务，其中包含名为DeliverySchedule的输入且类型为XML。该服务可以接收传入的数据并将卡车的事物属性放入数据表中。

如果想要将输出直接发送到混搭小组件，则应选择INFOTABLE类型的输出；

如果选择输出信息表，则需要选择数据形状（Data Shape）； 应用程序利用数据形状确定将返回哪些列和数据类型，以便用其显示数据。

你也可以视需要选择任意数量的输入。例如，您的输出可以是针对数据返回到混搭的数据库所执行的SQL查询。该服务会自动成为ThingWorx应用程序服务器的REST API的一部分（与您模型中的所有定义相同）。可以通过来自其他应用程序或混搭中的REST调用来使用该服务。

调用服务时，如果将输出定义为信息表，则可以使用URL调用和Accept URL参数来请求HTML、JSON 或 XML 形式的结果集 (有关详细信息，请参阅 REST API)。由于这种灵活性，以及混搭环境能够轻松使用信息表，建议您使用此格式作为默认设计模式。可根据需要解决特定需求，如 XML 架构输出。

定义了脚本函数接口后，您便可以通过单击该服务的==“处理程序”列==来实现该服务。这会使您转至服务实现编辑器。在实现编辑器中，请选择处理程序（SQL查询或脚本）。SQL查询仅适用于数据库实体。脚本实现是服务器端Java脚本引擎。

借助SQL查询，您只需使用通常用于源数据库的语法编写查询即可。可以使用服务输入作为查询中的参数，就像使用预处理语句一样。如果输出属性是一个信息表，则不需要操控结果。查询结果将显示在信息表中，并作为输出提供。

脚本处理程序是利用服务器上所有数据、事物和服务来满足应用程序需求的一种强大方式。可以执行计算和查找、调用服务或从模型中的其他事物访问属性。选择将脚本作为处理程序后，便会看到多个脚本帮助程序。可以看到当前所编辑事物的脚本、属性、服务和事件的输入，可通过双击将其粘贴到脚本窗口中。还可以浏览系统中任何其他实体的属性、服务和事件。可将所有模型功能都组合在您的服务中。

如果脚本是从网页或URL调用的，则它将在已登录用户的上下文中运行。如果用户无权访问脚本中任何实体的运行时服务、属性或事件，则该脚本可能会失败。

默认情况下，ThingWorx 平台上的脚本超时设置为 30 秒。如果脚本运行时间超过此时间限制，则平台会终止执行。ThingWorx 管理员可以在 platform-settings.json 文件的“基本设置”部分配置脚本超时。

异步服务

异步服务将在其自己的线程中创建和执行。它们不能具有返回值，因为当其运行时，将创建线程且该线程会在平台上独立运行。如果从另一个服务中调用，则正在调用的服务不会等待异步服务完成。这对于长时间运行的服务非常有用，尤其是那些更新后台数据结构或执行系统维护任务的计时器上的服务。

如果在“新建服务”编辑器中选择了异步，则会显示“排队调用”选项。此选项适用于远程绑定的服务，如果未连接远程事物，则会对服务执行进行排队。ThingWorx会对每个执行服务尝试进行排队，然后在远程事物重新连接后按顺序执行它们。

1.2.4.1 查询服务的查询参数

多个ThingWorx服务可接受可选查询参数。查询参数为值对象，其配置会根据所请求查询类型的不同而不同。

可能的类型有：

Matches, NotMatches TaggedWith, NotTaggedWith, GT, LT, GE, LE, NE, EQ, LIKE, NOTLIKE, IN, NOTIN
Between, NotBetween MissingValue,NotMissingValue Near, NotNear

查询可以为AND/OR，并且可以包含“排序”

查询参数可用于以Query开头的所有服务

具体服务

配置

查询参数具有两个可配置选项：filters和sorters。定义查询参数后，可以将其传递给查询服务。以下是查询参数的filters和sorters选项的示例。建议在脚本配置器中使用编写脚本工具和片段作为起点，然后根据需要手动创建查询参数对象。

【单一筛选器选项】

  • Matches或NotMatches筛选器

    var query = {
    "filters":{
        "type":"Matches|NotMatcher",
        "fileName":"Source",
        "expression":"(Kettle)|(Filter)"
    }
}

  • 标记或未标记筛选器

    var query = {
    "fieldName": "tags",
    "type": "NOTTAGGED",
    "tags": [
        {
            "vocabulary": "Applications",
            "vocabularyTerm": "Testing"
        },
        {
            "vocabulary": "Plants",
            "vocabularyTerm": "Sedona"
        }
    ]
};

  • 单一比较运算符

    使用 LIKE/NOTLIKE 时需要添加您自己的通配符 (%、* 或 ？ 表示单一字符通配符)。例如，要查找 ThingWorx，可以使用 LIKE Th%

    var query =   
    {
        "filters": {
            "type": "GT, LT, GE, LE, NE, EQ, LIKE, NOTLIKE",
            "fieldName": "Duration",
            "value": "12"
        }
    };

  • In或Not In筛选器

    var jsonArray = [12,14];
var query = {
    "filters": {
        "type": "IN, NOTIN",
        "fieldName": "Duration",
        "values": jsonArray
    }
};

更多筛选器

1.2.4.2 迭代事物的属性
1.2.4.3 服务输入参数

在创建服务时，可以定义输入（和输出）参数。这些参数可以是任何ThingWorx基本类型，并且可以设置为该服务的必填参数，如果将该参数设置为必填参数，则在未提供参数的情况下，服务不会运行。

在混搭中使用服务时，参数在Mashup Builder的数据属性面板中显示未可绑定参数。

服务输入参数命名

详情

1.2.4.4 服务输出结果

服务可以有输出。输出的名称必须是result

输出可以是任何基本类型。通过设置var result = ... ，可在该服务中分配值

如果选择使得输出为信息表基本类型，则必须定义数据形状，否则将无法在混搭中使用输出（尽管Rest API能够提供该信息表）。

如果添加的选项为流或数据表，则ThingWorx也会自动提供时间戳、源、源类型、位置和标记的默认字段。

1.2.4.4 使用诊断追踪服务
1.2.4.5 加密
1.2.5 事物订阅

订阅是接收事件并对事件进行响应的服务。订阅包含源（通常为事物）。事物可以订阅通过某一操作做出响应的事件。例如，如果某个实体触发电动机过热事件，则可通过触发关闭电动机订阅来订阅该事件。事物可以从其使用的事物模板和事物形态继承订阅。

订阅类似于标准服务，但是它与事件显式关联。这样，您便可将事件从对其作出响应的代码中分离出来。像服务一样，您可以实现自定义业务逻辑来对事件作出反应。可以利用模型的功能，方法包括通过邮件服务器事物发送电子邮件、写入数据库或调用平台中可用的任何服务。

订阅不会像服务一样具有显式返回输出，但能够从线程安全上下文可访问的模型中调用任何其他服务。

订阅具有已定义的输入，该输入是由事件发布的数据包，称为事件数据。如果实体订阅了已定义事件，则会将事件数据传递给订阅函数。事件数据由事件数据形状进行描述。在订阅实现中，从事件传递的数据用作脚本函数的输入。例如，如果实体订阅事物属性数据更改事件，则会调用订阅脚本函数，同时会将事物属性值和事件中的其他相关数据一同作为事件数据传递到函数。

多个实体可以订阅同一事件。每个实体可以使用传递的事件数据接收对订阅的调用。为达到解决方案的要求，实体可以采取订阅脚本中的任何所需操作。

与使用从另一服务调用的服务相比，此项技术的优点包括：事件可通过一或多个订阅进行订阅，并根据系统活动调用事件，无需用户交互。如果一个事件应由多个事物订阅，则可以使用订阅而不是链接多个服务。

1.2.6 警报

1.3 事物模板

事物模板提供了事物实例在其执行中所使用的属性、服务、事件和订阅的基本功能。每个事物都是根据事物模板创建的。一个事物模板可以扩展另一个事物模板。在发布产品的新版本时，只需添加版本的附加特征，而无需重新定义整个模型。

【事物形态】

事物形态提供一组特性，这些特性表示为在一组物理资产*享的属性、 服务、 事件和 订阅。事物形态最适合用来组合以描述模型中对象之间的关系。它们可以促进所包含的属性和业务逻辑的重用，且可以由一个或多个事物模板来继承。在ThingWorx中，模型允许事物模板实现一个或多个事物形态，这类似于C++中具有多重继承的类定义。

1.4 数据形状

**数据形状表示模型中的数据。**数据形状是指定的字段定义以及相关元数据的集合。数据形状中的每个字段都具有一种数据类型。ThingWorx提供了一组已定义的基本类型。

数据类型将有助于创建应用程序，因为当您使用数据时，应用程序会根据数据形状定义提供有关如何表示数据集的内置知识。

数据形状适用于许多情况，而并非仅用作流、值流和数据表。当您需要描述数据集时，也可以使用数据形状。例如，当为服务实现定义信息表输出时，您可以使用数据形状来描述输出结果集。您可以拥有信息表类型的事物属性，还可以指定用于描述该属性的数据形状。

信息表—Infotables

信息表是 ThingWorx Platform 中常用的一种数据结构。信息表是显示相同属性的对象所构成的零索引、有序数组。信息表可以用任何编程语言表示。在ThingWorx Platform上，信息表通常用于JavaScript实现中，并且可用于表示服务的输入值和输出值。

由于信息表为对象数组，因此也可将其视为一个电子表格，其中将数组条目作为行，将数组中每个对象的对象属性作为列。在自定义服务或应用程序中使用信息表时，请务必确保每个对象均具有相同的属性，以便表格中的每一列都可以映射到属性值。

数组在JavaScript中的工作原理

ThingWorx允许您使用JavaScript创建自定义服务，其中使用信息表进行输入和输出。如果您曾在JavaScript中使用过数组对象，那么您一定熟悉数组在ThingWorx中的工作原理。

信息表与数组有何不同

JavaScript数组可以包含不同的数据类型，而信息表只能包含一种对象类型。

如何将信息表与服务配合使用

ThingWorx Edge Java SDK提供了一些工具，可用于构造调用服务时所需的信息表。此SDK为展示如何将信息表与服务配合使用提供了基础。

注意：INFOTABLE是ThingWorx基本类型之一。特别是，它属于聚合基本类型。

Service的自变量和返回值是使用字符串、整数、数字和布尔值等基元表示的。信息表可用于描述一组Service自变量。Service参数和返回值可作为包含一行或多行的信息表来传递和接收。

在ThingWorx Edge Java SDK应用程序中使用时，信息表的DataShapeDefinition用于描述表内每个字段的名称、基本类型和其他信息。信息表内的数据包含在行中。每一行都可以有一个或多个字段，由信息表的 DataShapeDefinition 来描述。以下是有关信息表定义及其数据形状和行的示例：

{
    "dataShape":{
        "fieldDefinitions":
        {
            "name":{"name":"name","baseType":"STRING"},
            "phone":{"name":"phone","baseType":"STRING"},
            "age":{"name":"age","baseType":"NUMBER"}
        }
    },
    "rows":[
        {name:"Bill",phone:"609-555-1212",age:20},
        {name:"Iran",phone:"215-555-1213",age:21}
    ]
}

除了将信息表与服务配合使用外，还可以使用信息表来保存事件数据或由多个属性的读取请求所返回的值。信息表可以包含一行或多行。结果返回后，您需要使用getFirstRow()、getSecondRow()等Java SDK 方法从每一行中提取值。也可以使用与字段基本类型相匹配的helper函数，例如getStringValue()

1.5 标记

标记是词汇与特定词汇项的组合。标记将显示为Vocabulary: VocabularyTerm。几乎每个ThingWorx实体都可以进行标记。标记可用于创建多个不同ThingWorx实体之间的关系。

词汇是指用于描述特定概念或事物的单词或标识符的列表。词汇包含多个词汇项。有关词汇的示例，可以是颜色或位置。

词汇项是指用于描述事物或表达概念的单词或短语。有关词汇项的示例，词汇颜色包括红色、蓝色和绿色。对于位置，它可以是制造工厂所在城市的名称。

以编程方式添加标记

可以使用SetTags()和AddTags()服务来添加和编辑标记。

1.6 工业连接

1.7 集成连接器

1.8 通知

作为管理员，您可以使用通知的方式基于事件向ThingWorx用户发送电子邮件或文本消息。

==通知由一个或多个触发器组成。==触发器用于定义哪些用户会收到指定事件的通知以及他们所收到的消息的内容。创建触发器时，您必须定义以下内容：

  • 源

    源实体和导致通知发送的事件。

  • 处理程序

    处理程序是一个实体，用于提供发送通知消息的服务。处理程序定义了可发送内容的类型。

  • 内容

    向用户发送的消息

1.8.1 添加通知

具体操作

上一篇：composer文件简介


下一篇：windows-composer-laravel安装