API-Übersicht - Devin Docs

Diese Dokumentation gilt für die Federal-Bereitstellungen von Devin. Zurück zur Devin-Dokumentation

Enterprise-Administratoren im Federal-Bereich können den ACU-Verbrauch programmgesteuert abfragen und Gruppen, Modellverfügbarkeit sowie ACU-Limits über eine Service-Schlüssel-API verwalten. Ein Python SDK kapselt jeden in diesem Abschnitt beschriebenen Endpunkt. Die Endpunkte für Gruppenverwaltung und ACU-Obergrenzen sind nur in self-hosted Federal-Bereitstellungen mit mehreren Mandanten verfügbar. Sie sind in kommerziellen Bereitstellungen nicht verfügbar. Die Analyseendpunkte (/Analytics, /UserPageAnalytics und /CascadeAnalytics) prüfen außerdem die Analytics-Zugriffsebene der Bereitstellung; ein Team ohne Analytics-Zugriff erhält permission_denied.

Base URL

Alle Anfragen werden als JSON-POST-Anfragen an den API-Server Ihres Deployments gesendet:

https://<your-server>/api/v1/<Method>

Ersetzen Sie <your-server> durch die API-Domain Ihrer Federal-Bereitstellung.

Authentifizierung

Jede Anfrage wird mit einem Service-Schlüssel authentifiziert, der im Request-Body enthalten ist:

{
  "service_key": "your_service_key_here"
}

Um einen Service-Schlüssel zu erstellen, melden Sie sich als Teamadministrator beim Federal Portal an und navigieren Sie zu Settings → Service-Schlüssel. Erstellen Sie dann einen Schlüssel mit den Berechtigungen für die Endpunkte, die Sie aufrufen möchten.

Bewahren Sie Service-Schlüssel sicher auf. Verwenden Sie sie niemals in clientseitigem Code und committen Sie sie nicht in Repositorys.

Erforderliche Berechtigungen

Endpunkt	Erforderliche Berechtigung
Legacy-Nutzungsbericht (`/UserPageAnalytics` and `/CascadeAnalytics`)	Teams Read-Only
ACU-Verbrauch (`/Analytics`)	Analytics Read
Gruppen auflisten (`/ListGroups`)	Teams Read-Only
Gruppe abrufen (`/GetGroup`)	Teams Read-Only
Gruppe erstellen (`/CreateGroup`)	Teams Update
Gruppe aktualisieren (`/UpdateGroup`)	Teams Update
Gruppe löschen (`/DeleteGroup`)	Teams Update
Gruppenmitglieder auflisten (`/ListGroupMembers`)	Teams Read-Only
Gruppenmitglieder hinzufügen (`/AddGroupMembers`)	Teams Update
Gruppenmitglieder entfernen (`/RemoveGroupMembers`)	Teams Update
ACU-Obergrenze eines Nutzers abrufen (`/GetUserAcuCap`)	Teams Read-Only
ACU-Obergrenze eines Nutzers aktualisieren (`/UpdateUserAcuCap`)	Teams Update

Schlüssel mit Team- oder Gruppenbereich

Service-Schlüssel erhalten bei ihrer Erstellung einen Geltungsbereich:

Schlüssel mit Teambereich können teamweite Daten abfragen und alle Gruppen im Team verwalten.
Schlüssel mit Gruppenbereich sind auf die ihnen zugewiesene Gruppe beschränkt. Sie können die aggregierte ACU-Gesamtsumme und Nutzerzeilen der Gruppe lesen, nur diese Gruppe auflisten und lesen sowie ACU-Obergrenzen nur für aktuelle Mitglieder dieser Gruppe lesen oder aktualisieren. Sie können keine teamweiten Gesamtsummen oder Nutzerzeilen lesen, keine anderen Gruppen einsehen und keine Gruppen erstellen.

Paginierung

Gruppen, Gruppenmitglieder und ACU-Zeilen pro Nutzer werden seitenweise aufgelistet:

page_size — optional; standardmäßig 100, maximal 1.000. Wenn dieser Wert weggelassen oder 0 übergeben wird, wird der Standardwert verwendet.
next_page_token — wird zurückgegeben, wenn weitere Ergebnisse verfügbar sind. Übergeben Sie ihn als page_token in einer ansonsten identischen Anfrage (einschließlich desselben page_size), um die nächste Seite abzurufen.

Seitentokens sind nicht lesbar und verschlüsselt. Sie laufen nach 24 Stunden ab. Tokens für den ACU-Verbrauch sind an Endpunkt, Team, Geltungsbereich, Zeitraum, Gruppenauswahl und Seitengröße gebunden. Tokens für Gruppen- und Mitgliederlisten sind an Endpunkt, Team, Geltungsbereich und Seitengröße gebunden. Wenn ein gebundener Wert zwischen Seiten geändert wird, wird der Fehler invalid_argument zurückgegeben.

Fehler

Fehler werden als JSON mit einem Code und einer Nachricht zurückgegeben:

{
  "code": "permission_denied",
  "message": "service key role is missing the required permission"
}

Code	Bedeutung
`unauthenticated`	Der Service-Schlüssel fehlt, ist ungültig oder abgelaufen.
`permission_denied`	Der Rolle des Service-Schlüssels fehlt die erforderliche Berechtigung.
`invalid_argument`	Die Anfrage ist fehlerhaft – zum Beispiel aufgrund eines ungültigen Zeitraums, einer Custom-Analytics-Abfrage mit gemischten typisierten und benutzerdefinierten Analysen, eines leeren Updates oder eines veralteten bzw. nicht übereinstimmenden Seitentokens.
`not_found`	Die Ressource existiert nicht, gehört zu einem anderen Team oder liegt außerhalb des Geltungsbereichs des Service-Schlüssels. Teamübergreifende Ressourcen und Ressourcen außerhalb des Geltungsbereichs sind nicht von fehlenden Ressourcen zu unterscheiden.
`failed_precondition`	Die Anfrage ist gültig, kann jedoch im aktuellen Zustand nicht abgeschlossen werden, etwa beim Festlegen einer ACU-Obergrenze für ein Team ohne ACU-Abrechnung oder beim Auswählen einer mehrdeutigen Nutzer-E-Mail-Adresse.
`already_exists`	Der angeforderte Gruppenname wird bereits vom Team verwendet.
`internal`	Der Dienst konnte die Anfrage nicht abschließen.

​Base URL

​Authentifizierung

​Erforderliche Berechtigungen

​Schlüssel mit Team- oder Gruppenbereich

​Paginierung

​Fehler

Base URL

Authentifizierung

Erforderliche Berechtigungen

Schlüssel mit Team- oder Gruppenbereich

Paginierung

Fehler