Azure DevOps API a saját mesterséges intelligenciáidhoz

Az MI-asszisztensed tud kódot olvasni, de nem látja, mi lapul az Azure DevOps-tárhelyeidben. Ez az API hidat képez: projektek, fájlok, commitok, pull requestek, mindez egyszerű JSON-ban, a saját hozzáférési jogaiddal.

Legyünk rögtön az elején világosak: ezt először gépeknek terveztem. Egy MI-ügynöknek, egy MCP-szervernek (ez a protokoll teszi lehetővé, hogy egy olyan asszisztens, mint a Claude, külső eszközöket hívjon meg) vagy egy egyszerű scriptnek. Az emberek is szívesen látott vendégek, de az ötlet az, hogy egy MI megkérhesse, hogy „mutasd meg ezt a fájlt” vagy „mi változott ebben a commitban”, anélkül, hogy ki kellene találnia, hogyan működik az Azure DevOps API-ja, amely erős, de őszintén szólva meglehetősen sűrű.

Íme a szolgáltatás Swagger-oldala, ahol minden hívás fel van sorolva:

Ingyenes vagy PRO: ezt kapod

A két csomag ugyanazokhoz a hívásokhoz biztosít hozzáférést, az írás is benne van. Az egyetlen különbség a naponta küldhető kérések száma. A zöld sáv mutatja, mennyit kérhetsz egy nap alatt.

A számláló UTC szerint éjfélkor indul újra, vagyis Franciaországban évszaktól függően hajnali 1-kor vagy 2-kor. Tíz kérés gyorsan elfogy egy sokat beszélő ügynökkel. A tanácsom, hogy tovább tartsanak: a files:batch hívás akár 50 fájlt is visszahoz, és csak egyetlen kérésnek számít.

Mire képes az API

Körülbelül húsz hívás, mindegyik a https://devops.digital3d.com/api/Devops/ alatt. Szükség szerint rendeztem el őket, nem ábécésorrendben:

Két szolgáltatáshívás is van: a Health, amely kulcs nélkül válaszol, és soha nem számít bele, valamint a WhoAmI, amely megerősíti, hogy a fejléceidet megfelelően értelmezi.

A három elküldendő fejléc

Minden kérés három fejlécet tartalmaz. Egyet nekem, kettőt az Azure DevOpsnak.

A Digital3D-kulcs. Hozz létre egy fiókot, erősítsd meg az e-mail-címedet, majd másold ki a fiókodban megjelenő kulcsot. Ez ugyanaz a kulcs, mint a többi szolgáltatásomhoz. Ha a régi verziót használtad, figyelj: az X-Api-Key fejléc helyét az Authorization vette át.

A szervezet neve. Jelentkezz be a https://dev.azure.com oldalon, és nézd meg a címet. A https://dev.azure.com/ma-societe/ címben az elküldendő érték a ma-societe. Ez a szervezet neve, nem egy projekté.

A személyes hozzáférési token (a PAT, egyfajta korlátozott jogosultságú jelszó). Az Azure DevOpsban kattints jobb felül a felhasználói beállítások ikonjára, majd a „Personal access tokens” és a „New Token” elemre. Adj neki egy beszédes nevet, rövid érvényességi időt (30 vagy 90 nap), és csak a szükséges jogosultságokat: a „Code (Read)” és a „Project and Team (Read)” elegendő ahhoz, hogy mindent olvass. A „Code (Read & Write)” jogosultságot csak akkor add hozzá, ha az agentednek írnia is kell. Azonnal másold ki a tokent, az Azure DevOps csak egyszer jeleníti meg.

Egy kis óvatosság, mert ez a te kódod: ez a token hozzáférést ad a tárházadhoz, és minden kérésnél áthalad a szerveremen. A lehető legkevesebb jogosultságot add neki, állíts be lejárati dátumot, és vond vissza azon a napon, amikor már nincs rá szükséged. Én is ezt tenném a helyedben.

Első hívások

Kezdd azzal, hogy ellenőrzöd, átmegy-e a három fejléc:

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

Ezután jöhet a tárolók listája. Minden tárolónak van egy azonosítója (egy GUID), és ezt várja az összes többi hívás a {repoId} helyett:

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"

Egy tároló összes C#-fájljának kereséséhez, az alapértelmezett ágán:

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"

Ha pedig több fájlt szeretnél egyetlen kéréssel beolvasni, az egy POST a fájlútvonalak listájával:

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

Amikor egy ágat vár a rendszer (refName), beírhatod a main értéket vagy a teljes formát, a refs/heads/main értéket. Ha nem adsz meg semmit, a tároló alapértelmezett ágát veszi.

Összehasonlítás és írás

Na, itt lesz igazán érdekes egy ügynök számára. Ha tudni szeretnéd, mi választ el két commitot:

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

Ha a summaryOnly értéke true (ez az alapértelmezett érték), a válasz egy tömör összefoglaló: a módosított fájlok számai és útvonalai. Ez szándékos. Egy MI minden elolvasott szóért fizet, úgyhogy felesleges Azure DevOps nyers válaszát elé tenni, amikor elég egy összefoglaló.

És egy fájl írásához:

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

Na jó, legyünk két percig komolyak: ha egy mesterséges intelligenciának engeded, hogy írjon egy repóba, ahhoz védőkorlátok kellenek. Három beállítás létezik erre. A createBranch létrehozza az ágat, ha még nem létezik, így az agent elkülönítve dolgozhat, te pedig átnézheted a munkáját egy pull requestben. Az expectHeadCommit közli az utolsó commitot, amelyet az agent látott: ha közben valaki pusholt, az írás elutasításra kerül ahelyett, hogy felülírná a munkáját. Az írt fájl mérete szerveroldalon korlátozva van. És ha egyáltalán nem akarsz írást, továbbra is a csak olvasásra jogosító token a legbiztosabb: az Azure DevOps magától elutasítja.

A motorháztető alatt

Néhány technikai döntés, amelyek megmagyarázzák az API működését.

Minden kérésnél te mondod meg, melyik szervezetet kell lekérdezni, és melyik tokennel. Ugyanaz az API tehát bármelyik Azure DevOps-szervezethez használható, és nem lát többet annál, mint amire a tokened engedélyt ad.

A Digital3D-kulcsot ellenőrizzük először. Egy kérés attól a pillanattól számít bele, hogy a kulcsot elfogadtuk, függetlenül attól, mit válaszol utána az Azure DevOps. Egy rossz szervezetnév vagy egy lejárt token tehát egy kérésbe kerül: ezért érdemes egyszer és mindenkorra ellenőrizni a beállításaidat a WhoAmI segítségével, ahelyett, hogy vaktában próbálkoznál.

Két 401-es hiba hasonlít egymásra, és nem ugyanaz az oka. Az, amelyik a WWW-Authenticate: Bearer fejlécet tartalmazza, tőlem jön: a Digital3D-kulcs hiányzik vagy elutasításra került, és semmi sem számít bele. Amelyik nem tartalmazza, az Azure DevOps-tól jön: nézz körül az X-Ado-Org és az X-Ado-Pat környékén.

A válaszok korlátozva vannak, hogy könnyen emészthetők maradjanak: csoportos olvasásonként 50 fájl és körülbelül 2 MB, fájllistánként alapértelmezés szerint 2000 bejegyzés, naplónként alapértelmezés szerint 50 commit. Ezek a korlátok a top és maxItems paraméterekkel állíthatók.

A kvótád követése

Amint a kulcsot elfogadtuk, minden válasz három fejlécet tartalmaz: X-RateLimit-Limit (a napi limitet), X-RateLimit-Remaining (ami még hátravan) és X-RateLimit-Reset (a nullázás időpontját Unix-másodpercben). Egy jól nevelt ügynök elolvassa az X-RateLimit-Remaining értékét, és visszavesz, mielőtt falnak megy.

• 429 : a napi kvóta elfogyott. A Retry-After fejléc megadja, hány másodpercet kell várni a nullázásig.
• 503 : a szolgáltatás nem tudta ellenőrizni a kulcsot. 30 másodperccel később újra meg lehet próbálni.
• A többi hiba egy JSON-objektum, benne egy error mezővel, amely megmondja, mi a baj.

Tesztelés egyetlen sor kód írása nélkül

Mindent dokumentáltunk az API Swaggerében. Kattints az „Authorize” gombra, töltsd ki a három mezőt (a kulcsot, a szervezetet, a tokent), aztán próbáld ki az egyes hívásokat a „Try it out” gombbal. Azért figyelj : ezek a próbák beleszámítanak a kvótádba, mint bármelyik kérés. Ugyanez a Swagger szerződésként szolgál egy MI számára : add meg neki a https://devops.digital3d.com/swagger/v1/swagger.json fájl címét, és magától felfedezi a hívásokat.

Miért kell előfizetés?

Mert ez az egész egy olyan szerveren fut, amit én fizetek. Az ingyenes csomag megmarad tesztelésre és könnyű használatra. Ha egy ügynök minden nap a tárolóidon dolgozik, a havi 12 €-s PRO-előfizetés 1000 kérésre emeli a napi limitet, tartalmazza a teljes TV-útmutatót és az összes szoftveremet, és ez tartja életben a szolgáltatást. Előfizetés nélkül kereskedelmi használat nem engedélyezett. Ha pedig többre van szükséged, írj nekem.