自訂 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 可以是主要資料形式 (正在執行服務的資料形式) 的名稱，也可以是透過連接包括在查詢中的其他資料形式的名稱。
例如，可以在 GetJobOrders 服務的 JSON 篩選器中使用下列 select 索引鍵，來回傳工作訂單處理資源需求的名稱、工作訂單的名稱與 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 索引鍵可讓您篩選符合特定值的記錄的查詢結果。透過建構名為 filters 的 JSON 陣列，以逗號分隔每個篩選器，並以 AND 或 OR 運算子連接，便可將多個篩選器串聯在一起。每個篩選器指定一个 dataShapeName、fieldName、type 以及一个 value 或 values (針對 IN 運算子)。多個篩選器必須一起放在另一個 filters 索引鍵之下。
dataShapeName 可以是主要資料形式 (正在執行服務的資料形式) 的名稱，也可以是透過連接包括在查詢中的其他資料形式的名稱。如果沒有為篩選器指定 dataShapeName，則假設為正在執行服務的資料形式。
例如，可以在 GetHistoricalData 服務的 JSON 篩選器中使用下列 filters 索引鍵，來回傳其中已建立或更新工作订单之歷史資料資料庫表格中的全部結果：
"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
sorts 索引鍵可讓您根據特定資料形式欄位 (dataShapeName 與 fieldName) 排序查詢結果，以遞增或遞減順序 (isAscending) 排序，並決定篩選器是否區分大小寫 (isCaseSensitive)。您可以透過在陣列中包括多個排序物件 (以逗號分隔) 來排序多個欄位。
dataShapeName 可以是主要資料形式 (正在執行服務的資料形式) 的名稱，也可以是透過連接包括在查詢中的其他資料形式的名稱。如果沒有指定 dataShapeName，則假設為正在執行服務的資料形式。
例如，可以在 GetJobOrders 服務的 JSON 篩選器中使用下列 sorts 索引鍵，來按工作訂單處理資源需求的名稱以遞增順序排序，然後按工作訂單名稱以遞減順序排序 (假設工作訂單處理資源需求透過連接包括在查詢中)。
"sorts":[
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name",
"isAscending": true,
"isCaseSensitive": false
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name",
"isAscending": false,
"isCaseSensitive": false
}
]
連接
連接可用於根據資料形式之間的相關欄位合併兩個或多個資料形式所在的列。欲在 select、sort 或 filter 索引鍵中使用資料形式的欄位，請使用連接將這些資料形式 (主要資料形式除外) 包括在查詢中。
每個連接均由連接類型 (type)、來源 (也就是左側資料形式) 和欄位名稱 (sourceDataShapeName 與 sourceFieldName)，以及目標 (也就是右側資料形式) 和欄位名稱 (targetDataShapeName 與 targetFieldName) 組成。系統支援下列類型的連接：INNER、LEFT、RIGHT 與 FULL。
• INNER - 內部連接會回傳在兩個資料形式中均有相符值的全部記錄。
• LEFT - 左連接會回傳左側 (來源) 資料形式中的全部記錄和右側 (目標) 資料形式中的相符記錄。如果沒有相符記錄，則連接右側 (目標) 的結果是 NULL。
• RIGHT - 右連接會回傳右側 (目標) 資料形式中的全部記錄和左側 (來源) 資料形式中的相符記錄。如果沒有相符記錄，則連接左側 (來源) 的結果是 NULL。
• FULL - 完整連接會回傳左側 (來源) 或右側 (目標) 資料形式中存在相符記錄的全部記錄。
例如，可以在 GetJobOrders 服務的 JSON 篩選器中使用下列 joins 索引鍵來回傳工作訂單的 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。
• 僅針對 ID 值為 WC1 的那些處理資源篩選結果。
• 回傳的結果適用於滿足下列條件的記錄：工作訂單的 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 篩選器。