Administration

API-Zugänge und API-Dokumentation

Schlüsselpaare für Fremdsysteme erzeugen und die Schnittstellen der eigenen Installation nachschlagen.

EasyUC · Version 4.8.7

In EasyUC: EasyUC Cisco → Verwaltung → Integrationen & Kommunikation → API-Zugänge / API-Dokumentation

Wozu dient das

Ein API-Zugang ist ein Schlüsselpaar aus API-Schlüssel und API-Secret, mit dem sich ein Fremdsystem an der EasyUC-Schnittstelle anmeldet, zum Beispiel ein Ticketsystem oder ein Identity-Management, das Benutzer und Telefone automatisch anlegen lässt.

Die Seite API-Dokumentation zeigt die Schnittstellen genau dieser Installation in einer Swagger-Oberfläche: Endpunkte, Parameter, Antworten. Sie ist in die Bereiche default, devices, users, groups, reporting, curri, templates, voicemails und globals gegliedert.

Voraussetzungen

Ein Konto mit dem Zugriffstyp Administrator (Vollzugriff) (ROLE_APP_ADMIN) oder das Eigentümerkonto (ROLE_OWNER). Nur diese Konten sehen das Menü Verwaltung.
Ein sicherer Ablageort für das Secret, zum Beispiel ein Kennworttresor.
Der Zweck jedes Zugangs steht fest. Legen Sie je Fremdsystem einen eigenen Zugang an, damit Sie ihn einzeln zurückziehen können.

Schritt für Schritt: API-Zugang erzeugen

Öffnen Sie den Arbeitsbereich EasyUC Cisco.
Wählen Sie Verwaltung → Integrationen & Kommunikation → API-Zugänge. Die Seite heißt API-Benutzer verwalten.
Klicken Sie oben rechts auf Erstellen. EasyUC legt den Zugang sofort an, ohne weiteres Formular.
Es erscheint ein Hinweisfenster mit Api key und Api secret. Kopieren Sie beide Werte in Ihren Kennworttresor.
Schließen Sie das Fenster mit Ok. Die Liste zeigt danach nur noch den API-Schlüssel.
Tragen Sie Schlüssel und Secret im Fremdsystem ein.

Schritt für Schritt: Schnittstelle nachschlagen

Wählen Sie Verwaltung → Integrationen & Kommunikation → API-Dokumentation.
Wählen Sie oben in der Auswahlliste der Definitionen den Bereich, zum Beispiel users oder devices.
Klappen Sie den gewünschten Endpunkt auf und lesen Sie Parameter, Beispielkörper und Antwortcodes.
Achten Sie auf den Parameter für die CUCM-Verbindung. Viele Aufrufe beziehen sich auf genau einen Cluster.

Schritt für Schritt: API-Zugang zurückziehen

Klären Sie, welches Fremdsystem den Schlüssel verwendet.
Klicken Sie in der Zeile des Schlüssels auf Löschen.
Bestätigen Sie die Rückfrage Sind Sie sicher?. Der Zugang ist sofort ungültig.

Felder und Optionen

Felder und Optionen
Feld / Aktion	Bedeutung und Verwendung
API-Schlüssel	Öffentlicher Teil des Zugangs. Steht dauerhaft in der Liste.
Api secret	Geheimer Teil. Wird nur im Hinweisfenster nach dem Erzeugen angezeigt.
Erstellen	Erzeugt ein neues Schlüsselpaar. Es gibt keine weiteren Eingaben und keine Einschränkung auf einzelne Rechte.
Löschen	Entfernt den Zugang. Ein gelöschter Schlüssel lässt sich nicht wiederherstellen.
Definitionen der API-Dokumentation	default, devices, users, groups, reporting, curri, templates, voicemails, globals.

Ergebnis prüfen und Fehler eingrenzen

Erfolg: Das Fremdsystem meldet sich mit Schlüssel und Secret an und erhält Antworten auf seine Aufrufe.
Das Secret ist verloren: Löschen Sie den Zugang und erzeugen Sie einen neuen. Ein Secret lässt sich nicht erneut anzeigen.
Die Anmeldung wird nach mehreren Fehlversuchen vorübergehend abgewiesen: EasyUC bremst wiederholte Fehlanmeldungen. Korrigieren Sie die Zugangsdaten und warten Sie einige Minuten.
Die API-Dokumentation bleibt leer: Sie ist nur für angemeldete Benutzer abrufbar. Melden Sie sich neu an und laden Sie die Seite.
Verwenden Sie Endpunkte und Feldnamen aus der Dokumentation der eigenen Installation, nicht aus der einer anderen Version.
Das Änderungsprotokoll kennt den Akteurstyp API-Benutzer. Dort lässt sich nachvollziehen, was über einen API-Zugang geändert wurde.