Méthode api_post()

Envoie une requête POST à l'API HighBond.

Syntaxe

hcl.api_post("Détails de la requête de l'API HighBond", data = charge_utile_de_requête)

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_post 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 :

  • Informations sur l'hôte

  • Région Diligent One

  • ID d'instance Diligent One (ID d'organisation)

  • Informations sur l'en-tête

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
data = charge_utile_de_requête

Les données à envoyer au serveur API Diligent One.

Les données de la charge utile doivent être au format JSON.

Valeurs renvoyées

Objet de réponse du serveur API HighBond.

Exemples

Créer un problème dans un projet Diligent One

Créez une charge utile de requête au format JSON et affectez-la à la variable payload. Utilisez ensuite la méthode hcl.api_post, et référencez la variable payload dans la méthode pour créer un problème dans le projet avec l'ID 19756.

Conseil

Pour construire rapidement une syntaxe de charge utile, copiez le bloc de syntaxe de charge utile approprié à partir de la référence d'API HighBond. Une fois le bloc de charge utile copié, vous pouvez supprimer les paires clé-valeur que vous souhaitez laisser vides.

payload = {"data":
        { 
            "type": "issues",
            "attributes": {
                "description": "Description of issue",
                "owner": "Jane Sleaman",
                "deficiency_type": "Deficiency",
                "title": "Data retention and backup",
                "severity": "High",
                "published": True,
                "identified_at": "2021-11-01T18:15:30Z"
                    }
                }
            }

hcl.api_post("projects/19756/issues", data = payload)

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")