Documentation de l’API - Data360_Govern - Dernière

Aide Data360 Govern

Product type
Logiciels
Portfolio
Verify
Product family
Data360
Product
Precisely Data Integrity Suite > Govern
Data360 Govern
Version
Dernière
Language
Français
Product name
Data360 Govern
Title
Aide Data360 Govern
Copyright
2024
First publish date
2014

Bienvenue dans la documentation de l’API REST Data360 Govern.

Les informations de cette section sont fournies en même temps que la documentation de l’API Swagger, où vous pouvez tester des requêtes et voir les détails de points de terminaison spécifiques. Vous pouvez accéder à la documentation Swagger depuis l’application en accédant à Administration > Intégration > API.

L’API Data360 Govern vous permet d’accéder à l’application via des applications tierces et vous permet de l’intégrer facilement à Data360 Analyze et à Data360 DQ+.

Aperçu de l’API

Gestion des versions

L’API v1 a été dépréciée et ne sera pas prise en charge dans une prochaine version. Veuillez utiliser l’API v2 lorsque cela est possible.

L’application est sécurisée via SNI (Server Name Indication). Vous devez utiliser la version SNI 7.18.1 ou supérieure, et au moins TLS 1.0.

Authentification

Pour vous authentifier, vous devez fournir vos informations d’identification d’API dans l’en-tête de requête au format suivant :

<API Key>;<API Secret>

Obtenir des informations d’identification de l’API

Data360 Govern génère une clé d’API et une clé secrète de l’API pour chaque utilisateur.

Vous pouvez obtenir vos informations d’identification de l’API comme suit :

  1. Connectez-vous à Data360 Govern.
  2. Dans le menu Profil en haut à droite de l’écran, sélectionnez Clé d’API.
  3. Copiez la valeur du champ Clé d’API et enregistrez-la en dehors de l’application.
  4. Copiez la valeur du champ Clé secrète de l’API et enregistrez-la en dehors de l’application. Vous devrez utiliser ces valeurs pour accéder à l’API.
Remarque : Si vous ne disposez pas d’un accès d’administrateur, vous devrez peut-être contacter votre administrateur système si l’option Clé d’API n’est pas visible dans le menu de votre profil utilisateur.

Dans certains cas, par exemple lors d’une intégration à Data360 Analyze, les informations d’identification de l’API utilisées pour se connecter peuvent être celles d’un compte de service qui a été créé spécialement pour votre intégration. Dans ce cas, veuillez contacter votre représentant Precisely pour plus d’informations.

Remarque : Les responsabilités qui vous ont été attribuées dans l’application continueront à s’appliquer lorsque vous accédez aux données via l’API. Par conséquent, vous ne disposez peut-être pas de l’autorisation requise pour afficher ou modifier un asset même si vous vous êtes authentifié avec succès.

Lancer une requête

Une requête est composée des informations suivantes :

  • En-têtes de requête - Fournissez des informations au client et au serveur, notamment les informations d’identification d’authentification et les formats de données acceptés.
  • Méthode - Définit le type de requête à effectuer (GET, POST, PUT et DELETE).
  • Point de terminaison - Indique le mode d’accès à la ressource.
  • Corps - Un corps est envoyé avec les requêtes POST, PUT et DELETE et contient les informations sur lesquelles le serveur doit agir, par exemple le nom d’objet, les champs et les valeurs des champs.

En outre, certains points de terminaison comportent également des paramètres facultatifs ou obligatoires utilisés pour adapter davantage la réponse de l’API.

Remarque : Le format par défaut des requêtes et des réponses est JSON (application/json). Les noms des paramètres utilisent camelCase.

En-têtes de requête

Touche d’en-tête Description
Autorisation

Spécifie les informations d’identification d’authentification :

Authorization: <API Key>;<API Secret>

Content-Type

Spécifie le format des données :

Content-Type: application/json

Accepter

Spécifie le format de données qui est acceptable pour la réponse :

Accept: application/json

Vous pouvez également utiliser un jeton de workflow dans le champ Valeur de l’en-tête. Reportez-vous à Créer un workflow qui appelle une API externe > Étape 2 - Configurer l’activité Requête HTTP pour en savoir plus.

Méthodes et points de terminaison

Les points de terminaison indiquent comment accéder à la ressource, et la méthode de requête HTTP définit le type de requête à effectuer.

L’API Data360 Govern utilise les méthodes standard suivantes pour créer des requêtes :

Méthode Action
GET Récupère les ressources
POST Crée des ressources
PUT

Met à jour les ressources existantes

DELETE Supprime des ressources

Dans certains cas, les requêtes PUT peuvent également être utilisées pour créer des ressources. Par exemple, le point de terminaison PUT api/v2/fields peut être utilisé pour ajouter ou mettre à jour des types de champs. Pour connaître les détails d’un point de terminaison PUT spécifique, reportez-vous aux détails du résumé du point de terminaison dans Swagger, par exemple :

Documentation de l’API Swagger

Chaque ressource dispose de divers points de terminaison associés. Le point de terminaison montre le chemin d’accès final d’une URL de ressource, et le chemin de base est commun à tous les points de terminaison, par exemple :

https://exemple.data3sixty.com/api/v2/assets/types

Corps de la requête

Dans l’interface utilisateur Swagger, chaque méthode d’API nécessitant un corps de requête comprend un modèle d’exemple que vous pouvez utiliser comme point de départ, puis modifier pour répondre aux besoins de votre requête.

Par exemple, le point de terminaison POST /api/v2/metrics/results dispose d’un corps de requête obligatoire qui vous oblige à référencer un UID de l’asset et un UID de l’asset de métrique :

[ { 	"AssetUid": "b1c4f830-c71c-4f95-909d-a1d67ca5361c", 	"MetricAssetUid": "d06f201c-4241-4102-8d68-07d4fb37dfc1", 	"EffectiveDate": "2019-05-08T08:51:56.737Z", 	"Result": true } ]

Dans Swagger, le corps de la requête s’affiche comme suit :

Corps de la requête

Cliquez sur le modèle d’exemple à droite de l’écran pour renseigner le paramètre du modèle à gauche, puis entrez les valeurs réelles de l’UID pour remplacer le texte de la marque de réservation (00000000-0000-0000-0000-000000000000).

Vous devez inclure tous les champs obligatoires dans le corps de la requête, par exemple, lors de la création d’un asset via une requête POST. Les champs facultatifs peuvent être supprimés s’il n’y a pas de valeur à envoyer.

Pour certaines requêtes, par exemple, les requêtes par lot pour de grandes quantités de données, vous pouvez inclure un paramètre facultatif afin de suivre la réussite ou l’échec de l’ajout ou de la mise à jour de l’asset.

Paramètres

Certains points de terminaison comportent également des paramètres facultatifs ou obligatoires utilisés pour adapter davantage la réponse de l’API.

Type de paramètre Description Exemple
Chemin d’accès Paramètres inclus dans le chemin d’accès au point de terminaison, généralement entre accolades.

Le point de terminaison GET /api/v2/assets/fields/{assetTypeUid} inclut un paramètre de chemin d’accès obligatoire, par exemple :

https://example-igx.preview.data3sixty.com/api/v2/assets/fields/188f094b-fb02-4de3-8790-8c0d32d98e1a

Requête Paramètres inclus dans la chaîne de requête d’un point de terminaison, après un caractère '?'.

Le point de terminaison GET /api/v2/fields comporte un certain nombre de paramètres de requête facultatifs. Dans l’exemple suivant, les paramètres Type et _pageSize sont utilisés pour indiquer que la réponse ne doit contenir que des champs de type booléen et que le nombre de résultats par page doit être limité à 100 :

https://example.data3sixty.com/api/v2/fields?Type=Boolean&_pageSize=100

Les détails des paramètres spécifiques se trouvent sur la page de documentation de l’API Swagger.

Exemple de requête

Les exemples de requêtes d’API présentés dans cette section de l’aide utilisent la syntaxe Curl pour afficher toutes les informations requises, notamment les en-têtes de requête, les méthodes, les points de terminaison et les données, ainsi que tous les paramètres obligatoires et facultatifs :

         curl -X GET --header 'Accept: application/json' --header 'Authorization: key;secret' 'https://example.data3sixty.com/api/v2/assets/types'       

Curl fournit une bibliothèque et un outil de ligne de commande pour transférer des données aux serveurs à l’aide de différents protocoles standard, tels que HTTPS.

Remarque : Sous Windows, vous devez remplacer les guillemets simples par des guillemets doubles.

L’exemple suivant montre les informations d’en-tête pour la même requête à utiliser lors de la connexion à l’API Data360 Govern via un client d’API :

GET https://example.data3sixty.com/api/v2/assets/types HTTP/1.1 	Authorization: <API Key>;<API Secret> 	Content-Type: application/json 	Accept: application/json

Évaluer la réponse

Codes de réponse

Code de statut HTTP Description Dépannage
200

Indique la réussite.

N/A
400

Indique une erreur en raison d’une requête non valide.

Vérifiez que vous avez correctement formaté l’identifiant (UID) dans votre requête.
401 Indique une erreur d’authentification.

Vérifiez que l’en-tête de votre requête inclut les informations d’identification d’authentification requises.

Si vous rencontrez toujours des difficultés, il se peut que vous n’ayez pas l’autorisation requise pour afficher ou modifier la ressource en fonction des responsabilités qui vous ont été attribuées dans l’application.

403 Indique une erreur 'accès refusé'. Il se peut que vous n’ayez pas l’autorisation requise pour afficher ou modifier la ressource en fonction des responsabilités qui vous ont été attribuées dans l’application.
404 Indique que la ressource demandée est introuvable. Vérifiez que vous avez correctement formaté l’identifiant (UID) dans votre requête.
406 Indique que la requête ne contient pas le type de paramètre ou les champs requis. Vérifiez que vous avez inclus tous les types et champs de paramètres requis.
409 Indique que la ressource demandée existe déjà. N/A
500 Indique qu’une erreur inconnue s’est produite lors du traitement de la requête. N/A

Exemple de réponse

HTTP/1.1 200 OK "content-length": "2", "content-type": "application/json; charset=utf-8"  [ 	{ 		"uid": "85315000-c77f-4898-84db-f4872cbd2dc0", 		"Name": "Bloomberg", 		"Description": "Metadata via the Bloomberg Fields CSV file and other Bloomberg sources.", 		"Class": { 			"ID": 3, 			"Name": "Technical Asset", 			"Description": "Technical assets." 		}, 		"Path": "Bloomberg" 	}, 	{ 		"uid": "88e6e59c-0cd8-49a9-a4f4-059b7172ddee", 		"Name": "Business Calendar", 		"Class": { 			"ID": 4, 			"Name": "Technical Asset", 			"Description": "Technical assets." 		}, 		"Path": "Business Calendar" 	} ]
Conseil : Dans cet exemple, le premier élément inclut une propriété 'Description', mais la propriété 'Description' n’est pas renvoyée dans le second élément. Dans de nombreux cas, s’il existe des champs personnalisés pour un asset, le nom et la valeur du champ ne peuvent être affichés que si le champ a été renseigné. Remarque : ce comportement n’est pas affecté par la configuration du champ Afficher si vide dans l’application.

Cas d’utilisation courants

L’API Data360 Govern vous permet d’obtenir des informations sur les assets de votre application de gouvernance des données.

Les cas d’utilisation standard sont les suivants :

  • Obtenir des informations sur les assets existants dans votre système de gouvernance des données, y compris des détails sur les relations et la propriété.
  • Ajouter des métadonnées techniques provenant de sources de données externes pour fournir un contexte à vos assets métier.
  • Appliquer l’attribution d’un score à vos assets de gouvernance des données (reportez-vous à Utiliser l’API pour appliquer un score à vos assets).
  • Promouvoir les assets techniques dans votre glossaire métier.

Astuces et conseils

Astuce Description

Points de terminaison du traitement par lot

Lorsque vous utilisez un grand nombre d’éléments, il est recommandé d’utiliser les points de terminaison 'lot'.

Lorsqu’il existe un point de terminaison 'lot', l’équivalent 'non-lot' a souvent une limite de 250 éléments. Les points de terminaison 'lot' sont destinés à un plus grand nombre d’éléments, car ils stockent la liste des éléments pour un traitement asynchrone ou par lots.

Par exemple, vous pouvez utiliser les points de terminaison suivants pour supprimer un ensemble d’assets en fonction de l’identifiant unique du type d’asset spécifié. Le premier est destiné à traiter un plus petit nombre d’éléments, et le second à traiter un plus grand nombre d’éléments :

  • Point de terminaison DELETE /api/v2/assets/{assetTypeUid} - Utilisez ce point de terminaison si vous souhaitez traiter moins de 250 éléments et avez besoin de résultats immédiats.
  • Point de terminaison DELETE /api/v2/assets/batch/{assetTypeUid} - Utilisez ce point de terminaison lors du traitement d’un nombre supérieur d’éléments.
Remarque : Il est recommandé de ne pas utiliser l’interface utilisateur Swagger pour les requêtes volumineuses. Pour gérer les requêtes plus volumineuses, il est recommandé d’utiliser un autre client d’API.
Remarque : Chaque environnement est limité à deux requêtes par lot à la fois.
Remarque : Il n’est pas garanti que l’ordre d’exécution des appels d’API par lot corresponde à l’ordre dans lequel les tâches ont été envoyées. Par exemple, si vous envoyez dix tâches par lot dans les 30 secondes, les tâches ne seront pas nécessairement exécutées dans l’ordre dans lequel elles ont été envoyées.

Taille de la page

Il n’y a pas de taille maximale de page. Toutefois, il est recommandé de limiter la taille de la page en fonction de la taille de votre requête. Par exemple, lors de l’utilisation du point de terminaison GET /api/v2/assets/{assetTypeUid}, il est recommandé de restreindre la taille de page à 1 000 ou moins, en fonction de la quantité de contenu que vous appelez.

Vous pouvez utiliser le paramètre _pageSize pour restreindre le nombre de résultats renvoyés par page. La valeur par défaut est de 200.

Propriétés JSON

En raison de la manière dont le sérialiseur JSON traite les données, si la valeur est nulle, il n’y a aucune garantie que la propriété sera affichée. De même, l’ordre des propriétés qui sont retournées n’est pas toujours le même.

En-tête X-HTTP-Method-Override

Pour éviter d’effectuer une requête POST avec un corps, vous pouvez utiliser X-HTTP-Method-Override: DELETE dans l’en-tête de la requête. Par exemple, lors de la suppression des relations dans Data360 Govern, via un connecteur.

Champs clés des assets

Lorsque vous exécutez une mise à jour (requête PUT), l’API recherche toutes les valeurs de champ clés, en utilisant l’UID de l’asset fourni. Un message d’erreur s’affiche si le type d’asset spécifié a un champ clé défini et que certains assets ont une valeur NULLE pour ce champ.

Liens vers les assets

Tout asset est accessible via le lien suivant, où <environment> est remplacé par votre hôte <asset uid> et Data360 est remplacé par la valeur UID d’un asset :

https://<environment>.data3sixty.com/asset/<asset uid>

Par exemple :

https://example.data3sixty.com/asset/5f2692c7-6d64-4e23-9a11-faa69a7f35de

Vous pouvez accéder à la page de liste des types d’assets pour les assets métier, techniques, de modèle ou de règle sur le lien suivant, où <environment> est remplacé par votre hôte <asset type uid> et Data360 est remplacé par la valeur UID du type d’asset :

https://<environment>.data3sixty.com/assets/<asset type uid>

Par exemple :

https://example.data3sixty.com/assets/188f094b-fb02-4de3-8790-8c0d32d98e1a