向数据模型添加自定义实体
向数据模型添加新实体涉及如下多个步骤：
1. 创建新构建基块。
2. 为新实体创建数据形状。
创建新构建基块
要创建新构建基块，请完成以下步骤：
1. 创建一个新项目。为您的项目指定唯一的前缀，例如您的公司名称。对于 PTC 提供的实体，保留 PTC 前缀。在本示例中，创建一个名为 MyCompany.MyBuildingBlock 的项目。对于为此构建基块创建的各个新事物模板、事物或其他实体，将新项目添加为实体“常规信息”页面上的“项目”值。
2. 在您的项目中创建一个新的入口点事物模板。在本示例中，将此新事物模板命名为 MyCompany.MyBuildingBlock.EntryPoint_TT。使用的“基本事物模板”取决于新构建基块的类型：
◦ 如果构建基块从 PTC 构建基块扩展而来，请使用 PTC 构建基块中的入口点事物模板。
事物模板。
3. 在您的项目中创建一个新事物，该事物使用在步骤 2 中创建的事物模板作为其“基本事物模板”。在本示例中，将此新事物命名为 MyCompany.MyBuildingBlock.EntryPoint。
4. 如果构建基块并非从 PTC 构建基块扩展而来，则请在您的项目中创建一个新事物形态，以包含用于管理新实体的服务定义。在本示例中，将此新事物形态命名为 MyCompany.MyBuildingBlock.Managment_TS。如果构建基块从 PTC 构建基块扩展而来，请跳过此步骤。
5. 如果构建基块并非从 PTC 构建基块扩展而来，则在您的项目中创建一个新事物模板，该事物模板使用 PTC.Base.CommonManager_TT 作为其“基本事物模板”。在本示例中，将此新事物模板命名为 MyCompany.MyBuildingBlock.Manager_TT。如果构建基块从 PTC 构建基块扩展而来，请跳过此步骤。
6. 如果构建基块并非从 PTC 构建基块扩展而来，请将步骤 4 中创建的事物形态添加到步骤 5 中所创建事物模板的“实现的事物形态”字段中。如果构建基块从 PTC 构建基块扩展而来，请跳过此步骤。
7. 在您的项目中创建一个新事物，该事物使用在步骤 5 中创建的事物模板作为其“基本事物模板”。在本示例中，将此新事物命名为 MyCompany.MyBuildingBlock.Manager，并使用 MyCompany.MyBuildingBlock.Manager_TT 作为其“基本事物模板”。
8. 如果此新构建基块从 PTC 构建基块扩展而来，则将原始构建基块的管理器事物中的所有配置均添加到此新构建基块的管理器事物中。
a. 导航至在步骤 7 中创建的管理器事物，在本示例中为 MyCompany.MyBuildingBlock.Manager。
b. 在“配置”下，添加在原始构建基块的管理器事物“配置”页面中找到的配置。
9. 注册自定义管理器。
a. 导航至 PTC.Base.Manager 事物。
b. 在“配置”下，单击 DefaultGlobalManagerConfiguration 配置表的“添加”。
▪ 在“名称”中，输入自定义管理器的名称，例如 MyCompany.MyBuildingBlock.Manager。
▪ 在“值”中，搜索并选择在步骤 7 中创建的自定义管理器事物。
c. 单击“添加”将自定义管理器添加到配置表中。
d. 单击“保存”以保存对管理器事物的更新。
为新实体创建数据形状
要为新实体创建数据形状，请完成以下步骤：
1. 在 ThingWorx Composer 中，创建新数据形状。将此数据形状添加到此新构建基块的项目中。在本示例中，将此数据形状命名为 MyObject。
2. 在“字段定义”下，单击“添加”，并为要包括在此数据形状中的每个属性指定新的字段定义。
a. 通过选择该字段的“是主键”复选框，将某个字段指定为主键。
b. 将主键字段的“基本类型”设置为 LONG。如果主键字段为 LONG 数据类型，则系统会自动生成该字段的值，且用于递增该值的逻辑将由数据库负责处理。如果选择了不同的“基本类型”，则您必须亲自处理该逻辑以确保主键的唯一性。
要与构建基块数据模型保持一致，请添加一个“基本类型”为 LONG 的 UID 字段，同时选中“是主键”复选框。
3. 单击“保存”以保存新数据形状。
 |
为数据形状创建数据库表时，数据库表名称为数据形状名称去掉所有前缀并采用小写形式。例如，如果数据形状被命名为 ABC.MyObject，则数据库表名称为 myobject。由于数据库表名称不包含前缀，因此系统不支持可生成相同数据库表名称的多个数据形状名称，例如 ABC.MyObject 和 PTC.JobOrder.MyObject。
同样，数据库表中的列名称为数据形状中的字段名称，且形式为小写。例如，名为的 MyPrimaryLocation 的字段会生成名为 myprimarylocation 的列。因此，相同的数据形状不支持具有相同字母但大小写不同的字段名称，例如 MyName、myName 和 myname。
|
更新数据库信息以包括新的数据形状
更新数据库信息以包括您的新数据形状。您可以通过将实体的数据库信息添加到此新构建基块的管理器事物 (MyCompany.MyBuildingBlock.Manager) 的 GetDBInfo 服务来完成此操作。
要将新数据形状的数据库信息添加到现有 GetDBInfo 服务：
1. 导航至此新构建基块的管理器事物 (MyCompany.MyBuildingBlock.Manager)。
2. 在“服务”下，导航至 GetDBInfo 服务并进行覆盖。
3. 在脚本编辑器中，类似于现有数据形状条目，将新数据形状的条目添加为数组。包括数据形状的数据库信息：
◦ dataShapeName - 要添加新数据库表的数据形状的名称。
◦ indexedFields - 要建立索引的列。索引有助于提高搜索和排序的速度。可在数组中定义多个索引字段。数组中的每个元素均可以包含以下属性：
▪ name - 列的名称。必填。
▪ unique - 指定列是否必须具有唯一值。
▪ fieldNames - 包含列名称的数组。如果仅指定了一列，则创建单一索引。如果指定了多列，则创建复合索引。
|
|
指定 name，将单个值作为列的名称，而不为 fieldnames 指定单个值，这样可创建单一索引。如果 name 和 fieldnames 均已指定，则 name 将被忽略，并使用 fieldnames 值创建索引。
|
▪ identifier - 数据库中实体的名称。如果尚未指定，则系统会自动以 <表名>_<列名>_idx 格式生成该值。如果已指定，则无论对于指定值，还是任何自动生成的值，该值都必须具备唯一性。该值的最大长度为数据库所允许的最大标识符长度。
◦ fields - 需要某些附加规范的任何列。可在数组中定义多个字段。数组中的每个元素均可以包含以下属性：
▪ name - 列的名称。必填。
▪ length - 列的长度 (列为 String 且所需长度并非数据库默认长度时)。
▪ notNull - 指定列是否不得为空。
▪ defaultValue - 此属性的默认值。
|
|
如果某一列必须具有唯一值，那么请使用 indexedFields 而非 fields 数组中的 unique 指定此部分内容。
|
▪ name - 当前数据形状上要作为外键的列的名称。
▪ referenceDataShapeName - 所引用的数据库表的数据形状。
▪ referenceFieldName - 包含所引用值的字段的名称。
▪ identifier - 数据库中实体的名称。如果尚未指定，则系统会自动以 <表名>_<列名>_fk 格式生成该值。如果已指定，则无论对于指定值，还是任何自动生成的值，该值都必须具备唯一性。该值的最大长度为数据库所允许的最大标识符长度。
▪ onDelete - 所引用数据形状的实例被删除时，当前数据形状的实例会出现何种情况。
▪ deleteReference - 当前数据形状的实例被删除时，所引用数据形状的实例会出现何种情况。
有关删除行为的详细信息，请参阅使用外键设置删除行为。
例如，如果希望新 MyObject 数据形状不具有索引字段，有一个外键，且将 Location 字段的长度设置为 4000 个字符，请输入以下内容：
{
"dataShapeName": "MyObject",
"indexedFields": [],
"foreignKeys": [{"name":"WorkDefinitionUID", "referenceDataShapeName":"PTC.SCA.SCO.WorkDefinition", "referenceFieldName":"UID"}],
"fields": [
{
"name": "Location",
"length": 4000
}
]
}
"dataShapeName": "MyObject",
"indexedFields": [],
"foreignKeys": [{"name":"WorkDefinitionUID", "referenceDataShapeName":"PTC.SCA.SCO.WorkDefinition", "referenceFieldName":"UID"}],
"fields": [
{
"name": "Location",
"length": 4000
}
]
}
4. 相继单击“完成”和“保存”来保存更新的服务。
创建 CRUD 服务
创建管理新数据形状实例所需的 CRUD 服务。
1. 在构建基块管理事物形态 (MyCompany.MyBuildingBlock.Managment_TS) 的“服务”下，单击“添加”，然后创建必需的服务。将构建基块实体的现有 CRUD 服务用作模型。
◦ 创建服务：
▪ 输入服务名称。在本示例中，输入 AddMyObjects。
▪ 对于服务输入，请添加一个名为 MyObjects 且“基本类型”为 INFOTABLE 的输入。对于“数据形状”，请选择数据形状。
▪ 对于服务输出，请选择 INFOTABLE，然后选取您的数据形状。
▪ 在脚本窗格中，输入如下类似代码：
var insertParams = {
infoTable: MyObjects,
dataShapeName: "MyObject"
};
var result = Things[me.GetDatabaseThingName()].Insert(insertParams);
infoTable: MyObjects,
dataShapeName: "MyObject"
};
var result = Things[me.GetDatabaseThingName()].Insert(insertParams);
◦ 删除服务：
▪ 输入服务名称。在本示例中，输入 DeleteMyObject。
▪ 对于服务输入，请添加一个名为 UID 且“基本类型”为 STRING 的输入。
▪ 对于服务输出，请选择 INFOTABLE，然后选取您的数据形状。
▪ 在脚本窗格中，输入如下类似代码：
var params = {
UID: UID,
dataShapeName: "MyObject"
};
var result = Things[me.GetDatabaseThingName()].Delete(params);
UID: UID,
dataShapeName: "MyObject"
};
var result = Things[me.GetDatabaseThingName()].Delete(params);
◦ 更新服务：
▪ 输入服务名称。在本示例中，输入 UpdateMyObjects。
▪ 对于服务输入，请添加一个名为 MyObjects 且“基本类型”为 INFOTABLE 的输入。对于“数据形状”，请选择数据形状。
▪ 对于服务输出，请选择 INFOTABLE，然后选取您的数据形状。
▪ 在脚本窗格中，输入如下类似代码：
var params = {
infoTable: MyObjects,
dataShapeName: "MyObject"
};
var result = Things[me.GetDatabaseThingName()].Update(params);
infoTable: MyObjects,
dataShapeName: "MyObject"
};
var result = Things[me.GetDatabaseThingName()].Update(params);
◦ 用于检索此数据形状的单个实例的服务：
▪ 输入服务名称。在本示例中，输入 GetMyObject。
▪ 对于服务输入，请添加一个名为 UID 且“基本类型”为 STRING 的输入。
▪ 对于服务输出，请选择 INFOTABLE，然后选取您的数据形状。
▪ 在脚本窗格中，输入如下类似代码：
var params = {
UID: UID,
dataShapeName: "MyObject"
};
var result = Things[me.GetDatabaseThingName()].GetEntity(params);
UID: UID,
dataShapeName: "MyObject"
};
var result = Things[me.GetDatabaseThingName()].GetEntity(params);
◦ 一种用于检索此数据形状的多个实例的服务，其中可包括 filter、offset 和 limit 输入参数。如果未指定任何输入参数，则会返回 MyObject 的所有实例：
▪ 输入服务名称。在本示例中，输入 GetMyObjects。
▪ 对于服务输入：
▪ 添加一个名为 filter 且“基本类型”为 JSON 的输入。
▪ 添加一个名为 offset 且“基本类型”为 INTEGER 的输入。
▪ 添加一个名为 limit 且“基本类型”为 INTEGER 的输入。
▪ 对于服务输出，请选择 INFOTABLE，然后选取您的数据形状。
▪ 在脚本窗格中，输入如下类似代码：
var params = {
filter: filter,
dataShapeName: "MyObject",
offset: offset,
limit: limit
};
var result = Things[me.GetDatabaseThingName()].Query(params);
filter: filter,
dataShapeName: "MyObject",
offset: offset,
limit: limit
};
var result = Things[me.GetDatabaseThingName()].Query(params);
2. 单击“保存”以将新服务保存到事物形态。
同步数据库信息和数据库架构
通过同步数据库信息和数据库架构将新实体添加到数据库中。有关详细信息，请参阅同步数据库信息和数据库架构。