Azure DevOps API für Ihre künstlichen Intelligenzen

Dein KI-Assistent kann Code lesen, aber er sieht nicht, was in deinen Azure-DevOps-Repositories schlummert. Diese API schlägt die Brücke: Projekte, Dateien, Commits, Pull Requests, alles als einfaches JSON, mit deinen eigenen Zugriffsrechten.

Seien wir gleich von Anfang an klar: Ich habe sie zuerst für Maschinen entwickelt. Einen KI-Agenten, einen MCP-Server, das Protokoll, mit dem ein Assistent wie Claude externe Tools aufrufen kann, oder ein einfaches Skript. Menschen sind willkommen, aber die Idee ist, dass eine KI fragen kann „Zeig mir diese Datei“ oder „Was hat sich in diesem Commit geändert“, ohne erraten zu müssen, wie die API von Azure DevOps funktioniert, die zwar leistungsstark, aber ehrlich gesagt ziemlich unübersichtlich ist.

Hier ist die Swagger-Seite des Dienstes, auf der alle Aufrufe aufgelistet sind:

Kostenlos oder PRO: Das bekommst du

Beide Tarife geben Zugriff auf dieselben Aufrufe, einschließlich Schreibzugriff. Der einzige Unterschied ist die Anzahl der Anfragen pro Tag. Der grüne Balken zeigt, was du an einem Tag anfragen kannst.

Der Zähler wird um Mitternacht UTC zurückgesetzt, also in Frankreich je nach Jahreszeit um 1 Uhr oder 2 Uhr morgens. Zehn Anfragen sind mit einem redseligen Agenten schnell weg. Mein Tipp, damit sie länger reichen: Der Aufruf files:batch liefert bis zu 50 Dateien zurück und zählt nur als eine einzige Anfrage.

Was die API kann

Ungefähr zwanzig Aufrufe, alle unter https://devops.digital3d.com/api/Devops/. Ich habe sie nach Bedarf statt alphabetisch geordnet:

Es gibt außerdem zwei Serviceaufrufe: Health, der ohne Schlüssel antwortet und nie gezählt wird, und WhoAmI, der bestätigt, dass deine Header richtig verstanden werden.

Die drei zu sendenden Header

Jede Anfrage enthält drei Header. Einen für mich, zwei für Azure DevOps.

Der Digital3D-Schlüssel. Erstelle ein Konto, bestätige deine E-Mail-Adresse und kopiere dann den in deinem Konto angezeigten Schlüssel. Es ist derselbe Schlüssel wie für meine anderen Dienste. Falls du die alte Version verwendet hast, aufgepasst: Der Header X-Api-Key wurde durch Authorization ersetzt.

Der Name der Organisation. Melde dich bei https://dev.azure.com an und sieh dir die Adresse an. In https://dev.azure.com/ma-societe/ ist der zu sendende Wert ma-societe. Das ist der Name der Organisation, nicht der eines Projekts.

Der persönliche Zugriffstoken (der PAT, eine Art Passwort mit eingeschränkten Rechten). Klicke in Azure DevOps oben rechts auf das Symbol für die Benutzereinstellungen, dann auf „Personal access tokens“ und „New Token“. Gib ihm einen aussagekräftigen Namen, eine kurze Laufzeit (30 oder 90 Tage) und nur die nötigen Rechte: „Code (Read)“ und „Project and Team (Read)“ reichen aus, um alles zu lesen. Füge „Code (Read & Write)“ nur hinzu, wenn dein Agent schreiben muss. Kopiere den Token sofort, Azure DevOps zeigt ihn nur einmal an.

Eine Warnung, weil es dein Code ist: Dieser Token gibt Zugriff auf deine Repositories und läuft bei jeder Anfrage über meinen Server. Gib ihm so wenige Rechte wie möglich, ein Ablaufdatum, und widerrufe ihn an dem Tag, an dem du ihn nicht mehr brauchst. So würde ich es an deiner Stelle machen.

Erste Aufrufe

Beginne damit zu prüfen, dass die drei Header durchgehen:

curl "https://devops.digital3d.com/api/Devops/WhoAmI" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure"

Danach die Liste der Repositories. Jedes Repository hat eine ID (eine GUID), und genau diese erwarten alle anderen Aufrufe anstelle von {repoId}:

curl "https://devops.digital3d.com/api/Devops/Repos?project=MonProjet" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure"

Um alle C#-Dateien eines Repositories auf seinem Standardbranch zu suchen:

curl "https://devops.digital3d.com/api/Devops/Repos/{repoId}/search?glob=**/*.cs" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure"

Und um mehrere Dateien in einer einzigen Anfrage zu lesen, ist es ein POST mit der Liste der Pfade:

curl -X POST "https://devops.digital3d.com/api/Devops/Repos/{repoId}/files:batch" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure" \
  -H "Content-Type: application/json" \
  -d '{ "paths": ["/README.md", "/src/Program.cs"], "refName": "main" }'

Überall dort, wo ein Branch erwartet wird (refName), kannst du main oder die vollständige Form refs/heads/main schreiben. Wenn du nichts angibst, wird der Standardbranch des Repositories verwendet.

Vergleichen und schreiben

Da wird es für einen Agenten wirklich interessant. Um herauszufinden, was zwei Commits voneinander trennt:

curl -X POST "https://devops.digital3d.com/api/Devops/Repos/{repoId}/diffs/commits" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure" \
  -H "Content-Type: application/json" \
  -d '{ "baseCommit": "abc123", "targetCommit": "def456", "summaryOnly": true }'

Mit summaryOnly auf true (der Standardwert) ist die Antwort eine kompakte Zusammenfassung: die Summen und die Pfade der geänderten Dateien. Das ist Absicht. Eine KI bezahlt für jedes Wort, das sie liest, also sollte man ihr nicht die rohe Antwort von Azure DevOps vorsetzen, wenn eine Zusammenfassung ausreicht.

Und um eine Datei zu schreiben:

curl -X POST "https://devops.digital3d.com/api/Devops/Repos/{repoId}/write" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/docs/notes.md",
    "content": "# Notes\n\nEcrit par mon agent.",
    "branch": "feature/notes",
    "createBranch": true,
    "commitMessage": "Ajout des notes"
  }'

Gut, seien wir zwei Minuten lang ernst: Eine KI in ein Repository schreiben zu lassen, macht man mit Leitplanken. Dafür gibt es drei Einstellungen. createBranch erstellt den Branch, wenn er nicht existiert, sodass der Agent abseits arbeiten und du seine Arbeit in einem Pull Request prüfen kannst. expectHeadCommit kündigt den letzten Commit an, den der Agent gesehen hat: Wenn zwischenzeitlich jemand etwas gepusht hat, wird das Schreiben abgelehnt, statt seine Arbeit zu überschreiben. Und die Größe der geschriebenen Datei ist serverseitig begrenzt. Und wenn du überhaupt kein Schreiben erlauben willst, ist ein Token mit Leserechten die sicherste Lösung: Azure DevOps wird es von selbst ablehnen.

Unter der Haube

Ein paar technische Entscheidungen, die das Verhalten der API erklären.

Du legst bei jeder Anfrage fest, welche Organisation abgefragt werden soll und mit welchem Token. Dieselbe API funktioniert also mit jeder beliebigen Azure-DevOps-Organisation, und sie sieht nicht mehr als das, was dein Token erlaubt.

Der Digital3D-Schlüssel wird zuerst überprüft. Eine Anfrage wird gezählt, sobald der Schlüssel akzeptiert wurde, unabhängig davon, was Azure DevOps danach antwortet. Ein falscher Organisationsname oder ein abgelaufenes Token kostet also eine Anfrage: Daher lohnt es sich, deine Konfiguration einmal mit WhoAmI zu validieren, statt herumzuprobieren.

Zwei 401-Fehler sehen sich ähnlich und haben nicht dieselbe Ursache. Der mit dem Header WWW-Authenticate: Bearer kommt von mir: Der Digital3D-Schlüssel fehlt oder wurde abgelehnt, und es wird nichts gezählt. Der ohne diesen Header kommt von Azure DevOps: Sieh bei X-Ado-Org und X-Ado-Pat nach.

Die Antworten sind begrenzt, damit sie verdaulich bleiben: 50 Dateien und etwa 2 MB pro gruppiertem Lesevorgang, standardmäßig 2000 Einträge für eine Dateiliste, standardmäßig 50 Commits für ein Protokoll. Diese Obergrenzen lassen sich mit den Parametern top und maxItems einstellen.

Dein Kontingent verfolgen

Sobald der Schlüssel akzeptiert wurde, trägt jede Antwort drei Header: X-RateLimit-Limit (dein Tageslimit), X-RateLimit-Remaining (was dir noch bleibt) und X-RateLimit-Reset (die Uhrzeit der Rücksetzung, in Unix-Sekunden). Ein wohlerzogener Agent liest X-RateLimit-Remaining und nimmt den Fuß vom Gas, bevor er gegen die Wand kracht.

• 429 : Das Tageskontingent ist aufgebraucht. Der Header Retry-After gibt die Anzahl der Sekunden an, die du bis zur Rücksetzung warten musst.
• 503 : Der Dienst konnte den Schlüssel nicht überprüfen. Das lässt sich 30 Sekunden später erneut versuchen.
• Die anderen Fehler sind ein JSON-Objekt mit einem Feld error, das sagt, was nicht stimmt.

Testen, ohne eine Zeile Code zu schreiben

Alles ist im Swagger der API dokumentiert. Klick auf „Authorize“, füll die drei Felder aus (den Schlüssel, die Organisation, das Token) und probier jeden Aufruf mit der Schaltfläche „Try it out“ aus. Trotzdem Achtung: Diese Tests zählen zu deinem Kontingent wie jede andere Anfrage. Dieses Swagger dient auch einer KI als Vertrag: Gib ihr die Adresse der Datei https://devops.digital3d.com/swagger/v1/swagger.json und sie entdeckt die Aufrufe ganz allein.

Warum ein Abonnement?

Weil das alles auf einem Server läuft, den ich bezahle. Die kostenlose Version bleibt zum Testen und für eine leichte Nutzung bestehen. Wenn ein Agent jeden Tag auf deinen Repositories arbeitet, erhöht das PRO-Abonnement für 12 € im Monat das Limit auf 1000 Anfragen pro Tag, umfasst den vollständigen TV-Leitfaden und all meine Software, und das hält den Dienst am Leben. Die kommerzielle Nutzung ohne Abonnement ist nicht erlaubt. Und wenn du mehr brauchst, schreib mir.