API client settings

Wenn Sie einen API-Client einrichten oder bearbeiten, können Sie die folgenden clientspezifischen Einstellungen konfigurieren.

Einstellung	Beschreibung	Hinweise
Client-Obergrenze	Legen Sie die maximalen Kosten für die Abfragekomplexität pro Minute für diesen Client fest.	Wenn dieser Wert den Wert überschreitet, der für die auf Standortebene festgelegte Kundenratengrenze festgelegt wurde, wird stattdessen die Begrenzung auf Standortebene verwendet.
Ablaufen des Tokens	Dies legt fest, wie lange Zugriffstoken gültig sind, bevor sie ablaufen.	Die Standardzeit beträgt 1 Tag. Das Ändern dieser Einstellung wirkt sich nur auf neue Token aus.Alle vorhandenen Token behalten weiterhin die Ablaufzeit bei, die zum Zeitpunkt ihrer Erstellung festgelegt wurde.
Fehlerrückmeldung	Diese Einstellung legt fest, wie viele Informationen in API-Antworten bereitgestellt werden, wenn Fehler für diesen Client auftreten. Wählen Sie eine der folgenden Optionen aus: Standort-Standard (X): Dieser Client verwendet die Option für die Standardfehlerantwort in den standortweiten API-Einstellungen Keine: API-Antworten geben keine spezifischen Informationen über den Fehler zurück Normal: API-Antworten geben spezifische Informationen darüber zurück, warum der Fehler aufgetreten ist Entwickler: API-Antworten geben spezifische Informationen darüber zurück, warum der Fehler aufgetreten ist, einschließlich eines vollständigen Stack-Traces	Standardmäßig verwenden die Kunden die Option Website-Standard (X). Wenn die Standardeinstellung für die Fehlerantwort auf Website-Ebene geändert wird, werden alle Clients, die die Standardoption (X) verwenden, die ausgewählte Option verwenden.

Einstellung

Beschreibung

Hinweise

Client-Obergrenze

Legen Sie die maximalen Kosten für die Abfragekomplexität pro Minute für diesen Client fest.

Wenn dieser Wert den Wert überschreitet, der für die auf Standortebene festgelegte Kundenratengrenze festgelegt wurde, wird stattdessen die Begrenzung auf Standortebene verwendet.

Ablaufen des Tokens

Dies legt fest, wie lange Zugriffstoken gültig sind, bevor sie ablaufen.

Die Standardzeit beträgt 1 Tag.

Das Ändern dieser Einstellung wirkt sich nur auf neue Token aus.Alle vorhandenen Token behalten weiterhin die Ablaufzeit bei, die zum Zeitpunkt ihrer Erstellung festgelegt wurde.

Fehlerrückmeldung

Diese Einstellung legt fest, wie viele Informationen in API-Antworten bereitgestellt werden, wenn Fehler für diesen Client auftreten. Wählen Sie eine der folgenden Optionen aus:

Standort-Standard (X): Dieser Client verwendet die Option für die Standardfehlerantwort in den standortweiten API-Einstellungen
Keine: API-Antworten geben keine spezifischen Informationen über den Fehler zurück
Normal: API-Antworten geben spezifische Informationen darüber zurück, warum der Fehler aufgetreten ist
Entwickler: API-Antworten geben spezifische Informationen darüber zurück, warum der Fehler aufgetreten ist, einschließlich eines vollständigen Stack-Traces

Standardmäßig verwenden die Kunden die Option Website-Standard (X). Wenn die Standardeinstellung für die Fehlerantwort auf Website-Ebene geändert wird, werden alle Clients, die die Standardoption (X) verwenden, die ausgewählte Option verwenden.

API Client IP-Whitelisting

Site-Administratoren können einschränken, welche IP-Adressen über einen bestimmten API-Client Anfragen stellen dürfen. Dies bietet mehr Sicherheit und Kontrolle darüber, wie externe Systeme über die externe API mit Ihrer Totara-Website interagieren.

Warum IP-Whitelisting verwenden?

Zuvor konnte jedes System mit Zugriff auf eine gültige API-Client-ID und ein Geheimnis die externe API verwenden, unabhängig davon, wo die Anfrage ihren Ursprung hatte. Dies bedeutete, dass die API-Nutzung nicht auf vertrauenswürdige Systeme oder Netzwerke beschränkt werden konnte. Um dies zu beheben, wurde ein neues Feld Zulässige IP-Adressen zu den API-Client-Einstellungen hinzugefügt. Dies ermöglicht Administratoren, festzulegen, welche IP-Adressen über den ausgewählten API-Client Anfragen senden dürfen. Standardmäßig sind alle IP-Adressen zulässig. Sie können jedoch den Zugriff einschränken, indem Sie die zulässigen IPs in diesem neuen Feld angeben.

Wo Sie die Einstellung finden

Um diese Funktion zu verwenden, stellen Sie sicher, dass die externe API aktiviert ist und mindestens ein API-Client erstellt wurde. Anweisungen zur Einrichtung finden Sie in den folgenden Anleitungen:

Sobald diese vorhanden sind:

Gehen Sie zum Schnellzugriffsmenü > Entwicklung > API > API-Clients > Client-Einstellungen bearbeiten
Suchen Sie das neue Feld Zulässige IP-Adressen.
Lassen Sie das Feld leer, um Anfragen von einer beliebigen IP-Adresse zuzulassen (Standardverhalten).
Um den Zugriff einzuschränken, geben Sie eine oder mehrere zulässige IP-Adressen in einer separaten Zeile ein.

Wenn eine eingehende Anfrage über diesen API-Client gestellt wird:

Wenn die Anfrage von einer zulässigen IP-Adresse stammt, wird der API-Aufruf wie gewohnt fortgesetzt.
Wenn die IP-Adresse nicht auf der Whitelist steht, wird die Anfrage gesperrt. Die Art der Fehlerantwort hängt von der Einstellung „Fehlerantwort“ ab:
- Normal: Gibt eine 403-Verboten-Antwort zurück.
- Keine: Gibt eine 404 Not Found-Antwort zurück.
- Entwickler: Gibt Debugging-Informationen auf Entwicklerebene zurück, die erklären, warum die Anfrage blockiert wurde.

Das neue Feld Zulässige IP-Adressen unterstützt:

Vollständige IP-Adresse: 192.168.0.1
Teilweise IP-Adresse: 192.168 (entspricht jeder Adresse, die mit diesem Wert beginnt)
IP-Bereich: 192.168.0.10-20 (entspricht allen Adressen von .10 bis .20)
CIDR-Notation: 231.54.211.0/20

Join the Totara Community for more resources to help you get the most out of Totara.