Blocs de construction communs > Bloc de construction de connexion de base de données > Utilisation de filtres JSON dans les services de requête
Utilisation de filtres JSON dans les services de requête
Les filtres JSON sont utilisables dans de nombreux services de requête. Les sections suivantes expliquent comment utiliser ces filtres JSON dans tout service de requête utilisant le paramètre d'entrée filter facultatif.
Clés et opérateurs pris en charge
Les clés et opérateurs suivants sont pris en charge pour utilisation dans les filtres JSON :
select
as
filters
Avec les valeurs type suivantes (opérateurs logiques) :
EQ : égal à
NE : différent de
LT : inférieur à
LE : inférieur ou égal à
GT : supérieur à
GE : supérieur ou égal à
AND : et
OR : ou
IN : dans
NOTIN : pas dans
LIKE : comme
NOTLIKE : différent de
BETWEEN : entre
NOTBETWEEN : non compris entre
TAGGED : marqué
NOTTAGGED : non marqué
MATCHES : correspond
NOTMATCHES : ne correspond pas
MISSINGVALUE : valeur manquante
NOTMISSINGVALUE : valeur non manquante
isCaseSensitive : comparaison sensible à la casse si vrai ; utilisé avec EQ, NE, LIKE, NOTLIKE, MATCHES et NOTMATCHES.
sorts
isAscending : tri croissant si vrai, tri décroissant si faux
isCaseSensitive : tri sensible à la casse si vrai
joins, avec les valeurs de type suivantes (types de jointure) :
INNER
LEFT
RIGHT
FULL
dataShapeName : nom de la forme de données sur laquelle réside la colonne (fieldName)
fieldName : nom de la colonne dans la forme de données
value ou values : valeur ou valeurs d'intérêt dans la base de données
alias : alias de la forme de données que le service de requête interroge. Lorsqu'un alias est spécifié, vous devez utiliser alias dans les clés select, filters, joins et sorts.
function :
MIN
MAX
COUNT : non pris en charge pour les champs DATETIME.
AVG
SUM
groupBy
* 
Dans l'exemple de filtre suivant, les champs Name de PTC.SCA.SCO.JobOrderProcessingResourceRequirement et de PTC.SCA.SCO.JobOrder sont des propriétés personnalisées qui ont été ajoutées à ces formes de données. Pour utiliser les filtres comme indiqué, ces champs doivent être ajoutés aux formes de données.
Lorsque vous spécifiez des propriétés personnalisées dans un filtre JSON, vous pouvez spécifier la forme de données principale de l'objet, comme illustré dans ces exemples. Il n'est pas nécessaire de spécifier la forme de données _AP associée utilisée pour ajouter la propriété personnalisée.
Select
Dans une clé select, vous pouvez sélectionner les champs de formes de données spécifiques que vous souhaitez que la requête renvoie. Construisez un tableau JSON dans lequel chaque objet spécifie le dataShapeName et le fieldName pour qu'un champ soit renvoyé par la requête. Le dataShapeName peut être le nom de la forme de données principale (la forme de données sur laquelle le service est exécuté) ou le nom d'une autre forme de données incluse dans la requête par une jointure. Si un alias est spécifié pour une forme de données, utilisez l'alias chaque fois que vous souhaitez faire référence à cette table de données spécifique dans la clé select. Lorsqu'aucun alias n'est défini pour une forme de données, la requête utilise par défaut une valeur d'alias unique générée pour cette table de données. Chaque fois que vous ne spécifiez pas l'alias et que votre JSON fait référence à cette même forme de données, la même valeur d'alias unique générée pour cette table de données est utilisée.
Lorsqu'as est utilisé, la table d'informations de sortie ajoute un champ pour cette clé select en utilisant la valeur as comme nom de champ.
Les fonctions (MIN, MAX, COUNT, AVG, SUM) peuvent être utilisées dans une clé select. Un exemple de filtre JSON incluant la fonction COUNT est disponible ici.
* 
Si une fonction d'agrégation est utilisée dans la clé select et qu'il y a plusieurs objets select dans la clé select, groupBy doit également être utilisé dans le filtre, sinon la requête échoue.
Par exemple, la clé select suivante peut être utilisée dans un filtre JSON pour que le service GetJobOrders renvoie le nom d'une exigence de ressource de production d'ordre de travail, le nom et l'ID d'un ordre de travail et le nom d'une ressource de production :
{
"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"
}
]
}
Dans l'exemple précédent, les champs Name de PTC.SCA.SCO.JobOrderProcessingResourceRequirement et de PTC.SCA.SCO.JobOrder sont des propriétés supplémentaires qui ont été ajoutées aux formes de données.
* 
Le service BuildSelectFromDataShapes sur l'objet PTC.DBConnection.QueryUtils peut être utilisé pour créer la clé select pour les formes de données spécifiées. L'exemple suivant d'entrée de service génère une clé select pour les formes de données PTC.SCA.SCO.JobOrderPRocessingResourceRequirement, PTC.SCA.SCO.JobORder et PTC.SCA.SCO.ProcessingResource :
{
"dataShapes": [{
"name": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement"
},
{
"name": "PTC.SCA.SCO.JobOrder"
},
{
"name": "PTC.SCA.SCO.ProcessingResource"
}
]
}
Filters
La clé filters vous permet de filtrer les résultats de la requête pour afficher les enregistrements correspondant à des valeurs spécifiques. Vous pouvez combiner plusieurs filtres dans un tableau JSON nommé filters, en séparant chaque filtre par une virgule et en reliant les filtres au moyen d'un opérateur AND ou OR. Chaque filtre spécifie un dataShapeName, fieldName, type et value ou values (pour l'opérateur IN). Les filtres simples ou multiples doivent ensuite être regroupés sous une autre clé filters.
Le dataShapeName peut être le nom de la forme de données principale (la forme de données sur laquelle le service est exécuté) ou le nom d'une autre forme de données incluse dans la requête par une jointure. Si aucun dataShapeName n'a été spécifié pour le filtre, c'est la forme de données sur laquelle le service est exécuté qui est prise en compte. Si un alias est spécifié pour une forme de données, utilisez l'alias chaque fois que vous souhaitez faire référence à cette table de données spécifique dans la clé filters. Lorsqu'aucun alias n'est défini pour une forme de données, la requête utilise par défaut une valeur d'alias unique générée pour cette table de données. Chaque fois que vous ne spécifiez pas l'alias et que votre JSON fait référence à cette même forme de données, la même valeur d'alias unique générée pour cette table de données est utilisée.
Par exemple, la clé filters suivante peut être utilisée dans un filtre JSON pour que le service GetHistoricalData renvoie tous les résultats de la table de base de données des données historiques dans laquelle un ordre de travail a été créé ou mis à jour :
{
"filters": {
"filters": [
{
"dataShapeName": "PTC.DBConnection.HistoricalData",
"fieldName": "DataShapeName",
"type": "EQ",
"value": "PTC.SCA.SCO.JobOrder",
"isCaseSensitive": true
},
{
"dataShapeName": "PTC.DBConnection.HistoricalData",
"fieldName": "ReferenceKey",
"type": "IN",
"values": [1,2]
}
],
"type": "AND"
}
}
Sorts
La clé sorts vous permet de trier les résultats de la requête en fonction d'un champ de forme de données spécifique (dataShapeName et fieldName), de trier dans l'ordre croissant ou décroissant (isAscending) et de déterminer si le filtre est sensible à la casse (isCaseSensitive). Vous pouvez effectuer un tri sur plusieurs champs en incluant plusieurs objets de tri dans le tableau, séparés par des virgules.
Le dataShapeName peut être le nom de la forme de données principale (la forme de données sur laquelle le service est exécuté) ou le nom d'une autre forme de données incluse dans la requête par une jointure. Si aucun dataShapeName n'a été spécifié, c'est la forme de données sur laquelle le service est exécuté qui est prise en compte. Si un alias est spécifié pour une forme de données, utilisez l'alias chaque fois que vous souhaitez faire référence à cette table de données spécifique dans la clé sorts. Lorsqu'aucun alias n'est défini pour une forme de données, la requête utilise par défaut une valeur d'alias unique générée pour cette table de données. Chaque fois que vous ne spécifiez pas l'alias et que votre JSON fait référence à cette même forme de données, la même valeur d'alias unique générée pour cette table de données est utilisée.
Par exemple, la clé suivante sorts peut être utilisée dans un filtre JSON avec le service GetJobOrders pour trier les résultats selon le nom de l'exigence de la ressource de production de l'ordre de travail dans l'ordre croissant, puis selon le nom de l'ordre de travail dans l'ordre décroissant (en supposant que l'exigence de ressource de production de l'ordre de travail est incluse dans la requête par une jointure).
{
"sorts":[
{
"dataShapeName": "PTC.SCA.SCO.JobOrderProcessingResourceRequirement",
"fieldName": "Name",
"isAscending": true,
"isCaseSensitive": false
},
{
"dataShapeName": "PTC.SCA.SCO.JobOrder",
"fieldName": "Name",
"isAscending": false,
"isCaseSensitive": false
}
]
}
Jointures
Une jointure est utilisée pour combiner les lignes de deux formes de données ou plus, en fonction d'un champ associé entre les formes de données. Pour utiliser des champs sur les formes de données dans les clés de sélection, de tri ou de filtre, incluez ces formes de données (autres que la forme de données principale) dans la requête à l'aide d'une jointure.
Chaque jointure est constituée du type de jointure (type), de la forme de données source ou gauche et du nom de champ (sourceDataShapeName et sourceFieldName), ainsi que de la forme de données cible ou droite et du nom de champ (targetDataShapeName et targetFieldName).
Utilisez respectivement sourceAlias et targetAlias pour les formes de données source et cible de la jointure. targetAlias doit être unique. sourceAlias doit soit référencer l'alias principal pour la requête, soit un targetAlias précédent. Lorsqu'aucun sourceAlias ou targetAlias n'est défini pour une forme de données, la requête utilise par défaut une valeur d'alias unique générée pour cette table de données. Chaque fois que vous ne spécifiez pas soureAlias ou targetAlias et que votre JSON fait référence à cette même forme de données, la même valeur d'alias unique générée pour cette table de données est utilisée.
Les types de jointures suivants sont pris en charge : INNER, LEFT, RIGHT et FULL.
INNER : une jointure interne renvoie tous les enregistrements qui ont des valeurs correspondantes dans les deux formes de données.
LEFT : une jointure gauche renvoie tous les enregistrements de la forme de données gauche (source) et les enregistrements correspondants de la forme de données droite (cible). S'il n'existe aucune correspondance, le résultat du côté droit (cible) de la jointure est NULL.
RIGHT : une jointure droite renvoie tous les enregistrements de la forme de données droite (cible) et les enregistrements correspondants de la forme de données gauche (source). S'il n'existe aucune correspondance, le résultat du côté gauche (source) de la jointure est NULL.
FULL : une jointure complète renvoie tous les enregistrements contenant une correspondance dans la forme de données gauche (source) ou droite (cible).
Les jointures réflexives sont prises en charge lorsque les valeurs sourceAlias et targetAlias pour la jointure sont différentes. Si votre jointure réflexive se trouve sur la forme de données principale, sourceAlias doit correspondre à la valeur alias de la forme de données principale.
Par exemple, la clé joins suivante peut être utilisée dans un filtre JSON pour que le service GetJobOrders renvoie tous les enregistrements pour lesquels l'UID de l'ordre de travail correspond au champ JobOrderUID de l'exigence de ressource de production de l'ordre de travail et où le champ ProcessingResourceUID de l'exigence de ressource de production de l'ordre de travail correspond au champ UID de la ressource de production.
{
"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"
}
]
}
Grouper par
La clé groupBy vous permet d'agréger les lignes de la sortie en lignes récapitulatives en fonction d'un champ de forme de données spécifique (dataShapeName et fieldName). Le dataShapeName peut être le nom de la forme de données principale (la forme de données sur laquelle le service est exécuté) ou le nom d'une autre forme de données incluse dans la requête par une jointure. Si aucun dataShapeName n'a été spécifié, c'est la forme de données sur laquelle le service est exécuté qui est prise en compte. La clé groupBy est souvent utilisée avec les fonctions (MIN, MAX, COUNT, AVG, SUM).
Si un alias est spécifié pour une forme de données, utilisez l'alias chaque fois que vous souhaitez faire référence à cette table de données spécifique dans la clé groupBy. Lorsqu'aucun alias n'est défini pour une forme de données, la requête utilise par défaut une valeur d'alias unique générée pour cette table de données. Chaque fois que vous ne spécifiez pas l'alias et que votre JSON fait référence à cette même forme de données, la même valeur d'alias unique générée pour cette table de données est utilisée.
Par exemple, la clé groupBy suivante peut être utilisée dans un filtre JSON pour permettre à un service de requête de regrouper les résultats selon le nom du type de raison.
{
"groupBy": [
{
"dataShapeName": "PTC.ReasonCode.ReasonType",
"fieldName": "name"
}
}
Exemples de filtres JSON
Exemple 1 : L'exemple suivant présente un filtre qui peut être utilisé avec le service GetHistoricalData. Ce filtre renvoie tous les résultats dans la base de données d'historique où un ordre de travail a été créé, puis trie les résultats dans l'ordre croissant en fonction de l'heure de création de chaque ordre de travail.
{
"filters": {
"filters": [
{
"dataShapeName": "PTC.DBConnection.HistoricalData",
"fieldName": "DataShapeName",
"type": "EQ",
"value": "PTC.SCA.SCO.JobOrder"
},
{
"dataShapeName": "PTC.DBConnection.HistoricalData",
"fieldName": "ReferenceKey",
"type": "EQ",
"value": 1
}
],
"type": "AND"
},
"sorts": [
{
"fieldName": "TimeStamp",
"isAscending": true,
"isCaseSensitive": false
}
]
}
Exemple 2 : L'exemple suivant présente un filtre qui peut être utilisé avec le service GetJobOrders. Avec ce filtre :
Pour chaque résultat, le Name et l'ID de l'ordre de travail, le Name de la ressource de production associée et le Name de l'exigence de ressource de production de l'ordre de travail sont renvoyés.
Les résultats sont filtrés uniquement pour les ressources de production dont l'ID a pour valeur WC1.
Les résultats renvoyés concernent les enregistrements pour lesquels l'UID de l'ordre de travail correspond au champ JobOrderUID de l'exigence de la ressource de production de l'ordre de travail, et où le champ ProcessingResourceUID de l'exigence de la ressource de production de l'ordre de travail correspond au champ UID de la ressource de production.
Les résultats sont triés par Name d'exigence de ressource de production de l'ordre de travail dans l'ordre croissant, puis par Name d'ordre de travail dans l'ordre décroissant.
{
"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
}
]
}
Exemple 3 : l'exemple suivant présente un filtre qui peut être utilisé lors de l'interrogation de la forme de données PTC.ReasonCode.ReasonCategory en tant que forme de données principale de la requête. Ce filtre inclut des clés as, la fonction COUNT et groupBy.
{
"select": [
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"as": "count",
"function": "COUNT"
},
{
"dataShapeName": "PTC.ReasonCode.ReasonType",
"fieldName": "name",
"as": "typeName"
}
],
"joins": [
{
"type": "LEFT",
"sourceDataShapeName": "PTC.ReasonCode.ReasonCategory",
"sourceFieldName": "reasonTypeUid",
"targetDataShapeName": "PTC.ReasonCode.ReasonType",
"targetFieldName": "uid"
}
],
"groupBy": [
{
"dataShapeName": "PTC.ReasonCode.ReasonType",
"fieldName": "name"
}
]
}
Exemple 4 : l'exemple suivant présente un filtre pouvant être utilisé lors de l'interrogation de la forme de données PTC.ReasonCode.ReasonCategory en tant que forme de données principale de la requête. Ce filtre inclut une jointure réflexive par rapport à la forme de données PTC.ReasonCode.ReasonCategory utilisant sourceAlias et targetAlias, des clés as, la fonction COUNT et groupBy.
{
"alias": "ReasonCategory1",
"select": [
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"as": "name",
"alias": "ReasonCategory1"
},
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"as": "name2",
"alias": "ReasonCategory2"
},
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"as": "countName",
"function": "COUNT",
"alias": "ReasonCategory1"
}
],
"filters": {
"filters": [
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"type": "EQ",
"value": "Scrap",
"alias": "ReasonCategory1"
}
],
"type": "AND"
},
"joins": [
{
"type": "LEFT",
"sourceDataShapeName": "PTC.ReasonCode.ReasonCategory",
"sourceFieldName": "uid",
"sourceAlias": "ReasonCategory1",
"targetDataShapeName": "PTC.ReasonCode.ReasonCategory",
"targetFieldName": "uid",
"targetAlias": "ReasonCategory2"
},
{
"type": "LEFT",
"sourceDataShapeName": "PTC.ReasonCode.ReasonCategory",
"sourceFieldName": "reasonTypeUid",
"sourceAlias": "ReasonCategory1",
"targetDataShapeName": "PTC.ReasonCode.ReasonType",
"targetFieldName": "uid",
"targetAlias": "ReasonType"
}
],
"groupBy": [
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"alias": "ReasonCategory1"
},
{
"dataShapeName": "PTC.ReasonCode.ReasonCategory",
"fieldName": "name",
"alias": "ReasonCategory2"
}
]
}
Pour obtenir des exemples supplémentaires d'utilisation de filtres dans les requêtes, consultez la rubrique Paramètre de requête pour les services de requête dans le Centre d'aide ThingWorx. Remarque : Les filtres Near et NotNear décrits dans cette rubrique ne sont pas pris en charge dans ces filtres JSON.
Est-ce que cela a été utile ?