Uso de la API

Nota:

Nos esforzamos por hacer que la API sea predecible, así como fácil de usar e integrar. Si tienes algún comentario que pueda ayudarnos a mejorarlo, o si tienes algún problema o comportamiento inesperado, ponte en contacto con el soporte técnico. Nos pondremos en contacto con usted lo antes posible.

Punto final de API

Todas las solicitudes de API se envían a Communications Mining™ como objetos JSON a su punto final de tenant a través de HTTPS.

Nota:

Puedes ver todos los puntos finales disponibles en el archivo . Además, puedes consultar el Tutorial de la API.

Tenants incorporados a través de UiPath®:

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

Tenants incorporados a través de Communications Mining:

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

Importante:

En Communications Mining™, los datos y flujos de trabajo de desarrollo y producción pueden separarse teniendo tenants independientes o colocándolos en proyectos independientes en el mismo tenant. En cada caso, el acceso a los datos se permite por separado, de modo que los desarrolladores pueden tener acceso de administrador a los datos de desarrollo mientras se pueden colocar controles más estrictos en la producción. Si se utilizan tenants independientes, el punto final de la API es diferente para cada uno de los datos de desarrollo y producción; si se utilizan proyectos independientes en el mismo tenant, se utiliza el punto final de ese único tenant para ambos.

Autenticación

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

Para obtener el token de acceso de desarrollador, proceda de la siguiente manera:

1. Accede a Extracción y Procesamiento Inteligentes (IXP) desde Automation Cloud.

2. Ve a la página Administración .

3. Selecciona Mi cuenta.

4. En Token de API, selecciona el botón Regenerar , que generará un token de acceso.

   

Nota:

Solo puedes tener un token de API activo a la vez. La generación de un nuevo token invalidará el anterior.

Debes incluir el siguiente encabezado HTTP para cada llamada a la API que realices, donde $REINFER_TOKEN es tu token de la API de Communications Mining™.

Authorization: Bearer $REINFER_TOKEN

Los ejemplos de bash en el suponen que has guardado tu token en una variable de entorno. Los ejemplos de Python y Node en asumen que el token se ha almacenado en una variable local REINFER_TOKEN a través de la solución de configuración elegida.

Bash

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

Nodo

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

Respuesta

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

Importante:

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"

Nota:

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

Permisos

Cada punto final de la API de enumera sus permisos necesarios. Para ver los permisos que tienes, ve a la pestaña Gestionar acceso en la página Administración . La pestaña muestra los proyectos a los que tienes acceso y los permisos que tienes en cada proyecto.

Errores

Utilizamos códigos de respuesta HTTP convencionales para indicar el éxito o el fracaso de una solicitud de API. En general, los códigos en el rango 2xx indican éxito, los códigos en el rango 4xx indican un error que resultó de la solicitud proporcionada y los códigos en el rango 5xx indican un problema con Communications Mining.

Las solicitudes de ese error también devolverán un cuerpo con un valor status de error, en lugar de ok, y un mensaje de error que describe el error.

Bash

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

Nodo

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

Respuesta

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

Nota:

Su solicitud puede fallar debido a problemas en su red antes de que llegue a Communications Mining. En tales casos, la respuesta que recibas será diferente de la respuesta de error de Communications Mining descrita anteriormente.

Performance timing

Utilizamos el encabezado HTTP Server-Timing para comunicar el tiempo que tardan en procesarse las solicitudes a nuestra API. Incluimos una única métrica, total, que puedes utilizar para medir cuánto tiempo tardó nuestra plataforma en procesar tu solicitud sin latencia de la solicitud de red.

Un ejemplo del encabezado tal y como se muestra en una respuesta:

Server-Timing: total;dur=37.7

Los valores Server-Timing siempre están en milisegundos, por lo que en este caso la solicitud de API con este valor de encabezado tardó 37,7 milisegundos en procesarse en nuestra plataforma.