Utiliser DQL et l'API DataNinja
Comment utiliser DQL et l'API pour extraire de grands volumes de données
English: Read this page in English.
Español: Lee esta página en español.
Utilisez le DataNinja Query Language (DQL), l'onglet « Explorer » de la page API et l'API DataNinja pour interroger des enregistrements, confirmer les champs disponibles, créer des filtres de Grid Configuration et soutenir les intégrations.
DQL vous permet d'interroger l'information stockée dans DataNinja. L'API permet aux utilisateurs techniques et aux développeurs d'intégrations d'interagir avec les données DataNinja au moyen de points de terminaison d'API.
Utilisations recommandéesCes outils sont utiles lorsque vous devez :
- Extraire de grands volumes de données de DataNinja
- Soutenir des rapports personnalisés
- Passer en revue les champs disponibles pour un objet
- Tester des filtres avant de les utiliser dans des rapports ou des Grid Configurations
- Soutenir des intégrations avec des systèmes externes
- Mieux comprendre la structure des objets et des champs DataNinja
Aperçu de DQL et de l'API
DQL et l'onglet « Explorer » se trouvent sur la page API de votre site DataNinja. L'onglet « Explorer » énumère les objets de la base de données DataNinja et leurs champs, et les requêtes DQL utilisent ces objets et ces champs pour retourner des données en lecture seule. L'API DataNinja et Postman se trouvent à l'extérieur de votre site DataNinja, mais fonctionnent ensemble pour vous permettre de modifier des données en direct ou d'extraire des données en lecture seule.
| Outil | Objectif | Utilisation courante |
|---|---|---|
| DataNinja Query Language (DQL) | Permet aux utilisateurs d'interroger les données DataNinja avec une syntaxe semblable à SQL | Passer en revue des enregistrements, tester des filtres, créer des rapports, confirmer des valeurs de champ |
| Onglet Explorer | Permet aux utilisateurs de passer en revue les objets, les champs et les relations DataNinja disponibles | Trouver les noms de champs pour DQL, les Grid Configurations, les rapports ou les intégrations |
| API DataNinja | Permet aux utilisateurs techniques d'interagir avec les données DataNinja au moyen de points de terminaison d'API | Créer, mettre à jour, récupérer ou intégrer des enregistrements avec des systèmes externes |
| Jeton d'API | Permet à une intégration ou à un outil de se connecter à DataNinja en votre nom | Connecter Power BI, Excel, Google Sheets, des scripts ou d'autres intégrations |
| Documentation de l'API Postman | Fournit la documentation et des exemples des points de terminaison d'API | Passer en revue les appels d'API, trouver des pièces, consulter les niveaux de stock et soutenir les intégrations |
DataNinja Query Language (DQL)
Le DataNinja Query Language (DQL) est un langage de requête semblable à SQL pour les données d'une application DataNinja. Utilisez DQL pour passer en revue des enregistrements, tester des filtres, créer des rapports et confirmer des valeurs de champ. Utilisez la notation par points dans les clauses SELECT et WHERE pour naviguer dans les relations. DataNinja crée automatiquement les jointures appropriées à l'interne.
DQL prend en charge :
- Where
- Group by
- Having
- Order by
- Limit
- Offset
Les noms d'objets et de champs ne sont pas sensibles à la casse; part.partNumber et PART.PARTNUMBER retournent donc le même champ.
DQL est couramment utilisé par les équipes d'implantation, les administrateurs, les équipes de soutien et les utilisateurs techniques qui doivent interroger les données DataNinja ou confirmer la façon dont l'information est structurée dans le système.
Accéder à la page API
Vous pouvez exécuter DQL à partir de la page API de DataNinja. Cliquez sur l'icône d'engrenage en haut à droite, allez à « All Lists », puis cliquez sur « API ». La page API comporte cinq onglets : « DQL », « Explorer », « Examples », « Setup » et « Custom Fields ». Rédigez et exécutez vos requêtes dans la « Query Window » de l'onglet « DQL ».

Utiliser l'onglet Explorer
Pour explorer les objets que vous pouvez interroger avec DQL, ouvrez l'onglet « Explorer » en haut de la page API.
L'onglet « Explorer » vous permet de passer en revue les objets et les champs DataNinja disponibles. Utilisez-le pour confirmer le bon nom de champ, ou pour le copier directement dans une requête.

Si un objet affiche un cercle vert « CF », des champs personnalisés peuvent être créés sur cet objet. Consultez Champs personnalisés pour en savoir plus.

Les requêtes peuvent être générées automatiquement en cochant la case à côté des champs dont vous avez besoin sur un objet, puis en cliquant sur « Copy ». Un seul objet peut être copié à la fois, et copier à partir d'un nouvel objet remplace la requête précédente.

Si un champ d'un objet affiche « Foreign Key » à côté, ce champ est relié à un autre objet. Cliquez sur « Foreign Key » pour aller à l'objet relié.

L'onglet « Explorer » peut vous aider à comprendre :
| Élément à examiner | Pourquoi c'est important |
|---|---|
| Objets | Aide à déterminer le type d'enregistrement DataNinja interrogé |
| Champs | Confirme les noms exacts des champs disponibles pour le filtrage ou les rapports |
| Objets liés | Aide à repérer les champs qui peuvent être accessibles par la notation par points |
| Structure des données | Aide les utilisateurs à comprendre comment les enregistrements sont reliés |
| Valeurs des champs | Aide les utilisateurs à confirmer les valeurs qui peuvent servir dans les filtres, comme le statut, le type ou la catégorie |
Exemples DQL de base
Ces exemples sont fournis à titre de référence seulement. Confirmez les bons noms d'objets, noms de champs et valeurs dans votre propre site DataNinja à l'aide de l'onglet « Explorer ». Dans le tableau ci-dessous, remplacez [fields] par les champs (colonnes) que vous voulez voir dans les résultats.
| Objectif | Exemple DQL |
|---|---|
| Retourner les enregistrements valides | SELECT [fields] FROM part WHERE isvalid=true |
| Retourner les enregistrements ayant un statut précis | SELECT [fields] FROM manufacturedbatch WHERE lifecycleid=2 |
| Retourner un nombre limité d'enregistrements | SELECT [fields] FROM part LIMIT 100 |
| Trier les enregistrements par nom | SELECT [fields] FROM part WHERE isvalid=true ORDER BY name |
Volume de résultatsSi votre requête DQL génère un grand volume de résultats, la performance de votre site DataNinja peut se dégrader; les pages peuvent se charger plus lentement ou des messages « Internal Server Error » peuvent s'afficher. Pour l'éviter, filtrez votre recherche autant que possible, ou utilisez LIMIT pour contrôler le nombre de résultats affichés sur la page.
Utiliser la notation par points pour les objets liés
DQL prend en charge la notation par points pour faire référence aux champs d'objets liés. Vous pouvez ainsi filtrer ou sélectionner de l'information provenant d'enregistrements liés sans créer de jointures manuellement.
SELECT id, identifier, lifecycleId, partId, partNumber, part.defaultLocationId
FROM batch
LIMIT 100Dans cet exemple, part.defaultLocationId fait référence au champ defaultLocationId de l'objet lié part.
Les objets et les champs liés disponibles dépendent de l'objet interrogé. Utilisez l'onglet « Explorer » pour confirmer les relations disponibles.
Un chemin avec des points peut aller jusqu'à 3 relations de profondeur. Par exemple, part.partNumber sur un lot représente 1 relation de profondeur. Si un chemin va plus loin, ou si l'une de ses étapes n'est pas une relation de cet objet, la requête s'arrête avec une erreur qui nomme le chemin, pour que vous puissiez le raccourcir ou corriger l'étape.
Retourner des enregistrements liés avec des sous-requêtes
Pour retourner un enregistrement avec la liste de ses enregistrements liés, comme une commande client et ses lignes, placez une sous-requête entre parenthèses dans le SELECT. Le FROM de la sous-requête est le nom d'une collection de l'objet principal, et la sous-requête peut avoir ses propres WHERE, ORDER BY et LIMIT.
SELECT Id,
(
SELECT Id, Quantity, Part.Name AS PartName
FROM Lines
WHERE IsDeleted = false
ORDER BY LineNumber DESC
LIMIT 100
) AS Lines
FROM SalesOrderChaque commande client est retournée une seule fois, avec ses lignes dans une liste nommée d'après l'alias (Lines). Un enregistrement sans lignes liées retourne une liste vide, et chaque liste est accompagnée du nombre total de lignes enfants correspondantes, même lorsque le LIMIT raccourcit la liste.
- Une requête peut contenir jusqu'à 5 sous-requêtes.
- Le
LIMITd'une sous-requête s'applique à chaque enregistrement parent. Il est de 100 lignes si vous l'omettez, et peut être d'au plus 250. - Les
WHERE,ORDER BY,LIMITetOFFSETde la requête principale s'appliquent seulement aux enregistrements principaux.
Connecter une intégration avec un jeton d'API
Les intégrations et les outils comme Power BI, Excel, Google Sheets ou vos propres scripts utilisent un jeton d'API pour se connecter à DataNinja. Vous créez et gérez vos propres jetons dans votre profil d'utilisateur.
- Cliquez sur l'icône d'engrenage en haut à droite, puis sur « User Profile ».
- Ouvrez l'onglet « API tokens ». Vous pouvez aussi y accéder à partir de l'onglet « Setup » de la page API en cliquant sur « Go to API Tokens ».
- Cliquez sur « Create token » et donnez au jeton un nom qui correspond à l'application qu'il connecte, comme « Power BI sync », pour le retrouver facilement plus tard.
- Copiez le jeton immédiatement. Il n'est affiché qu'au moment de sa création; conservez-le donc en lieu sûr, par exemple dans un gestionnaire de mots de passe.

Votre intégration envoie le jeton dans l'en-tête ApiToken de chaque requête à l'API DataNinja. Pour lire des données avec DQL, envoyez une requête GET à l'adresse /api/dql/query de votre site DataNinja, avec votre requête dans le paramètre dql :
GET https://<your site>.dataninja.com/api/dql/query?dql=SELECT Id, Name FROM Part LIMIT 10
ApiToken: <your token>À savoir au sujet des jetons :
- Un jeton agit en votre nom, avec vos rôles et vos permissions, et tout ce qu'il fait est enregistré sous votre nom.
- Chaque jeton expire un an après sa création. L'onglet « API tokens » affiche la date d'expiration de chaque jeton.
- Vous pouvez avoir jusqu'à 10 jetons actifs, et chacun doit avoir un nom unique.
- Vous pouvez révoquer un jeton à tout moment dans l'onglet « API tokens ». On vous demande d'abord de confirmer, puis le jeton cesse de fonctionner immédiatement; vos autres jetons continuent de fonctionner.
- Les utilisateurs ayant le rôle Contractor ne peuvent pas créer de jetons. Désactiver ou supprimer un utilisateur, ou le passer au rôle Contractor, révoque tous ses jetons.
Intégrations qui se connectaient avec un nom d'utilisateur et un mot de passeLes anciennes intégrations obtenaient leur jeton en envoyant un nom d'utilisateur et un mot de passe à DataNinja. Cette méthode ne retourne plus de jeton. Si une intégration ne se connecte plus, créez un jeton dans l'onglet « API tokens » et ajoutez-le à l'intégration.
Traitez les jetons comme des mots de passeToute personne qui possède votre jeton peut lire et modifier vos données DataNinja avec vos permissions. Ne le partagez pas, et révoquez-le dès qu'une intégration n'en a plus besoin.
Utiliser l'API DataNinja
DataNinja utilise Postman pour documenter l'API et interagir avec elle. La documentation de l'API DataNinja comprend des exemples et des instructions pour les activités liées à l'API, comme :
- Passer en revue les points de terminaison disponibles
- Publier des données dans DataNinja
- Récupérer des données de DataNinja
- Soutenir des intégrations avec des systèmes externes
Consultez la documentation de l'API DataNinja.
Bonnes pratiques
- Utilisez l'onglet « Explorer » pour confirmer les noms d'objets et de champs avant de rédiger des requêtes
- Commencez par une requête simple et ajoutez les filtres graduellement
- Utilisez des filtres et des limites lorsque vous interrogez de grands ensembles de données
- Confirmez les valeurs exactes des champs avant de filtrer par statut, type, catégorie ou emplacement
- Sélectionnez des champs précis plutôt que
SELECT *lorsque vous n'avez besoin que de certaines informations - Testez les résultats d'une requête avant d'utiliser la même logique dans un rapport, une intégration ou une Grid Configuration
- Évitez les requêtes trop larges, surtout avec de grands ensembles de données
DQL vs API
| Besoin | Outil recommandé |
|---|---|
| Passer en revue ou interroger des enregistrements DataNinja | DQL |
| Tester la logique d'un filtre | DQL |
| Repérer les objets et les champs disponibles | Onglet « Explorer » |
| Créer ou soutenir des Grid Configurations | Onglet « Explorer » et DQL |
| Créer, mettre à jour ou récupérer des enregistrements au moyen d'une intégration | API, avec un jeton d'API |
| Consulter la documentation des points de terminaison d'API | Documentation de l'API Postman |
Dépannage
| Problème | Cause possible | Action suggérée |
|---|---|---|
| La requête ne retourne pas les résultats attendus | Le nom du champ ou de l'objet est peut-être incorrect | Confirmez le nom du champ ou de l'objet dans l'onglet « Explorer » |
| La requête retourne trop d'enregistrements | Le filtre est peut-être trop large | Ajoutez des conditions ou utilisez LIMIT |
| La requête ne retourne aucun enregistrement | Le filtre est peut-être trop restrictif, ou la valeur ne correspond pas exactement | Retirez une condition à la fois et testez de nouveau |
| Un champ lié ne fonctionne pas | La notation par points ne correspond peut-être pas à une relation disponible, ou le chemin dépasse 3 relations de profondeur | Passez en revue les objets liés dans l'onglet « Explorer » et raccourcissez le chemin |
| Une sous-requête retourne une erreur | Le LIMIT de la sous-requête dépasse 250, ou la requête contient plus de 5 sous-requêtes | Réduisez le LIMIT ou divisez la requête |
| L'utilisateur ne peut pas accéder aux données attendues | L'accès du rôle ou des permissions est peut-être limité | Passez en revue les permissions de l'utilisateur dans DataNinja |
| « Create token » n'est pas disponible, ou l'onglet « API tokens » est absent | L'utilisateur a le rôle Contractor | Demandez à votre administrateur si un autre rôle conviendrait |
| « You already have the maximum of 10 active API tokens. » | Vous avez 10 jetons actifs | Révoquez un jeton que vous n'utilisez plus dans l'onglet « API tokens » |
| Une intégration reçoit « 401 Unauthorized » | L'en-tête ApiToken est absent, ou le jeton a été révoqué ou a expiré | Créez un nouveau jeton et mettez à jour l'intégration |
Updated 7 days ago
