Exposition API

Logo HandleData HandleData - Version 8.6.0

Pour gérer les Expositions APIs en tant que producteur d’API, vous devez posséder les droits suivants

  • Permissions globales (sur l’utilisateur ou le groupe)

    • "exposition" : pour voir et modifier des Expositions API HandleData

    • "exposition-create" : pour créer de nouvelles Expositions API

  • Droit sur la source des données (DataBlock)

    • "Partages"

  • Droit sur l’Exposition API

    • "Modification"

Pour consommer une API vous devez

  • Être référencé comme utilisateur du module de consommation (future Market Place DataChain)

Les Expositions API permettent de décrire et configurer des APIs data issues de jeux de données (DataBlock) destinés à être consommés en dehors des Projets DataChain.

Pour migrer des Expositions existantes (visibles dans la liste des DataBlocks depuis GenericsData) vers la nouvelle version liées aux éléments partagés de HandleData décrits dans cette page, référez-vous au guide de migration des Expositions.

En résumé

  • Les Expositions API permettent de partager des jeux de données issues des DataBlocks sous forme d’APIs

  • Les paramètres de publication permettent de décrire et paramétrer l’API

    • Les métadonnées publiques décrivent l’API aux consommateurs et le point d’accès permet de personnaliser l’URL d’accès

    • Les paramètres généraux des colonnes définissent les colonnes qui peuvent être exposées dans les paramètres d’accès, ainsi que leurs caractéristiques

    • Les accès API permettent de définir les colonnes et les lignes exposées ainsi que les consommateurs qui peuvent y accéder

      • accès Ouvert (maximum 1) : tous les utilisateurs référencés qui ont accès à la Marketplace DataChain peuvent voir et consommer l’API

      • accès Limité : seuls les utilisateurs et les groupes spécifiés dans l’accès peuvent accéder aux données.
        Attention Les paramètres de l’accès Ouvert ne s’appliquent pas aux utilisateurs des accès limités

      • ffiltre sur ligne : permet de limiter l’accès aux données (ligne)

  • Lorsque que l’API est publiée, il est possible de

    • actualiser les données : les données sont mises à jour à partir de la configuration publiée de l’API (les paramètres de publication ne sont pas prit en compte lors de cette action)

    • supprimer les données : l’ensemble des données (lignes uniquement) sont supprimées de l’API publiée.
      Les métadonnées des colonnes (type, alias et description) restent visibles

    • mettre à jour la configuration de l’API publiée : permet de publier tout ou partie des paramètres de publication (métadonnées, paramètres de colonnes et accès).
      Si les paramètres des colonnes sont mis à jour, les accès et les données sont automatiquement mis à jour.

    • modifier le statut de publication de l’API : si vous désactivez l’API, elle devient Indisponible. Les utilisateurs consommateurs ne peuvent plus consulter la documentation de l’API, ni consommer le jeu de données.
      L’API peut ensuite être activée pour être à nouveau Disponible pour les consommateurs.

  • Le tableau de suivi des mises à jour permet de voir l’historique des mises à jour sur l’API publiée

    • Si une mise à jour échoue, la Publication reste dans sa dernière version stable (par exemple, si vous faites une mise à jour des données et que cette action échoue parce qu’une autre action est déjà en cours, les données resteront disponibles dans la dernière version stable qui a été mise à jour de l’API)

  • Si vous supprimez une Exposition, l’API publiée est automatiquement supprimée en même temps

Généralité

Une Exposition API est un élément DataChain constituée de métadonnées internes, qui identifient l’élément dans le Projet, et d’un ensemble de paramètres de Publication qui permettent de publier une API afin de partager les données d’une source de donnée interne au Projet (DataBlock).

Chaque Publication API est constituée d’un ensemble de métadonnées publiques et d’un jeu de données “à plat” (tabulaire), constitué de colonnes (typées, de 1 à n) et de lignes (de 0 à n).

  • Chaque ligne représente un élément du jeu de données

  • Chaque colonne représente une variable du jeu de données

Les données et les métadonnées d’une Publication API peuvent être consultées par tous les consommateurs qui ont accès à l’API par interrogation de l’API publiée.

Les Publications API sont accessibles par

  • des utilisateurs consommateurs, référencés et authentifiés dans la Plateforme DataChain, qui accèdent aux jeux de données partagés en dehors des Projets

  • des applications tierces (Power-BI, etc)

Les données disponibles (colonnes et lignes) et les fonctionnalités (id, filtrable, …) visibles et disponibles pour les consommateurs dépendent des paramètres de publication.

Source des données

La source des données d’une API est obligatoirement un DataBlock du Projet. Vous devez posséder le droit "Partage" sur la source pour créer une API sur les données du DataBlock.
Il n’est pas possible de modifier la source une fois qu’elle a été sélectionnée.

Les colonnes de type words, binary, files et geometry ne peuvent pas être publiées par API.

Un contrôle d’impact entre les paramètres des colonnes de la source et les paramètres de Publication est effectué en cas de modifications sur le DataBlock.
Par exemple il est impossible de supprimer une colonne dans les paramètres de sortie d’un DataBlock si elle est active dans les paramètres de Publication : vous devez d’abord la désactiver dans les paramètres de publication côté Exposition (et dans les filtres sur ligne si besoin).

Une attention particulière doit être portée au risque d’incohérence entre les paramètres des colonnes la source et la configuration des colonnes de l’API publiée.
La mise à jour des données à partir de la configuration de l’API publiée peut échouer s’il y a une incohérence avec ceux de la source de données.
Pour éviter ce problème, modifiez les paramètres de publication en parallèle de ceux du DataBlock, mettez ensuite à jour la configuration de l’API publiée à partir des nouveaux paramètres.

Exposition API

L’Exposition API est un élément interne au Projet qui permet de configurer et de partager des Publications API.
Les métadonnées de l’Exposition permettent d’identifier et de décrire l’élément dans le Projet et ne sont visibles que par les utilisateurs membres du Projet.

Exposition API -Métadonnées de l’Exposition
Intitulé Description Obligatoire Modifiable

Libellé

Description courte de l’élément

✅

✅

Description

Description longue de l’élément

✅

Tags

Catégorisation de l’élément. Les tags permettent de rechercher un élément

✅

Paramètres de publication

Les paramètres de publication permettent de définir la configuration de l’API qui sera publiée.

Lorsque l’API est publiée, les paramètres de publication peuvent être modifiés sans impacter la configuration de l’API publiée.
Dans ce cas, les paramètres visibles dans les paramètres de publication représentent la version "brouillon" de la configuration de l’API.

Pour mettre à jour la configuration d’une API publiée à partir des paramètres de publication, utilisez le bouton Mise à jour de la configuration situé dans la zone de la Publication API.

Métadonnées publiques

Les métadonnées de la Publication API permettent de définir l’URL d’accès à l’API et de décrire l’API aux consommateurs.

Exposition API -Métadonnées de la Publication API
Intitulé Description Obligatoire Modifiable

Point d’accès

Nom du point d’accès à partir duquel est créé l’URL d’accès à l’API

✅

✅

Titre

Description courte de l’API publiée

✅

✅

Détails

Description longue destinée aux consommateurs de l’API

✅

Mots clés

Catégorisation de l’élément. Les mots clés sont une caractéristique de filtre pour les consommateurs

✅

Paramètres généraux des colonnes

Les Paramètres généraux des colonnes définissent les colonnes qui peuvent être exposées depuis les paramètres d’accès à l’API.
Différents paramètres peuvent être activés sur chaque colonne exposée.

Exposition API -Paramètres généraux des colonnes
Intitulé Description Obligatoire Modifiable Type de colonnes concernées

Type

Type de la colonne (issus de la source)

-

Toutes

Libellé

Libellé de la colonne dans la source

-

Toutes

Alias

Libellé unique, normalisé et public de la colonne, visible par les consommateurs.
L’alias doit être utilisé pour écrire les filtres.
Si un accès possède un filtre sur ligne lié à une colonne et que vous modifiez l’alias, vous devez aussi modifier le filtre pour qu’il fonctionne à nouveau.

✅

✅

Toutes

État (Actif / Inactif)

Activer pour que la colonne soit disponible pour être exposée dans les accès

✅

✅

Toutes

Description

Description publique de la colonne, visible par les consommateurs

✅

Toutes

Id

Cocher pour que la colonne soit définie comme identifiant unique.
Les consommateurs pourront accéder à une ligne par son identifiant.
Une seule colonne peut être définie comme identifiant

✅

Toutes sauf Liste

Filtrable

Cocher pour que les consommateurs puissent filtrer les données selon l’une des valeurs de la colonne.
À décocher pour optimiser les performances.

✅

✅

Toutes sauf Liste

IC

Cocher pour rendre la recherche par filtre insensible à la casse.
Impacte à la fois les filtre effectués côté consommateurs de l’API et les filtres sur lignes défini dans les paramètres des accès

✅

Chaîne de caractères uniquement

Masquer

Cocher pour rendre la colonne et les lignes inaccessibles à tous les consommateurs tout en conservant la capacité à l’utiliser dans les filtres sur lignes.
Cette option est particulièrement adaptée pour les filtres sur ligne pour les groupes et les utilisateurs

✅

Toutes sauf Liste

Hachable

Cocher pour pouvoir activer l’option “Hacher” pour cette colonne dans les paramètres accès.
Les données seront visibles hachées uniquement pour les consommateurs concernés par le filtre où l’option est cochée.

✅

Chaîne de cratères et liste de chaîne de caractères

Accès à l’API

L’accès permet de paramétrer les colonnes exposées, de restreindre l’accès aux lignes et de définir des consommateurs qui pourront accéder à l’API.
Il est possible de configurer plusieurs accès pour une même API.
Seuls les utilisateurs avec l’accès au module de consommation sont visibles dans la liste et peuvent consommer l’API.

Exposition API -Paramètres d’accès
Intitulé Description

Métadonnée de l’accès

  • Libellé : description courte de l’accès

  • Description : description longue de l’accès

  • État : si l’accès est inactif, il ne sera pas pris en compte lors de la publication des paramètres

Type d’accès

  • Ouvert : tous les utilisateurs référencés qui ont accès au module de consommation peuvent accéder à l’API et aux données définies dans cet accès

  • Limité : seuls les utilisateurs et les membres des groupes ajoutés dans l’accès peuvent accéder à l’API et aux données définies dans cet accès
    Attention, les paramètres de l’accès ouvert ne s’appliquent pas aux utilisateurs et groupes des accès Limité.

Consommateurs

Si l’accès est Limité, au moins un groupe ou un utilisateur doit être sélectionné

Colonnes

  • Active : activer les colonnes qui seront visibles pour les consommateurs de cet accès

  • Hacher : les valeurs seront visibles mais hachées

Lignes

Utilisez le filtre sur ligne pour restreindre l’accès aux lignes des données.
Attention, il n’est pas possible de filtrer sur une colonne inactive ou hachée.

Filtre sur ligne

L’accès aux données exposées peut être limitée en ajoutant un ou plusieurs filtres sur lignes.
L’option "IC" (insensible à la casse) qui peut être activée dans les paramètres des colonnes impact aussi le filtre sur ligne des accès.

Le filtre ne pourra pas fonctionner s’il est positionné sur une colonne qui est inactive ou hachée dans le paramètre de l’accès ou si l’Alias utilisé n’est pas le même que celui de la Colonne.
Si le filtre contient une erreur, aucune donnée (ligne) ne sera disponible pour les consommateurs concernés par l’accès.
Exposition API -Type de colonnes disponibles pour le filtre sur ligne
Type Filtrable

String

✅

Integer

✅

Big Integer

✅

Boolean

✅

Décimal

✅

Liste (tous types de liste)
Syntaxe simple

Colonne Opérateur 'Valeur'

VILLE=='grenoble'

Résultat : les consommateurs ne voient que les lignes qui contiennent la valeur "grenoble" dans la colonne "VILLE"

Syntaxe avec filtre cumulatif

(Colonne Opérateur "Valeur" or Colonne Opérateur "Valeur") and (Colonne Opérateur "Valeur")

(VILLE=="grenoble" or CP=="38000") and (ANNE>="2020")

Résultat : les consommateurs ne voient que les lignes qui contiennent la valeur "grenoble" OU qui contiennent la valeur "38000" dans la colonne "CP" ET toutes les valeurs supérieur ou égal à "2020" de la colonne "ANNEE"

En savoir + sur la syntaxe des filtres.

Exemple

Une entreprise gère ses utilisateurs par groupes nommés par leur région.

Exposition API -Le jeu de données
year CA region

2022

892 235

Bretagne

2022

598 123

Auvergne-Rhône-Alpes

2022

125 789

Grand Est

2022

895 333

Corse

2023

592 683

Bretagne

2023

578 632

Auvergne-Rhône-Alpes

2023

859 265

Grand Est

2023

779 225

Corse

Accès Bretagne

  • Nom de l’accès : Bretagne

  • Accès Limité : 1 groupe

    • "Région Bretagne"

  • Colonnes actives : year, CA

  • Filtre sur lignes : region=="Bretagne"

Résultat

Les membres du groupe "Région Bretagne" voient uniquement les valeurs de la colonne A et B et les lignes 1 et 4.

Exposition API -Résultat pour les utilisateurs membres du groupe Bretagne
Year CA

2022

892 235

2023

592 683

Accès Bretagne et Corse 2022 et 2023

  • Nom de l’accès : Bretagne et Corse 2022

  • Accès Limité : 2 groupes

    • "Région Bretagne"

    • "Région Corse"

  • Colonnes actives : Year, CA

  • Filtre sur lignes : (region=="Bretagne" or region=="Corse") and (year=="2022")

Résultat

Les membres du groupe "Région Bretagne" et ceux de "Région Corse" voient les valeurs des colonnes Year et CA et les lignes 1 et 5.

Exposition API -Résultat pour les utilisateurs membre du groupe Bretagne
Year CA

2022

892 235

2022

895 333

Règle de syntaxe

Exposition API -Règle de syntaxe sur les filtres
Syntaxe Cas d’usage

()

utiliser pour regrouper 2 conditions non cumulatives (or)

or

utiliser pour ajouter une condition optionnelle

and

utiliser pour ajouter une condition obligatoire

"" ou ''

utiliser les simples ou les doubles côtes pour encadrer les valeurs

Opérateurs sur les valeurs

Les opérateurs possèdent la même syntaxe pour les filtres côté producteur et consommateur.

Exposition API -Convention / Opérateurs
Opérateur Syntaxe Types acceptés Exemple

Égal

==

String, Numérique, Booléen, Date

nom=='mon ami' ou nom==ami

Différent

!=Les actions disponibles sur une Publication API

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)

Ne contient pas

=notContains=

string

=notContains=(B)

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

Limiter l’accès en fonction de groupes ou d’utilisateur définis dans une colonne de la source

Il est possible de limiter l’accès aux lignes en fonction des valeurs qu’elles contiennent.

Pour limiter l’accès en fonction d’un groupe ou d’un utilisateur défini dans une colonne de la source, vous devez utiliser les opérateurs spécifiques décrits ci-dessous.

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 afficher cette colonne en cochant l’option "Masquer" depuis les paramètres généraux des colonnes.

Syntaxe attendue

nomDeLaColonne=operateur=variable
Exposition API -Opérateurs sur les utilisateurs et les groupes
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 groupe 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 du groupe Utilisateurs

Exposition API -Colonnes et valeurs du Datablock
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
Exposition API -Variable
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.

Exposition API -Exemple de variable sécurisée
nomDeLaColonne=operateur=#@DcUserGroups#
Exposition API -Colonnes et valeurs du Datablock sécurisées
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#

Créer une Exposition API

Depuis HandleData, cliquez sur le menu Partages  Expositions pour accéder à la liste des Expositions puis cliquez sur l’icône Nouveau.

La création se décompose en 4 étapes.

Exposition API -Création d’une Exposition
Etape Description

DataBlock

Sélectionnez le jeu de données source de l’Exposition API.
Seuls les DataBlocks sur lesquels vous possédez le droit "Partage" sont visibles dans la liste.
Il n’est pas possible de modifier la source une fois que l’Exposition est créée.

Métadonnées

  • Exposition : définissez les métadonnées visibles uniquement par les membres du Projet DataChain Core

  • Publication API : définissez les métadonnées visibles par les consommateurs de l’API

Colonnes

Activez les colonnes à publier et configurez les paramètres généraux des colonnes

Accès

Paramétrez un premier accès à l’API.
Il peut être "Ouvert" (tous les utilisateurs qui ont accès au module de consommation) ou ne concerner que certains utilisateurs.
Il est possible de limiter l’accès aux données avec un filtre sur lignes.

Dès que l’Exposition est créée, l’API peut être publiée depuis la liste, ou depuis la page de l’Exposition, à partir du bouton Publier.

Gérer une Publication API

Tous les utilisateurs qui possèdent le droit "Partage" sur le DataBLock source peuvent modifier et réaliser des actions sur la Publication API.

Pour que l’API soit visible par les consommateurs et que les données puissent être consommées, l’API doit avoir été publiée.

Si une action échoue, les données de l’API restent disponibles dans leur dernier état stable.

Les actions disponibles sur une Publication API dépendent de son statut.

Si une action groupée est lancée depuis le tableau des Expositions, il est possible de lancer des actions en incohérence avec le statut.
Par exemple, si vous lancez une mise à jour des données sur une API non publiée, cette action sera en échec et l’API restera non publiée.

Statut de Publication de l’API

  • Non publiée : l’API n’a jamais été publiée, les consommateurs ne voient ni les métadonnées de l’API, ni les données

  • Disponible : l’API est publiée et les données peuvent être consommées

  • Indisponible : l’API est publiée mais elle a été désactivée, c’est-à-dire que les données (colonnes et lignes) ne peuvent plus être consommées, seules les métadonnées sont encore consultables (URL d’accès, titre, description et mots clés)

Action Détail Disponible Indisponible Non publiée

Publier

Publie l’API pour la première fois. Si la tâche s’effectue correctement, l’API est Disponible

✅

Actualiser les données

Met à jour les données (lignes) de l’API à partir de la configuration API publiée.
Si vous avez modifié les paramètres de publication, utilisez l’action Mettre à jour la configuration pour actualiser les données à partir de nouveaux paramètres.
Il est possible d’automatiser cette action depuis DC-Maestro.

✅

✅

Vider les données

Supprimer l’ensemble des données (lignes) de l’API.
L’API renvoie toujours les métadonnées (Publication et colonne).
Utilisez les actions Actualiser les données ou Mettre à jour la configuration pour actualiser les données.

✅

✅

Désactiver

Rend la Publication API Indisponible : seules les métadonnées de la Publication sont encore consommables.
Utilisez l’action Activer pour que les données (colonnes et lignes) soient à nouveau disponibles

Activer

Rend la Publication API Disponible : les métadonnées et les données (colonnes et lignes) de la Publication sont consommables.

✅

Mettre à jour la configuration

Met à jour tout ou une partie de la configuration de l’API (métadonnées, paramètres des colonnes, accès).
Si les paramètres des colonnes sont mis à jour, les accès doivent aussi être mis à jour et les données (lignes) de l’API seront actualisées à partir de ces nouveaux paramètres.

✅

✅

Publier l’API

Au moins un accès doit être actif pour pouvoir publier l’API.
L’action peut prendre quelques minutes.
Si l’action s’est déroulée correctement, l’APi est publiée et elle est disponible pour les consommateurs.

Il est possible de publier une API depuis la page de l’Exposition ou depuis liste : soit sur l’élément, soit en action groupée.

Les accès inactifs ne sont pas publiés, ils n’auront donc aucun effet pour les consommateurs.

Actualiser les données

Cette action permet de mettre à jour l’ensemble des données de l’API à partir de la configuration publiée de l’API.
Il est possible d’automatiser cette action depuis DC-Maestro.

Il est possible d’actualiser les données depuis la page de l’Exposition ou depuis liste : soit sur l’élément, soit en action groupée.

Si des modifications ont été apportées sur la source, il est possible que le schéma des colonnes de la source et des paramètres de publication soient en conflit et que la mise à jour ne puisse pas être réalisée.
Dans ce cas, l’API et les données qu’elle contient ne sera pas mise à jour : elle reste dans son dernier état stable publié.

Modifiez les paramètres de publication pour corriger le problème puis mettez à jour la configuration des colonnes de l’API. L’action mettra à jour les données en même temps.

Supprimer les données

Cette action permet de supprimer l’ensemble des données de l’API.

Les métadonnées, y compris celles des colonnes (alias, type et description) sont toujours visibles pour les consommateurs.

Mettre à jour de la configuration

Une fois que l’API est publiée, il est possible de mettre à jour la configuration de l’API.

Les Paramètres d’une Publication peuvent être modifiés de façon indépendante : tant que vous n’avez pas mis à jour la configuration de l’API publiée, l’API publiée n’est pas impactée par les modifications que vous effectuez sur les paramètres de Publication.

Modifier les paramètres de Publication

Certaines modifications entraînent des modifications automatiques ou nécessitent que vous effectuez des modifications sur les accès.

Exposition API -Modification sur les paramètres généraux des colonnes
Intitulé Mise à jour dans l’accès

État

* Une modale de confirmation vous permet de choisir si les colonnes activées doivent être ajoutées comme actives ou inactives dans les accès existants. * Les colonnes désactivées sont automatiquement désactivées dans tous les accès : si des filtres sur colonnes étaient positionnés sur ces colonnes, ils ne sont plus fonctionnels.

Alias

Si des filtres sur colonnes étaient positionnés sur ces colonnes, ils ne sont plus fonctionnels.

Id

Aucun impact sur les accès

Filtrable

Aucun impact sur les accès

IC

Les filtres sur colonnes deviendront sensibles ou insensibles à la casse selon si l’option est activée ou désactivée.

Masquer

Aucun impact sur les accès

Hachable

* Option activée : l’option hacher sera disponible mais devra être coché manuellement * Option désactivée : les options hachées seront désactivées automatiquement

Mettre à jour de la configuration

Lorsque vous avez réalisé les modifications nécessaires sur tout ou une partie des paramètres de publication (métadonnées, paramètres généraux des colonnes, accès à l’API), cliquez sur Mettre à jour la configuration.

Attention, si vous avez désactivé des colonnes ou modifié leur Alias dans les paramètres généraux des colonnes, pensez à vérifier que les filtres sur lignes définis dans les accès ont bien été mis à jour avec le nouvel Alias.
Le filtre ne pourra pas fonctionner dans le cas contraire.

L’API est mise à jour en fonction des paramètres que vous avez sélectionnés

  • Métadonnées : impacte uniquement les métadonnées publiques de l’API, ne met pas à jour les données

  • Colonnes : met à jour les données. Les accès doivent obligatoirement être mis à jour en même temps que les colonnes

  • Accès : ne mettent pas à jour les données. Il est possible de mettre à jour uniquement les accès

Modifier le statut de publication de l’API

Les actions "Activer" et "Désactiver" modifient le statut de la Publication API et l’accès aux données.

  • Disponible : l’API est publiée. Les métadonnées et les données peuvent être consommées

  • Indisponible : l’API est publiée mais elle a été désactivée, c’est-à-dire que les données (colonnes et lignes) ne peuvent plus être consommées, seules les métadonnées sont encore consultables (URL d’accès, titre, description et mots clés)

Il est possible de modifier le statut depuis la page de l’Exposition ou depuis liste : soit sur l’élément, soit en action groupée.

Suivre les mises à jour

Le tableau de suivi des mises à jour indique les dernières actions réalisées sur l’API.

Si une mise à jour échoue, la Publication reste dans sa dernière version stable.

Par exemple, si vous faites une mise à jour des données et que cette action échoue parce qu’une autre action est déjà en cours, les données resterons disponibles dans la dernière version stable qui a été mise à jour de l’API.

Supprimer une Exposition API

La suppression d’une Exposition associée à une API publiée entraîne la suppression immédiate de la publication API.
L’ensemble des données exposées sont supprimées, mais il est toujours possible de créer une nouvelle Exposition depuis le DataBlock source.

Consommation des APIs

Si l’API contient un accès Ouvert, tous les utilisateurs qui ont accès au module de consommation peuvent voir la Publication API et consommer les données.
Si l’API contient uniquement un ou plusieurs accès Limité, seuls les utilisateurs et les groupes présents dans les accès Limités peuvent accéder à la Publication et ses données.

Si l’API contient à la fois un accès Ouvert et des accès Limités les paramètres de l’accès Ouvert ne sont pas appliqués aux consommateurs des accès Limités.

Les colonnes et les lignes qu’un utilisateur voit dépendent des paramètres de l’accès dans lequel il se trouve.

Cas d’un utilisateur défini dans plusieurs accès

Les données disponibles pour un utilisateur sont impactées s’il est présent dans les paramètres de plusieurs accès (en tant qu’utilisateur ou via son groupe).

  • Colonnes accessibles : seules les valeurs et les colonnes communes aux 2 accès sont disponibles (synthèse restrictive)

  • Filtre sur lignes : toutes les règles définies dans les filtres sont cumulées (synthèse additive)

Exemple

Exposition API -Le jeu de données
Colonne A Colonne B Colonne C

Valeur 1A

Valeur 1B

Valeur 1C

Valeur 2A

Valeur 2B

Valeur 2C

Valeur 3A

Valeur 3B

Valeur 3C

Valeur 3A

Valeur 3B

Valeur 3C

Paramètres des accès dans lequel l’utilisateur est ajouté comme consommateur (via ses groupes par exemple)

  • Accès 1 : Colonne A et B actives + valeurs de ligne qui contiennent 1

  • Accès 2 : Colonne B et C active + valeurs de ligne qui contiennent 3

    Résultat

    Le consommateur voit uniquement les valeurs de la colonne B et les lignes 1 et 3

Colonne B

Valeur 1A

Valeur 2A

Valeur 3A

Valeur 3A

Conditions d’accès à l’API d’un DataBlock

Pour consommer un élément partagé en dehors de DataChain Core, une API d’un DataBlock, vous devez avoir accès au module de consommation.

En tant que consommateur, vous pouvez accéder aux APIs * auxquelles vous avez été ajouté comme consommateur (vous ou un groupe dont vous faites partie) * qui sont accessibles pour tous les utilisateurs du module de consommation

Les API peuvent être consommées directement à partir de l’URL d’accès à l’API qui pourra vous être communiqué par le producteur de l’API.

Syntaxes et opérateurs de requêtes

Exposition API -Exemple d’une requête vers l’API d’exposition
https://monInstance/dcv-api/version/data/exposition?select=id,nom&filter=nom=beginsWith=A
Exposition API -Syntaxes des requêtes (consommation uniquement)
Syntaxe Description Obligatoire ?

http://…​../service/data/

URL d’accès de base

OUI

exposition?

Nom du point d’accès attribué lors du paramétrage de l’API au niveau du DataBlock

OUI

select=

Sélectionne les colonnes à renvoyer dans la réponse.
Si cette section n’est pas précisée, l’ensemble des colonnes exposées sont retournées.

filter=

Filtres en fonction des paramètres de filtres définis
Exemple : filter=nom=beginsWith=A
En savoir + sur la syntaxe des filtres.

page=

Indique la page retournée. Par défaut, il s’agit de la page 1
Exemple : page=5

hitsPerPage=

Indique le nombre de lignes par page
Exemple : hitsPerPage=50

useCache=

Indique si le cache (persistance) est utilisé ou non
Exemple : useCache=true

sort=

Tri en fonction des paramètres définis
Exemple : sort=nom:desc

ctx:

Indique le contexte de l’instance utilisée
Exemple : ctx:0

&

Caractère à ajouter entre chaque filtre
Exemple : sort=ipp:asc,nom:desc&hitsPerPage=50