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 à
.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+.
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 :
- Connectez-vous à Data360 Govern.
- Dans le menu Profil en haut à droite de l’écran, sélectionnez Clé d’API.
- Copiez la valeur du champ Clé d’API et enregistrez-la en dehors de l’application.
- 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.
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.
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.
En-têtes de requête
Touche d’en-tête | Description |
---|---|
Autorisation |
Spécifie les informations d’identification d’authentification : |
Content-Type |
Spécifie le format des données : |
Accepter |
Spécifie le format de données qui est acceptable pour la réponse : |
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 :
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 :
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 |
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 |
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.
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" } ]
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 :
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 Vous pouvez utiliser le paramètre |
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 |
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ù Par exemple : 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ù Par exemple : |