Verwenden der API

Hinweis:

Wir versuchen, die API vorhersehbar sowie einfach zu verwenden und zu integrieren. Wenn Sie Feedback haben, das uns helfen könnte, sie zu verbessern, oder wenn Probleme oder unerwartetes Verhalten auftreten, wenden Sie sich an den Support. Wir werden uns so schnell wie möglich bei Ihnen melden.

API-Endpunkt

Alle API-Anforderungen werden als JSON-Objekte über HTTPS an Communications Mining™ an Ihren Mandantenendpunkt gesendet.

Hinweis:

Sie können alle verfügbaren Endpunkte im anzeigen. Darüber hinaus können Sie sich das API-Tutorial ansehen.

Über UiPath® integrierte Mandanten:

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

Über Communications Mining integrierte Mandanten:

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

Wichtig:

In Communications Mining™ können Entwicklungs- und Produktionsdaten und Workflows getrennt werden, indem Sie entweder separate Mandanten haben oder sie in separaten Projekten im selben Mandanten platzieren. In jedem Fall wird der Datenzugriff separat genehmigt, sodass Entwickler Administratorzugriff auf Entwicklungsdaten haben können, während in der Produktion strengere Kontrollen festgelegt werden können. Wenn Sie separate Mandanten verwenden, ist der API-Endpunkt für alle Entwicklungs- und Produktionsdaten unterschiedlich; Wenn Sie separate Projekte im selben Mandanten verwenden, wird der Endpunkt dieses einzelnen Mandanten für beide verwendet.

Authentication

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

Um das Entwicklerzugriffstoken abzurufen, gehen Sie wie folgt vor:

1. Greifen Sie von der Automation Cloud aus auf IXP zu.

2. Gehen Sie zur Administrationsseite .

3. Wählen Sie Mein Konto aus .

4. Wählen Sie unter API-Token die Schaltfläche Erneut generieren aus, wodurch ein Zugriffstoken generiert wird.

   

Hinweis:

Es kann jeweils nur ein API-Token aktiv sein. Das Generieren eines neuen Tokens macht das vorherige ungültig.

Sie müssen den folgenden HTTP-Header für jeden API-Aufruf einschließen, wobei $REINFER_TOKEN Ihr Communications Mining™-API-Token ist.

Authorization: Bearer $REINFER_TOKEN

Die Bash-Beispiele im Abschnitt gehen davon aus, dass Sie Ihr Token in einer Umgebungsvariablen gespeichert haben. Bei den Python- und Knotenbeispielen wird davon ausgegangen, dass das Token über die von Ihnen gewählte Konfigurationslösung in einer lokalen Variablen REINFER_TOKEN gespeichert wurde.

Bash

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

Knoten

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

Antwort

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

Wichtig:

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"

Hinweis:

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

Berechtigungen

Jeder API-Endpunkt in den Listen benötigt die erforderlichen Berechtigungen. Um Ihre Berechtigungen anzuzeigen, wechseln Sie auf der Seite Administration zur Registerkarte Zugriff verwalten . Die Registerkarte zeigt die Projekte an, auf die Sie Zugriff haben, und die Berechtigungen, die Sie in jedem Projekt haben.

Fehler

Wir verwenden herkömmliche HTTP-Antwortcodes, um den Erfolg oder Fehlschlag einer API-Anforderung anzuzeigen. Im Allgemeinen zeigen Codes im Bereich 2xx einen Erfolg an, Codes im Bereich 4xx zeigen einen Fehler an, der aus der bereitgestellten Anforderung resultierende wurde, und Codes im Bereich 5xx weisen ein Problem mit Communications Mining auf.

Fordert diesen Fehler an, gibt auch einen Text mit dem status -Wert von error anstatt ok zurück sowie eine Fehlermeldung, die den Fehler beschreibt.

Bash

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

Knoten

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

Antwort

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

Hinweis:

Ihre Anfrage kann aufgrund von Problemen in Ihrem Netzwerk fehlschlagen, bevor sie Communications Mining erreicht. In solchen Fällen sieht die Antwort, die Sie erhalten, anders aus als die zuvor beschriebene Communications Mining-Fehlerantwort.

Performance timing

Wir verwenden den Server-Title-HTTP-Header , um die Zeit zu kommunizieren, die für die Verarbeitung von Anforderungen an unsere API benötigt wird. Wir fügen eine einzelne Metrik hinzu, total, mit der Sie messen können, wie lange unsere Plattform gedauert hat, um Ihre Anfrage frei von Latenz der Netzwerkanforderung zu bearbeiten.

Ein Beispiel für den Header, wie er in einer Antwort angezeigt wird:

Server-Timing: total;dur=37.7

Server-Timing -Werte werden immer in Millisekunden angegeben. In diesem Fall dauerte die API-Anforderung mit diesem Header-Wert 37,7 Millisekunden, um auf unserer Plattform zu verarbeiten.