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

Alle API-Anforderungen erfordern eine Authentifizierung, um den Benutzer zu identifizieren, der die Anforderung stellt. Zwei Authentifizierungsmethoden werden unterstützt: Entwickler-API-Token und externe Anwendungen (OAuth Client-Anmeldeinformationen).

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

Authentifizierung bei externen Anwendungen

Bei automatisierten oder Server-zu-Server-Integrationen, bei denen ein Entwickler-API-Token nicht geeignet ist, können Sie sich mithilfe einer externen Anwendung mit dem Flow der Client-Anmeldeinformationen authentifizieren.

Schritt 1: Erstellen einer externen Anwendung

Ein Administrator muss eine vertrauliche Anwendung erstellen und die erforderlichen Scopes konfigurieren, basierend auf den APIs, auf die Sie zugreifen müssen.

Erforderliche Scopes:

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

Wichtig:

Speichern Sie die App-ID und den geheimen App-Schlüssel sofort nach der Erstellung, da Sie den geheimen Schlüssel später nicht mehr abrufen können.

Die vollständigen Anweisungen finden Sie unter Verwalten externer Anwendungen.

Schritt 2: Anwendungsberechtigungen zuweisen

Nach dem Erstellen der externen Anwendung müssen Sie ihr die entsprechenden Berechtigungen zuweisen, bevor sie auf Ressourcen zugreifen kann.

1. Navigieren Sie in Ihrer UiPath-Umgebung zur Seite Zugriff verwalten in IXP.
2. Suchen Sie Ihre Anwendung anhand des Namens, den Sie ihr bei der Erstellung gegeben haben.
3. Weisen Sie der Anwendung die erforderlichen Rollen zu. Die Anwendung wird wie reguläre Benutzer in der Liste angezeigt.
4. Speichern Sie die Rollenzuweisungen.

Die vollständigen Details zur Berechtigungszuweisung finden Sie unter Verwalten von Benutzer- und Gruppenrollen.

Schritt 3: Authentifizieren Sie mithilfe des Flows für Client-Anmeldeinformationen

Verwenden Sie den Gewährungstyp Client-Anmeldeinformationen , um ein Zugriffstoken zu erhalten.

Erforderliche Parameter:

• grant_type=client_credentials
• client_id={app_id} - von Schritt 1
• client_secret={app_secret} - von Schritt 1
• scope – Die Scopes, die Sie in Schritt 1 konfiguriert haben (durch Leerzeichen getrennt)

Die vollständigen Authentifizierungsdetails finden Sie unter Externe Anwendungen (OAuth).

Schritt 4: Verwenden des Zugriffstokens

Sobald Sie ein Zugriffstoken haben, fügen Sie es in den Authorization -Header für alle API-Anforderungen ein.

Authorization: Bearer {access_token}

Beispielanforderung:

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

Hinweis:

Ersetzen Sie {organizationName}, {tenantName} und {access_token} durch Ihre tatsächlichen Werte.

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.

Leistungszeit

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.