Guides
GuidesLog In
Guides

Utiliser DQL et l'API DataNinja

Comment utiliser DQL et l'API pour extraire de grands volumes de données

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ées

Ces 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.

OutilObjectifUtilisation courante
DataNinja Query Language (DQL)Permet aux utilisateurs d'interroger les données DataNinja avec une syntaxe semblable à SQLPasser en revue des enregistrements, tester des filtres, créer des rapports, confirmer des valeurs de champ
Onglet ExplorerPermet aux utilisateurs de passer en revue les objets, les champs et les relations DataNinja disponiblesTrouver les noms de champs pour DQL, les Grid Configurations, les rapports ou les intégrations
API DataNinjaPermet aux utilisateurs techniques d'interagir avec les données DataNinja au moyen de points de terminaison d'APICréer, mettre à jour, récupérer ou intégrer des enregistrements avec des systèmes externes
Jeton d'APIPermet à une intégration ou à un outil de se connecter à DataNinja en votre nomConnecter Power BI, Excel, Google Sheets, des scripts ou d'autres intégrations
Documentation de l'API PostmanFournit la documentation et des exemples des points de terminaison d'APIPasser 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 ».

Page API sur l'onglet DQL avec la syntaxe DQL et des exemples

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.

Onglet Explorer avec la liste des objets et les pastilles CF

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.

Objet Address dans l'onglet Explorer avec son onglet Custom Fields ouvert

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.

Champs sélectionnés et bouton Copy sur l'objet Batch dans l'onglet Explorer

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é.

Lien Foreign Key sur un champ de table dans l'API Explorer

L'onglet « Explorer » peut vous aider à comprendre :

Élément à examinerPourquoi c'est important
ObjetsAide à déterminer le type d'enregistrement DataNinja interrogé
ChampsConfirme les noms exacts des champs disponibles pour le filtrage ou les rapports
Objets liésAide à repérer les champs qui peuvent être accessibles par la notation par points
Structure des donnéesAide les utilisateurs à comprendre comment les enregistrements sont reliés
Valeurs des champsAide 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.

ObjectifExemple DQL
Retourner les enregistrements validesSELECT [fields] FROM part WHERE isvalid=true
Retourner les enregistrements ayant un statut précisSELECT [fields] FROM manufacturedbatch WHERE lifecycleid=2
Retourner un nombre limité d'enregistrementsSELECT [fields] FROM part LIMIT 100
Trier les enregistrements par nomSELECT [fields] FROM part WHERE isvalid=true ORDER BY name
❗️

Volume de résultats

Si 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 100

Dans 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 SalesOrder

Chaque 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 LIMIT d'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, LIMIT et OFFSET de 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.

  1. Cliquez sur l'icône d'engrenage en haut à droite, puis sur « User Profile ».
  2. 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 ».
  3. 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.
  4. 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.
Onglet API tokens du profil d'utilisateur avec le bouton Create token

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 passe

Les 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 passe

Toute 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

BesoinOutil recommandé
Passer en revue ou interroger des enregistrements DataNinjaDQL
Tester la logique d'un filtreDQL
Repérer les objets et les champs disponiblesOnglet « Explorer »
Créer ou soutenir des Grid ConfigurationsOnglet « Explorer » et DQL
Créer, mettre à jour ou récupérer des enregistrements au moyen d'une intégrationAPI, avec un jeton d'API
Consulter la documentation des points de terminaison d'APIDocumentation de l'API Postman

Dépannage

ProblèmeCause possibleAction suggérée
La requête ne retourne pas les résultats attendusLe nom du champ ou de l'objet est peut-être incorrectConfirmez le nom du champ ou de l'objet dans l'onglet « Explorer »
La requête retourne trop d'enregistrementsLe filtre est peut-être trop largeAjoutez des conditions ou utilisez LIMIT
La requête ne retourne aucun enregistrementLe filtre est peut-être trop restrictif, ou la valeur ne correspond pas exactementRetirez une condition à la fois et testez de nouveau
Un champ lié ne fonctionne pasLa notation par points ne correspond peut-être pas à une relation disponible, ou le chemin dépasse 3 relations de profondeurPassez en revue les objets liés dans l'onglet « Explorer » et raccourcissez le chemin
Une sous-requête retourne une erreurLe LIMIT de la sous-requête dépasse 250, ou la requête contient plus de 5 sous-requêtesRéduisez le LIMIT ou divisez la requête
L'utilisateur ne peut pas accéder aux données attenduesL'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 absentL'utilisateur a le rôle ContractorDemandez à votre administrateur si un autre rôle conviendrait
« You already have the maximum of 10 active API tokens. »Vous avez 10 jetons actifsRé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