Interroger les données d’une table pour les rapports

Objectif

Lire les données d'une table d'un environnement via la source de données de rapports en lecture seule, pour qu'une intégration externe de rapports ou d'analyse puisse lister les tables qu'elle peut lire, découvrir les colonnes d'une table, récupérer des pages de lignes et exécuter une requête enregistrée, sans aucun accès en écriture.

Prérequis

• Une inscription d'application externe ayant la portée reporting.read (ou modelapps.read, qui accorde aussi les lectures de rapports) et un rôle autorisé à lire les tables dont elle a besoin. Voir Inscrire une application externe.
• Un jeton d'accès obtenu pour cette inscription, en demandant la portée par son nom.
• L'identifiant de l'environnement dont vous voulez lire les données.

La surface de rapports

Toutes les opérations portent sur un seul environnement et sont en lecture seule. Deux choses décident de ce que vous obtenez : la portée ouvre la surface, et le rôle de l'application décide quelles tables et quelles lignes, exactement comme pour une personne dans une application. Un jeton avec la portée et sans rôle n'atteint aucune ligne.

Opération	Requête	Renvoie
Lister les tables	GET /environments/{environmentId}/reporting/entities	Les tables que votre rôle peut lire (nom logique, nom d'affichage, nom au pluriel).
Décrire les colonnes d'une table	GET /environments/{environmentId}/reporting/entities/{entity}/schema	Chaque colonne : nom logique, nom d'affichage, type de données, s'il s'agit du champ principal, et la table cible d'une recherche.
Lire un jeu de données	POST /environments/{environmentId}/reporting/entities/{entity}/dataset	columns et rows, plus totalCount, pageNumber et pageSize.
Exécuter une requête enregistrée	POST /environments/{environmentId}/saved-queries/{logicalName}/run	Les enregistrements ou les groupes de la requête enregistrée.

Une requête de jeu de données

Le corps est une requête : select (les colonnes voulues), filter (un connecteur et des conditions, chacune avec un champ, un opérateur et une valeur), order (des champs, croissants ou décroissants) et page (number et size) :

{
  "select": ["nw_name", "nw_company"],
  "filter": { "connector": "And",
              "conditions": [{ "field": "nw_company", "operator": "Equals", "value": "Analytical Engines" }] },
  "order": [{ "field": "nw_name", "descending": false }],
  "page": { "number": 1, "size": 50 }
}

Avec select, columns décrit exactement ces colonnes, dans cet ordre. Une colonne de choix revient sous forme de nombre et, à côté, son libellé sous <colonne>__text. totalCount vous dit combien de pages il y a.

Une requête enregistrée

Une requête qu'un concepteur a dessinée et enregistrée s'exécute par son nom logique. Le corps est facultatif et ne peut que la restreindre : un filter supplémentaire s'ajoute au filtre enregistré, sans jamais le remplacer, et page choisit une page. Une requête groupée répond avec ses groupes et leurs mesures, si bien qu'une intégration peut demander des totaux au lieu d'additionner elle-même les lignes.

Ce qui se passe en coulisses

La source de données de rapports ne crée, ne modifie ni ne supprime rien. Chaque requête vérifie d'abord la portée du jeton, puis lit par le même chemin que les écrans de la plateforme : les autorisations du rôle et leurs stratégies décident donc des lignes. Seul l'environnement nommé dans la route est lu.

Dépannage

• 403 avec modelapps.reporting.forbidden. Le jeton ne porte ni reporting.read ni modelapps.read. Demandez la portée par son nom en demandant le jeton : un jeton demandé sans scope n'en porte aucune.
• 403 avec modelapps.record.forbidden. La portée est là, mais le rôle de l'application ne peut pas lire cette table. Accordez au rôle la lecture sur elle dans cet environnement.
• Une table manque dans la liste. Le rôle ne peut pas la lire, ou elle n'existe pas dans cet environnement.
• 400 pour un champ inconnu. Un champ de select, filter ou order n'appartient pas à la table. Utilisez un champ du schéma de la table.

Scénarios associés

• Inscrire une application externe.
• Lier un rapport à une table (concepteur).