Uso de la API

Te damos la bienvenida a la API de Communications Mining. Nos esforzamos por hacer que la API sea predecible, fácil de usar y fácil de integrar. Si cree que podemos hacer algo para mejorarlo o si encuentra algún error o comportamiento inesperado, póngase en contacto con el soporte y nos pondremos en contacto con usted lo antes posible.

Puedes ver todos los puntos finales disponibles en la Referencia de la API. También hay un tutorial de la API.

Punto final de API

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

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:

ENTORNOS DE DESARROLLO Y PRODUCCIÓN

En Communications Mining, los datos y flujos de trabajo de desarrollo y producción pueden separarse teniendo tenants separados o colocándolos en proyectos separados en el mismo tenant. En cada caso, el acceso a los datos se autoriza por separado (para que los desarrolladores puedan tener acceso de administrador a los datos de desarrollo mientras se pueden aplicar controles más estrictos a 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, el punto final de ese tenant único se utiliza para ambos.

Autenticación

Todas las solicitudes de API requieren autenticación para identificar al usuario que realiza la solicitud. La autenticación se proporciona a través de un token de acceso. El token de acceso de desarrollador se puede obtener en la página Administrar cuenta.

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 la Referencia de la API asumen que has guardado tu token en una variable de entorno. Los ejemplos de Python y Nodo en la Referencia de la API 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"
  }

Permisos

Cada punto final de la API en la Referencia de la API enumera sus permisos necesarios. Puedes ver los permisos que tienes yendo a la página Administrar cuenta. La página 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 la plataforma 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"
  }

Ten en cuenta que tu solicitud puede fallar debido a problemas en tu 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.

Tiempo de rendimiento

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 la latencia de la solicitud de red.

Un ejemplo del encabezado tal y como se verá 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.