Utilisation de l'API

Bienvenue dans l'API Communications Mining. Nous nous efforçons de rendre l'API prévisible, facile à utiliser et simple à intégrer. Si vous pensez que nous pouvons l’améliorer ou si vous rencontrez des bugs ou un comportement inattendu, veuillez contacter le support et nous vous répondrons dans les plus brefs délais.

Vous pouvez voir tous les points de terminaison disponibles dans la référence de l'API. Il existe également un API Tutoriel.

Point de terminaison de l’API

Toutes les requêtes d'API sont envoyées à Communications Mining en tant qu'objets JSON à votre point de terminaison locataire via HTTPS.

Locataires intégrés via UiPath :

https://cloud.uipath.com/<my_uipath_organisation>/<my_uipath_tenant>/reinfer_/api/...

Locataires intégrés via Communications Mining :

https://<mydomain>.reinfer.io/api/...

Important :

ENEnvironnements de développement et de production

Dans Communications Mining, les données et les workflows de développement et de production peuvent être séparés soit en ayant des locataires distincts, soit en les plaçant dans des projets distincts dans le même locataire. Dans chaque cas, l'accès aux données est autorisé séparément (afin que les développeurs puissent avoir un accès administrateur aux données de développement tandis que des contrôles plus stricts peuvent être placés sur la production). Si vous utilisez des locataires distincts, le point de terminaison de l'API est différent pour chacune des données de développement et de production ; si vous utilisez des projets distincts dans le même locataire, ce point de terminaison du locataire unique est utilisé pour les deux.

Authentification

Toutes les requêtes d'API nécessitent une authentification pour identifier l'utilisateur effectuant la requête. L'authentification est fournie via un jeton d'accès. Le jeton d'accès pour développeur peut être obtenu depuis votre page Gérer le compte (Manage Account).

Remarque :

Vous ne pouvez avoir qu'un seul jeton API actif à la fois. La génération d’un nouveau jeton invalidera le précédent.

Vous devez inclure l'en-tête HTTP suivant pour chaque appel API que vous effectuez, où $REINFER_TOKEN est votre jeton API Communications Mining.

Authorization: Bearer $REINFER_TOKEN

Les exemples bash de la référence d'API supposent que vous ayez enregistré votre jeton dans une variable d'environnement. Les exemples Python et Node dans la Référence d'API supposent que le jeton a été stocké dans une variable locale REINFER_TOKEN via votre solution de configuration choisie.

• Bash

  curl -X GET 'https://<my_api_endpoint>/api/...' \
      -H "Authorization: Bearer $REINFER_TOKEN"

• Nœud

  const request = require("request");
  
  request.get(
    {
      url: "https://<my_api_endpoint>/api/...",
      headers: {
        Authorization: "Bearer " + process.env.REINFER_TOKEN,
      },
    },
    function (error, response, json) {
      // digest response
      console.log(JSON.stringify(json, null, 2));
    }
  );

• Python

  import json
  import os
  
  import requests
  
  response = requests.get(
      "https://<my_api_endpoint>/api/...",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• Réponse

  {
    "status": "ok"
  }

Autorisations

Chaque point de terminaison d'API dans la Référence d' API (API Reference) répertorie ses autorisations requises. Vous pouvez afficher les autorisations dont vous disposez en accédant à votre page Gérer le compte (Manage Account). La page affiche les Projets auxquels vous avez accès et les Autorisations que vous avez dans chaque projet.

Erreurs (Errors)

Nous utilisons des codes de réponse HTTP classiques pour indiquer la réussite ou l'échec d'une requête API. En général, les codes de la plage 2xx indiquent la réussite, les codes de la plage 4xx indiquent une erreur résultant de la requête fournie, et les codes de la plage 5xx indiquent un problème avec la plate-forme Communications Mining.

Les requêtes renvoyant également un corps avec une valeur status de error au lieu de ok, et un message d'erreur décrivant l'erreur.

• Bash

  curl -X GET 'https://<my_api_endpoint>/api/v1/nonexistent_page' \
      -H "Authorization: Bearer $REINFER_TOKEN"

• Nœud

  const request = require("request");
  
  request.get(
    {
      url: "https://<my_api_endpoint>/api/v1/nonexistent_page",
      headers: {
        Authorization: "Bearer " + process.env.REINFER_TOKEN,
      },
    },
    function (error, response, json) {
      // digest response
      console.log(JSON.stringify(json, null, 2));
    }
  );

• Python

  import json
  import os
  
  import requests
  
  response = requests.get(
      "https://<my_api_endpoint>/api/v1/nonexistent_page",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• Réponse

  {
    "message": "404 Not Found",
    "status": "error"
  }

Notez que votre demande peut échouer en raison de problèmes de réseau avant qu'elle n'atteigne Communications Mining. Dans de tels cas, la réponse que vous recevez sera différente de la réponse d'erreur de Communications Mining décrite ci-dessus.

Synchronisation des performances

Nous utilisons l' en-tête HTTP Server-Timing pour communiquer le temps nécessaire pour que les requêtes soient traitées à notre API. Nous incluons une seule métrique, total, que vous pouvez utiliser pour mesurer le temps que notre plate-forme a mis à traiter votre demande sans latence de la demande de réseau.

Un exemple d'en-tête tel qu'il apparaîtra dans une réponse :

Server-Timing: total;dur=37.7

Les valeurs Server-Timing sont toujours en millisecondes. Par conséquent, dans ce cas, la requête d'API avec cette valeur d'en-tête a pris 37,7 millisecondes à traiter sur notre plate-forme.