Exposition DataBlock (API)
Introduction
Chaque DataBlock peut-être consommé via une API Rest (méthode GET).
La consommation des jeux de données des DataBlocks via l’API doit être configurée au niveau du DataBlock exposé.
|
Les droits s’appliquent différemment selon que le DataBlock est persisté ou non. En mode "Live" (non persisté), l’utilisateur doit avoir les droits sur l’ensemble de la chaîne de valeur des éléments liés précédant l’élément (Connecteur(s), Dépôt(s), Entité(s) Métier et DataBlock(s)). En Mode persisté, seuls les droits en sortie du DataBlock sont pris en compte |
Exposer les données d’un DataBlock
Il est possible d’exposer les données d’un DataBlock depuis
-
la liste des DataBlocks : cliquer sur l’icône
-
la page d’un DataBlock : cliquer sur le menu d’action puis sur "Exposition DataAPI"
Configuration de l’exposition API
Par défaut, les DataBlocks ne sont pas exposés.
Différents paramètres doivent être définis pour exposer les données d’un DataBlock.
Variable du point d’accès (Obligatoire)
Correspond à la partie en caractères gras dans l’exemple ci-dessous
…//…./service/data/exposition?select=DateNais,Sexe,NomFam,DateNais,DPT&filter=Sexe=in=(4,3)&hitsPerPage=1000
Bouton à cliquer pour exposer les données du Datablock et créer les liens d’accès
Description des données (visibles par les utilisateurs finaux consommant l’API)
Zone de recherche des colonnes
Libellé des colonnes du DataBlock
Libellé des colonnes que les utilisateurs finaux doivent utiliser dans la syntaxe de l’URL.
Correspond aux parties en caractères gras dans l’exemple ci-dessous
…//…./service/data/exposition?select=id,nom,prenom&filter=id=in=(4,3)&hitsPerPage=1000
Description de la colonne (visible par les utilisateurs finaux consommant l’API)
Indique si la colonne est exposée ou non. Une colonne non exposée n’est pas consommable par l’API
Indique si la colonne est masquée dans l’exposition (par exemple la colonne liée aux filtres sur les groupes et les utilisateurs)
Indique si une colonne doit être utilisée comme clé primaire (attention à l’unicité des données).
Permet d’accéder à une ligne par son identifiant
Sélectionner pour ignorer la casse et les accents lors des recherches
Affiche l’historique des expositions
Affiche les filtres disponibles pour l’exposition et permet de créer de nouveaux filtres
Configuration des points d’accès et modification de l’API
Dès que l’API est exposée, 3 points d’accès différents sont disponibles.
L’Exposition peut être désactivée et mise à jour.
Renvoie le nombre de lignes. Cette url peut être complétée par les paramètres de filtre.
…//…./service/data/MonEp/count?filter=Sexe=in=(4,3)
Renvoie les données (en fonction des filtres et de la requête effectuée, se référer au paragraphe Syntaxes et opérateurs)
Affiche l’écran d’information de l’API Rest DataBlock.
La documentation est dynamique et propre à chaque Datablock, c’est-à-dire, alignée sur la configuration réalisée.
Active/Inactive l’API.
Les expositions inactives ne sont plus opérationnelles pour ce DataBlock.
Cliquer pour mettre à jour les données de l’exposition (données, filtres …)
Cliquer pour supprimer l’ensemble des données exposées
Suivi des expositions
L’onglet de suivi des expositions trace l’ensemble des expositions effectuées.
À chaque fois que des modifications sont effectuées, la précédente exposition est supprimée.
Permissions par filtre
L’accès aux données exposées peut être limitée en ajoutant des filtres en amont depuis l’onglet "Permissions par filtres".
Vous devez d’abord paramétrer un filtre puis l’associer à un ou plusieurs utilisateurs ou groupes.
Le filtre s’applique uniquement sur le(s) utilisateur(s) ou membres du ou des groupe(s) associé(s) au filtre.
Cliquer sur l’icône 
de la liste des filtres pour associer les utilisateurs.
Ajouter le ou les utilisateurs et groupes à associer puis cliquer sur "Enregistrer"
Consommer des données exposées
Conditions d’accès à l’API d’un DataBlock
Pour consommer l’API d’un DataBlock, l’utilisateur doit posséder
-
un compte dans l’instance DataChain concernée
-
un jeton d’accès (Token)
Le jeton d’accès peut être obtenu
-
depuis la page de gestion du compte
-
via le service d’authentification, API d’authentification
Accès à la documentation de l’API Rest
Pour accéder à la page de la documentation, utiliser l’URL du point d’accès "Documentation".
Coller le jeton d’accès (token) (en savoir plus sur les jetons d’accès)
Cliquer pour afficher la documentation.
La documentation s’affiche en dessous du formulaire
Description du jeu de données exposé (si elle a été renseignée)
Liste des colonnes disponibles (libellé, type et description si elle a été renseignée)
URL d’accès aux données.
Utiliser cette zone pour effectuer des tests et afficher le résultat dans la page (se référer aux Syntaxes et opérateurs)
Tableau contenant le résultat de la requête
Depuis PowerBI
Il est possible de consommer les données exposées d’un DataBlock depuis le connecteur DataChain de PowerBI.
Pour suivre les étapes de création, rendez-vous sur le tutoriel Consommer une API DC exposée depuis PowerBi
Syntaxes et opérateurs
Syntaxes de requêtes vers l’API
Le jeton d’accès est obligatoire.
Il doit être positionné dans les entêtes de la requête (Bearer token).
https://monInstance/service/data/exposition?select=id,nom&filter=nom=beginsWith=A
| Syntaxe | Description | Obligatoire ? |
|---|---|---|
URL d’accès de base |
|
|
exposition? |
Nom du point d’accès attribué lors du paramétrage de l’API au niveau du DataBlock |
|
select= |
Sélectionne les colonnes à renvoyer dans la réponse. |
|
filter= |
Filtres en fonction des paramètres de filtres définis |
|
page= |
Indique la page retournée. Par défaut, il s’agit de la page 1 |
|
hitsPerPage= |
Indique le nombre de lignes par page |
|
useCache= |
Indique si le cache (persistance) est utilisé ou non |
|
sort= |
Tri en fonction des paramètres définis |
|
ctx: |
Indique le contexte de l’instance utilisée |
|
& |
Caractère à ajouter entre chaque filtre |
Opérateurs sur les valeurs
| Opérateur | Syntaxe | Types acceptés | Exemple |
|---|---|---|---|
Égal |
== |
String, Numérique, Booléen, Date |
nom=='mon ami' ou nom==ami |
Différent |
!= |
String, Numérique, Booléen, Date |
nom!='mon ami' ou nom!=ami |
Supérieur |
> ou =gt= |
Numérique, Date |
> 10 ou =gt=10 |
Supérieur ou égal |
> = ou =ge= |
Numérique, Date |
> = 10 ou =ge=10 |
Inférieur |
< ou =lt= |
Numérique, Date |
< 10 ou =lt=10 |
Inférieur ou égal |
< = ou =le= |
Numérique, Date |
< = 10 ou =le=10 |
Dans la liste |
=in= |
String, Numérique, Booléen, Date |
=in=(ami,copain) |
Pas dans la liste |
=out= ou =notIn= |
String, Numérique, Booléen, Date |
=out=(ami,copain) ou =notIn=('mon ami','mon copain') |
Compris entre |
=between= |
Numérique, Date |
=between=(2,5) ou =between=('','') |
N’est pas compris entre |
=notBetween= |
Numérique, Date |
=notBetween=(2,5) ou =notBetween=('','') |
Contient |
=contains= |
string |
=contains=(A,B,'B A') |
Ne contient pas |
=notContains= |
string |
=notContains=(A,B,'B A') |
Commence par |
=beginsWith= |
string |
=beginsWith=A ou =beginsWith='A B' |
Ne commence par |
=notBeginsWith= |
string |
=NotBeginsWith=A ou =NotBeginsWith='A B' |
Se termine par |
=endsWith= |
string |
=endsWith=A ou =endsWith='A B' |
Ne se termine pas par |
=notEndsWith= |
string |
=notEndsWith=A ou =notEndsWith='A B' |
Est null / N’est pas Null |
=isNull= |
String, Numérique, Booléen, Date |
Nom=isNull=true ou Nom=isNull=false |
Opérateurs sur les utilisateurs et les groupes
Il est possible d’ajouter des variables dans les filtres afin de limiter l’accès aux données exposées à certains utilisateurs ou groupes d’utilisateurs.
3 variables sont disponibles
-
@DcUserGroups
-
@DcUserMail
-
@DcUserLogin
Pour que le filtre s’applique, le Datablock doit posséder une colonne contenant, pour chaque ligne, la liste du ou des utilisateur(s) et groupe(s) concerné(s) par le filtre.
| Il est possible de ne pas exposer cette colonne en la désactivant depuis le paramétrage du choix des colonnes. |
Syntaxe attendue
nomDeLaColonne=operateur=variable
| Variable / Opérateur | =contains= | =notContains= | =containsAllOf= | =containsOneOf= | =containsNoneOf= |
|---|---|---|---|---|---|
@DcUserLogin |
La valeur contient le login de l’utilisateur |
La valeur ne contient pas le login de l’utilisateur |
N/A |
N/A |
N/A |
@DcUserMail |
La valeur contient le mail de l’utilisateur |
La valeur ne contient pas le mail de l’utilisateur |
N/A |
N/A |
N/A |
@DcUserGroups |
N/A |
N/A |
La valeur contient tous les groupes dont l’utilisateur fait partie |
La valeur contient l’un des groupes dont l’utilisateur fait partie |
La valeur ne contient aucun des groupes dont l’utilisateur fait partie |
|
L’opérateur se comporte comme un %like% en Base De Données. Par exemple, si un utilisateur appartient au Admin et que la colonne d’authentification comporte la valeur Administrateur, étant donné que la valeur Admin est contenue dans la valeur Administrateur, l’utilisateur pourra accéder aux données. L’exemple ci-dessous détail ce comportement et comment l’éviter. |
Exemple d’utilisation
-
Jean fait partie du groupe Admin
-
Alice fait partie des groupes Administrateur et Utilisateur
-
Cynthia fait partie des groupes Utilisateurs
| id | donnée | auth_group |
|---|---|---|
1 |
Donnée1 |
Admin |
2 |
Donnée2 |
Utilisateur Administrateur |
3 |
Donnée3 |
Admin Utilisateur |
4 |
Donnée4 |
Admin Administrateur Utilisateur |
auth_group=containsAllOf=@DcUserGroups
Le filtre permet à l’utilisateur de voir uniquement les lignes des données dont la valeur de la colonne Auth_group contient l’ensemble des valeurs égales aux valeurs des groupes auxquels il appartient.
-
Jean voit toutes les lignes, car la valeur "Admin" est incluse dans la valeur "Administrateur"
-
Alice voit les lignes 2 et 4
-
Cynthia ne voit aucune ligne, car "Utilisateurs" n’est pas une valeur incluse dans "Utilisateur"
Pour éviter d’inclure des valeurs non désirées, il est préférable d’ajouter un caractère spécial (ex : #) pour encadrer chaque valeur des groupes ou des utilisateurs dans la colonne et d’ajouter le même caractère autour de la variable.
nomDeLaColonne=operateur=#@DcUserGroups#
| id | donnée | auth_group |
|---|---|---|
1 |
Donnée1 |
#Admin# |
2 |
Donnée2 |
#Utilisateur#Administrateur# |
3 |
Donnée3 |
#Admin#Utilisateur# |
4 |
Donnée4 |
#Admin#Administrateur#Utilisateur# |