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

All API requests require authentication to identify the user making the request. Two authentication methods are supported: developer API tokens and External Applications (OAuth Client Credentials).

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

Authentication with external applications

For automated or server-to-server integrations where a developer API token is not appropriate, you can authenticate using an External Application with the Client Credentials flow.

Step 1: Create an external application

An administrator must create a Confidential application and configure the required scopes based on which APIs you need to access.

Required scopes:

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

Important :

Save the App ID and App Secret immediately after creation, as you cannot retrieve the secret later.

For the complete instructions, check Managing External Applications.

Step 2: Assign application permissions

After creating the external application, you must assign it the appropriate permissions before it can access resources.

1. Navigate to the Manage Access page in IXP in your UiPath environment.
2. Search for your application by the name you gave it when you created it.
3. Assign the necessary roles to the application. The application will appear in the list just like regular users.
4. Save the role assignments.

For the complete permission assignment details, check Managing User and Group Roles.

Step 3: Authenticate using the client credentials flow

Use the Client Credentials grant type to obtain an access token.

Required parameters:

• grant_type=client_credentials
• client_id={app_id} - from Step 1
• client_secret={app_secret} - from Step 1
• scope - the scopes you configured in Step 1 (space-separated)

For the complete authentication details, check External Applications (OAuth).

Step 4: Use the access token

Once you have an access token, include it in the Authorization header for all API requests.

Authorization: Bearer {access_token}

Example request:

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

Remarque :

Replace {organizationName}, {tenantName}, and {access_token} with your actual values.

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.

Performance timing

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.