Méthode api_get()
Envoie une requête GET à l'API HighBond.
Syntaxe
hcl.api_get("Détails de la requête de l'API HighBond")
Paramètres
| Nom | Description |
|---|---|
| Détails de la requête de l'API HighBond |
Les détails de la requête pour la ressource Diligent One. hcl.api_get fournit automatiquement la partie standard des détails de la requête en arrière-plan. Il n'est pas nécessaire de spécifier explicitement ces éléments de requête, sauf si vous voulez remplacer une valeur par défaut :
Pour la syntaxe de la requête concernant une ressource Diligent One spécifique, consultez la page Référence d'API HighBond. Remarque Si vous spécifiez explicitement des informations sur l'hôte, vous devez utiliser le protocole HTTPS pour vous connecter à l'API HighBond. Par exemple : https://apis-us.highbond.com |
Valeurs renvoyées
Objet de réponse du serveur API HighBond.
Exemples
Exemples de base
Remarque
La méthode hcl.api_get() renvoie un objet de réponse contenant tous les éléments renvoyés par le serveur API HighBond. L'objet de réponse contient à la fois les métadonnées et les données. En général, vous devez appliquer un traitement ultérieur à l'objet de réponse afin d'extraire les données que vous pouvez utiliser dans un script Python/HCL. Pour plus d'informations, consultez Exemples avancés.
Obtenir une liste de tous les projets dans une instance Diligent One
Renvoie une liste de tous les projets de l'instance Diligent One dans laquelle vous travaillez :
hcl.api_get("projects")
Obtenir une liste de toutes les collections dans l'application Diligent One Résultats
Renvoie une liste de toutes les collections de Résultats dans l'instance Diligent One dans laquelle vous travaillez :
hcl.api_get("collections")
Obtenir une liste de l'ensemble des problèmes dans un projet
Renvoie une liste de tous les problèmes dans le projet avec l'ID 19756 :
hcl.api_get("projects/19756/issues")
Obtenir une liste de problèmes et limiter les champs dans la réponse
Renvoie une liste de tous les problèmes dans le projet avec l'ID 19756, et renvoie uniquement les champs spécifiés pour chaque problème :
hcl.api_get("projects/19756/issues?fields[issues]=title,description,creator_name,created_at,updated_at,owner")
Exemples avancés
Accéder à la liste des problèmes dans l'objet de réponse renvoyé par le serveur API HighBond
En général, vous devez manipuler l'objet de réponse renvoyé par le serveur API HighBond afin de pouvoir utiliser les données qu'il contient.
Renvoie un objet de réponse comportant une liste de tous les problèmes dans le projet dont l'ID est 19756 :
response_object = hcl.api_get("projects/19756/issues")
Utilisez la méthode .json() dans la bibliothèque des requêtes Python pour extraire la partie codée en JSON de l'objet de réponse vers un dictionnaire Python. Vous pouvez désormais utiliser les données des problèmes dans un script Python/HCL.
import requests hb_issues_dict = response_object.json()
Vous pouvez également réaliser les deux opérations ci-dessus en une seule étape :
import requests
hb_issues_dict = hcl.api_get("projects/19756/issues").json()
Vous pouvez imprimer le dictionnaire Python à l'écran pour voir le contenu. En l'absence de toute autre mise en forme, le dictionnaire s'affiche sans césure ni retrait pour les éléments imbriqués :
print(hb_issues_dict)
Utilisez la méthode .dumps() de la bibliothèque JSON de Python pour appliquer une mise en forme supplémentaire afin que le contenu du dictionnaire soit plus facile à lire :
import json hb_issues_dict_formatted = json.dumps(hb_issues_dict, indent=4) print(hb_issues_dict_formatted)
Exemple de sortie mise en forme :
{
"data": [
{
"id": "52983",
"type": "issues",
"attributes": {
"title": "Data retention and backup",
"description": null,
"creator_name": null,
"created_at": "2015-05-08T20:59:34Z",
"updated_at": "2016-11-17T18:44:59Z",
"position": 3,
"owner": "Jane Sleaman",
"recommendation": "",
"deficiency_type": "Deficiency",
"severity": "High",
"published": true,
"identified_at": "2015-05-08T20:59:34Z",
"reference": null,
"reference_prefix": "1-A",
"risk": "<p>Data retention and backup policy does not exist</p>\r\n",
"scope": null,
"escalation": null,
"cause": "",
"effect": "",
"cost_impact": 3000.0,
"executive_summary": null,
"executive_owner": null,
"project_owner": null,
"closed": false,
"remediation_status": null,
"remediation_plan": null,
"remediation_date": null,
"actual_remediation_date": null,
"retest_deadline_date": null,
"actual_retest_date": null,
"retesting_results_overview": null,
"custom_attributes": []
},
"relationships": {
"project": {
"data": {
"id": "19756",
"type": "projects"
}
},
"owner_user": {
"data": {
"id": "HWF9X5jpXsS",
"type": "users"
}
},
"executive_owner_user": {
"data": null
},
"project_owner_user": {
"data": null
},
"creator_user": {
"data": null
}
}
}
],
"links": {
"prev": null,
"next": null
}
}
Remarques
Authentification
Toutes les requêtes de l'API HighBond requièrent une authentification. Vous devez être admin système dans au moins une instance Diligent One pour accéder à l'API.
Pour vous authentifier, utilisez la barre de lancement pour créer un jeton d'API HighBond pour votre compte. Le jeton est une chaîne de caractères permettant de vous authentifier et de vous ouvrir un accès sécurisé à l'API HighBond. Pour obtenir de l'aide avec la création d'un jeton, consultez la rubrique Créer et gérer des jetons d'accès HighBond.
Utiliser un jeton d'API HighBond avec les méthodes d'API HighBond
Pour utiliser un jeton d'API HighBond avec les méthodes d'API HighBond, vous devez attribuer le jeton à une variable HCL nommée v_hb_token. Une fois que le jeton est attribué, il est automatiquement utilisé pour l'authentification en arrière-plan sans qu'il soit nécessaire de l'indiquer de façon explicite dans le script Diligent One. Pour obtenir des informations concernant l'attribution du jeton à la variable, consultez la rubrique Utiliser la fenêtre Variables pour définir une variable HCL.
Jeton utilisateur système
Les clients ayant acquis des kits de ressources Diligent One spécifiques ont aussi la possibilité de s'authentifier à l'aide d'un jeton utilisateur système générique plutôt qu'avec un jeton associé à un compte utilisateur spécifique.
Indiquer uniquement la partie unique de l'URL de la ressource
Lorsque vous utilisez une méthode d'API HighBond, vous devez spécifier uniquement la partie unique (ou point de terminaison) de l'URL de la ressource Diligent One. Vous ne devez pas indiquer la partie commune (URL de base) ou l'ID de l'instance Diligent One dans laquelle vous travaillez. Ces informations sont automatiquement fournies en arrière-plan.
Par exemple, si vous travaillez dans une instance Diligent One portant l'ID 1000236, ces deux requêtes d'API renvoient une réponse identique. Elles fournissent toutes les deux la liste de tous les problèmes dans le projet 19756.
hcl.api_get("projects/19756/issues")hcl.api_get("https://apis.highbond.com/v1/orgs/1000236/projects/19756/issues")
Consulter la référence d'API HighBond
La syntaxe des requêtes pour chaque ressource Diligent One se trouve dans la référence d'API HighBond. Voici, par exemple, la syntaxe de requête permettant de récupérer la liste des problèmes dans un projet.
Si vous effectuez la requête à l'aide d'une méthode HCL, vous pouvez commencer à indiquer la syntaxe à projects/....
Si vous effectuez la requête à l'extérieur de Diligent One, vous devez spécifier l'intégralité de l'URL de la ressource, en commençant par le protocole ( https://... ).
Utiliser une variable dans l'URL de la ressource
Plutôt que d'indiquer un ID littéral dans une URL de ressource, il se peut que vous disposiez d'un code nécessitant l'utilisation d'une variable dans l'URL. L'URL de ressource prend la forme d'une chaîne de caractères. Aussi, pour incorporer une variable dans la chaîne de caractères, vous devez utiliser l'une des techniques Python présentées ci-dessous.
Vous pouvez utiliser une chaîne Python de type f :
v_project_id = "19756"
hcl.api_get(f"projects/{v_project_id}/issues")
Vous pouvez utiliser la concaténation des chaînes de caractères Python :
v_project_id = "19756"
hcl.api_get("projects/" + v_project_id + "/issues")
