Utilisation de l'API

Remarque :

Nous nous efforçons de rendre l'API prévisible, et facile à utiliser et à intégrer. Si vous avez des commentaires qui pourraient nous aider à l'améliorer, ou si vous rencontrez des problèmes ou un comportement inattendu, contactez l'assistance. Nous vous répondrons dans les plus brefs délais.

Point de terminaison de l’API

Toutes les demandes d’API sont envoyées à Communications Mining™ en tant qu’objets JSON vers le point de terminaison de votre locataire via HTTPS.

Remarque :

Vous pouvez afficher tous les points de terminaison disponibles dans le fichier . De plus, vous pouvez consulter le Tutoriel de l’API.

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 :

Dans Communications Mining™, les données de développement et de production ainsi que les workflows peuvent être séparés soit par 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, le point de terminaison de ce seul locataire est utilisé pour les deux.

Authentification

Toutes les requêtes d’API nécessitent une authentification afin d’identifier l’utilisateur effectuant la requête. Deux méthodes d'authentification sont prises en charge : les jetons d'API de développement et les applications externes (informations d'identification du client OAuth).

Pour obtenir le jeton d'accès au développeur, procédez comme suit :

1. Accédez à IXP depuis Automation Cloud.

2. Accédez à la page Administration .

3. Sélectionnez Mon compte.

4. Sous Jeton d'API, sélectionnez le bouton Régénérer , qui générera un jeton d'accès.

   

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 d’API Communications Mining™.

Authorization: Bearer $REINFER_TOKEN

Les exemples bash supposent que vous avez enregistré votre jeton dans une variable d'environnement. Les exemples Python et Node supposent que le jeton a été stocké dans une variable locale REINFER_TOKEN via la 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"
}

Authentification avec applications externes

Pour les intégrations automatisées ou de serveur à serveur où un jeton d'API de développeur n'est pas approprié, vous pouvez vous authentifier à l'aide d'une Application externe avec le flux Informations d'identification du client.

Étape 1 : créer une application externe

Un administrateur doit créer une application confidentielle et configurer les étendues requises en fonction des API auxquelles vous devez accéder.

Étendues requises :

• PM.User
• PM.User.Read
• Ixp.ApiAccess

Important :

Enregistrez l’ ID d’application et la clé secrète de l’application immédiatement après sa création, car vous ne pourrez pas récupérer la clé secrète ultérieurement.

Pour obtenir des instructions complètes, consultez Gestion des applications externes.

Étape 2 : Attribuez des autorisations d'application

Après avoir créé l'application externe, vous devez lui attribuer les autorisations appropriées avant de pouvoir accéder aux ressources.

1. Accédez à la page Manage Access dans IXP dans votre environnement UiPath.
2. Recherchez votre application par le nom que vous lui avez donné lors de sa création.
3. Attribuez les rôles nécessaires à l'application. L'application apparaîtra dans la liste comme les utilisateurs réguliers.
4. Enregistrez les attributions de rôle.

Pour plus de détails sur l'attribution des autorisations, consultez Gestion des rôles d'utilisateur et de groupe.

Étape 3 : S'authentifier à l'aide du flux d'informations d'identification client

Utilisez le type d'accord Informations d'identification du client pour obtenir un jeton d'accès.

Paramètres requis :

• grant_type=client_credentials
• client_id={app_id} - de l'étape 1
• client_secret={app_secret} - de l'étape 1
• scope : les étendues que vous avez configurées à l'étape 1 (séparées par des espaces)

Pour obtenir les détails d'authentification complets, consultez Applications externes (OAuth).

Étape 4 : utilisez le jeton d'accès

Une fois que vous disposez d'un jeton d'accès, incluez-le dans l'en-tête Authorization de toutes les requêtes d'API.

Authorization: Bearer {access_token}

Exemple de requête :

curl -X GET "https://cloud.uipath.com/{organizationName}/{tenantName}/reinfer_/api/v1/datasets" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

Remarque :

Remplacez {organizationName}, {tenantName} et {access_token} par vos valeurs réelles.

Autorisations

Chaque point de terminaison d'API dans la liste ses autorisations requises. Pour afficher les autorisations dont vous disposez, accédez à l'onglet Gérer l'accès sur la page Administration . L'onglet affiche les projets auxquels vous avez accès et les autorisations dont vous disposez par rapport à 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 d'API. En général, les codes dans la plage 2xx indiquent un succès, les codes dans la plage 4xx indiquent une erreur qui a résulté de la requête fournie, tandis que les codes dans la plage 5xx indiquent un problème avec Communications Mining.

Les demandes de cette erreur renverront également un corps avec une valeur status de error au lieu de ok, ainsi qu'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"
}

Remarque :

Votre demande peut échouer en raison de problèmes sur votre réseau avant qu’elle n’atteigne Communications Mining. Dans de tels cas, la réponse que vous recevrez sera différente de la réponse d’erreur Communications Mining décrite précédemment.

Calendrier de performances

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

Un exemple de l’en-tête, tel qu’il apparaît 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.