自定义 Operator Advisor > 在查询服务中使用 JSON 筛选器
在查询服务中使用 JSON 筛选器
Operator Advisor 支持在查询服务中使用 JSON 筛选器。本节介绍如何在使用了可选 filter 输入参数的任意 Operator Advisor 服务中使用这些 JSON 筛选器。
受支持的键和运算符
支持在 JSON 筛选器中使用以下键和运算符：
• select
• filters，具有以下 type 值 (逻辑运算符)：
◦ EQ - 等于
◦ NE - 不等于
◦ LT - 小于
◦ LE - 小于等于
◦ GT - 大于
◦ GE - 大于或等于
◦ AND - 与
◦ OR - 或
◦ IN - 包含
• sorts
◦ isAscending - 如果为 true，则升序排序，如果为 false，则降序排序
◦ isCaseSensitive - 如果为 true，则为区分大小写排序
• joins，具有以下 type 值 (连接类型)：
◦ INNER
◦ LEFT
◦ RIGHT
◦ FULL
• dataShapeName - 列 (fieldName) 所在数据形状的名称
• fieldName - 数据形状中的列名
• value 或 values - 数据库中的一个或多个相关值
选择
在 select 键中，可以从由查询返回的特定数据形状中选择特定字段。构造一个 JSON 数组，其中每个对象对于查询返回的字段指定 dataShapeName 和 fieldName。dataShapeName 可以是主要数据形状 (执行服务所针对的数据形状) 的名称，也可以是通过连接包含在查询中的另一个数据形状的名称。
例如，以下 select 键可用于 GetJobOrders 服务的 JSON 筛选器，以返回作业单处理资源需求的名称、作业单的名称和 ID，以及处理资源的名称：
"select": [
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name"
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name"
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "ID"
},
{
"dataShapeName": "PTC.SCA.SCO.ProcessingResource",
"fieldName": "Name"
}
]
在前面的示例中，PTC.SCA.SCO.JobOrderProcessingResourceRequirement 和 PTC.SCA.SCO.JobOrder 的 Name 字段都是已添加到数据形状的附加属性。
筛选器
filters 键允许您筛选符合特定值的记录的查询结果。可通过构建名为 filters 的 JSON 数组将多个筛选器串在一起，各个筛选器之间用逗号分隔，并通过 AND 或 OR 运算符对其进行连接。每个筛选器指定一个 dataShapeName、fieldName、type 以及 value 或 values (用于 IN 运算符)。然后必须在另一个 filters 键下将多个筛选器分成一组。
dataShapeName 可以是主要数据形状 (执行服务所针对的数据形状) 的名称，也可以是通过连接包含在查询中的另一个数据形状的名称。如果未对筛选器指定 dataShapeName， 则假定正在对该数据形状执行服务。
例如，以下 filters 键可用于 GetHistoricalData 服务的 JSON 筛选器，以返回创建或更新作业单的历史数据数据库表中的所有结果：
"filters": {
"filters": [
{
"dataShapeName": "PTC.SCA.SCO.HistoricalData",
"fieldName": "DataShapeName",
"type": "EQ",
"value": "PTC.SCA.SCO.JobOrder"
},
{
"dataShapeName": "PTC.SCA.SCO.HistoricalData",
"fieldName": "ReferenceKey",
"type": "IN",
"values": [1,2]
}
],
"type": "AND"
}
排序
sorts 键用于根据特定的数据形状字段 (dataShapeName 和 fieldName) 对查询结果进行排序，排序可以是升序或降序 (isAscending)，并可控制筛选器是否区分大小写 (isCaseSensitive)。您可以包括数组中的多个排序对象 (以逗号分隔) 来对多个字段进行排序。
dataShapeName 可以是主要数据形状 (执行服务所针对的数据形状) 的名称，也可以是通过连接包含在查询中的另一个数据形状的名称。如果未指定 dataShapeName，则假定正在对该数据形状执行服务。
例如，以下 sorts 键可用于 GetJobOrders 服务的 JSON 筛选器，以按作业单处理资源需求的名称对结果进行升序排序，然后按作业单名称进行降序排序 (假定作业单处理资源需求通过连接包括在查询中)。
"sorts":[
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name",
"isAscending": true,
"isCaseSensitive": false
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name",
"isAscending": false,
"isCaseSensitive": false
}
]
连接
连接用于根据数据形状之间的相关字段，将两个或多个数据形状中的行组合在一起。要在选择、排序或筛选键中使用有关数据形状的字段，请通过连接将这些数据形状 (而非主要数据形状) 包括在查询中。
每个连接都由连接类型 (type)、源或左侧数据形状和字段名称 (sourceDataShapeName 和 sourceFieldName)、目标或右侧数据形状和字段名称 (targetDataShapeName 和 targetFieldName) 组成。支持以下类型的连接：INNER、LEFT、RIGHT 和 FULL。
• INNER - 内连接返回在两个数据形状中都具有匹配值的所有记录。
• LEFT - 左连接返回左侧 (源) 数据形状中的所有记录和右侧 (目标) 数据形状的匹配记录。如果没有匹配项，则连接的右侧 (目标) 结果为 NULL。
• RIGHT - 右连接返回右侧 (目标) 数据形状中的所有记录和左侧 (源) 数据形状的匹配记录。如果没有匹配项，则连接的左侧 (源) 结果为 NULL。
• FULL - 完全连接返回左侧 (源) 和右侧 (目标) 数据形状中存在匹配项的所有记录。
例如，以下 joins 键可用于 GetJobOrders 服务的 JSON 筛选器，以返回所有符合以下条件的记录：作业单的 UID 匹配作业单处理资源需求的 JobOrderUID 字段，并且作业单处理资源需求的 ProcessingResourceUID 字段匹配处理资源的 UID 字段。
"joins": [
{
"type": "INNER",
"sourceDataShapeName": "PTC.SCA.SCO.JobOrder",
"sourceFieldName": "UID",
"targetDataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"targetFieldName": "JobOrderUID"
},
{
"type": "INNER",
"sourceDataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"sourceFieldName": "ProcessingResourceUID",
"targetDataShapeName": "PTC.SCA.SCO.ProcessingResource",
"targetFieldName": "UID"
}
]
JSON 筛选器示例
以下示例显示了用于 GetHistoricalData 服务的筛选器。此筛选器返回历史数据数据库中创建作业单的所有结果，然后按照每个作业单的创建时间对结果进行升序排序。
{
"filters": {
"filters": [
{
"dataShapeName": "PTC.SCA.SCO.HistoricalData",
"fieldName": "DataShapeName",
"type": "EQ",
"value": "PTC.SCA.SCO.JobOrder"
},
{
"dataShapeName": "PTC.SCA.SCO.HistoricalData",
"fieldName": "ReferenceKey",
"type": "EQ",
"value": 1
}
],
"type": "AND"
},
"sorts": [
{
"fieldName": "TimeStamp",
"isAscending": true,
"isCaseSensitive": false
}
]
}
以下示例显示了用于 GetJobOrders 服务的筛选器。使用此筛选器：
• 对于每个结果，返回作业单的 Name 和 ID、相关工艺资源的 Name 以及相关作业单工艺资源需求的 Name。
• 仅对 WC1 值为 ID 的工艺资源筛选结果。
• 返回的结果是满足以下条件的记录：作业单的 UID 匹配作业单工艺资源需求的 JobOrderUID 字段，并且作业单工艺资源需求的 ProcessingResourceUID 字段匹配工艺资源的 UID 字段。
• 结果按作业单工艺资源需求的 Name 升序排序，然后按作业单的 Name 降序排序。
* 
在本示例中，PTC.SCA.SCO.JobOrderProcessingResourceRequirement 和 PTC.SCA.SCO.JobOrder 的 Name 字段都是已添加到数据形状的附加属性。要如示例所示使用此筛选器，必须将这些字段添加到数据形状中。
{
"select": [
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name"
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name"
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "ID"
},
{
"dataShapeName": "PTC.SCA.SCO.ProcessingResource",
"fieldName": "Name"
}
],
"filters": {
"filters": [
{
"dataShapeName": "PTC.SCA.SCO.ProcessingResource",
"fieldName": "ID",
"type": "EQ",
"value": "WC1"
}
],
"type": "AND"
},
"joins": [
{
"type": "INNER",
"sourceDataShapeName": "PTC.SCA.SCO.JobOrder",
"sourceFieldName": "UID",
"targetDataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"targetFieldName": "JobOrderUID"
},
{
"type": "INNER",
"sourceDataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"sourceFieldName": "ProcessingResourceUID",
"targetDataShapeName": "PTC.SCA.SCO.ProcessingResource",
"targetFieldName": "UID"
}
],
"sorts":[
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name",
"isAscending": true,
"isCaseSensitive": false
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name",
"isAscending": false,
"isCaseSensitive": false
}
]
}
有关在查询中使用筛选器的其他示例，请参阅 ThingWorx 帮助中心内的 查询服务的查询参数。注意 - Operator Advisor 不支持该主题中讨论的 Near 和 NotNear 筛选器。