API Azure DevOps pro vaše umělé inteligence

Váš AI asistent umí číst kód, ale nevidí, co spí ve vašich repozitářích Azure DevOps. Toto API to propojuje: projekty, soubory, commity, pull requesty, to vše v jednoduchém JSONu, s vašimi vlastními přístupovými právy.

Řekněme si to hned na rovinu: navrhl jsem ho nejdřív pro stroje. AI agenta, MCP server (protokol, který asistentovi jako Claude umožňuje volat externí nástroje) nebo obyčejný skript. Lidé jsou vítáni, ale myšlenka je taková, že se AI může zeptat „ukaž mi tento soubor“ nebo „co se změnilo v tomto commitu“, aniž by musela hádat, jak funguje API služby Azure DevOps, které je výkonné, ale upřímně řečeno pěkně nepřehledné.

Tady je stránka Swaggeru této služby, kde jsou uvedená všechna volání:

Zdarma nebo PRO: co máte k dispozici

Obě varianty poskytují přístup ke stejným voláním, včetně zápisu. Jediný rozdíl je v počtu požadavků za den. Zelený pruh ukazuje, co můžete za jeden den požadovat.

Počítadlo se resetuje o půlnoci UTC, tedy ve 1 nebo 2 ráno ve Francii podle ročního období. Deset požadavků s upovídaným agentem zmizí rychle. Moje rada, jak je nechat vydržet: volání files:batch vrátí až 50 souborů a započítá se jen jako jediný požadavek.

Co API umí

Přibližně dvacet volání, všechna pod https://devops.digital3d.com/api/Devops/. Seřadil jsem je podle potřeby, ne podle abecedy:

Jsou tu také dvě servisní volání: Health, které odpovídá bez klíče a nikdy se nezapočítává, a WhoAmI, které potvrzuje, že jsou tvoje hlavičky správně pochopené.

Tři hlavičky, které je třeba posílat

Každý požadavek nese tři hlavičky. Jednu pro mě, dvě pro Azure DevOps.

Klíč Digital3D. Vytvoř si účet, potvrď svou e-mailovou adresu a pak zkopíruj klíč zobrazený v tvém účtu. Je to stejný klíč jako pro moje ostatní služby. Pokud jsi používal starou verzi, pozor: hlavička X-Api-Key ustoupila hlavičce Authorization.

Název organizace. Přihlas se na https://dev.azure.com a podívej se na adresu. V https://dev.azure.com/ma-societe/ je hodnota, kterou máš poslat, ma-societe. Je to název organizace, ne název projektu.

Osobní přístupový token (PAT, takové heslo s omezenými oprávněními). V Azure DevOps klikni vpravo nahoře na ikonu uživatelského nastavení, potom na „Personal access tokens“ a „New Token“. Dej mu výstižný název, krátkou dobu platnosti (30 nebo 90 dní) a jen potřebná oprávnění: „Code (Read)“ a „Project and Team (Read)“ stačí k přečtení všeho. „Code (Read & Write)“ přidej jen v případě, že tvůj agent musí zapisovat. Token hned zkopíruj, Azure DevOps ho zobrazí jen jednou.

Jedno varování, protože jde o tvůj kód: tento token poskytuje přístup k tvým repozitářům a při každém požadavku prochází mým serverem. Dej mu minimum oprávnění, datum vypršení a odvolej ho v den, kdy ho už nebudeš potřebovat. Na tvém místě bych to udělal stejně.

První volání

Začni ověřením, že projdou všechny tři hlavičky:

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

Pak seznam repozitářů. Každý repozitář má identifikátor (GUID) a právě ten očekávají všechna ostatní volání místo {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"

Pro hledání všech souborů C# v repozitáři na jeho výchozí větvi:

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"

A pro načtení několika souborů v jediném požadavku použij POST se seznamem cest:

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

Všude, kde se očekává větev (refName), můžeš napsat main nebo úplný tvar refs/heads/main. Když neuvedeš nic, použije se výchozí větev repozitáře.

Porovnávat a zapisovat

Tady to pro agenta začíná být opravdu zajímavé. Chceš-li zjistit, co se liší mezi dvěma commity:

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

S summaryOnly nastaveným na true (výchozí hodnota) je odpovědí kompaktní shrnutí: souhrny a cesty změněných souborů. Je to záměr. Umělá inteligence platí za každé slovo, které přečte, takže jí nemusíme servírovat surovou odpověď Azure DevOps, když stačí shrnutí.

A pro zápis souboru:

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

Dobře, buďme na dvě minuty vážní: nechat AI zapisovat do repozitáře se dělá s bezpečnostními pojistkami. Existují pro to tři nastavení. createBranch vytvoří větev, pokud neexistuje, takže agent může pracovat stranou a ty si jeho práci přečteš v pull requestu. expectHeadCommit oznámí poslední commit, který agent viděl: pokud mezitím někdo něco pushnul, zápis se odmítne, místo aby přepsal jeho práci. A velikost zapisovaného souboru je na straně serveru omezená. A pokud nechceš zapisovat vůbec, nejbezpečnější je pořád token pouze pro čtení: Azure DevOps ho odmítne samo.

Pod pokličkou

Několik technických voleb, které vysvětlují chování API.

Jsi to ty, kdo při každém požadavku říká, na jakou organizaci se dotazovat a s jakým tokenem. Stejné API tak slouží libovolné organizaci Azure DevOps a nevidí nic víc, než k čemu tvůj token opravňuje.

Klíč Digital3D se ověřuje jako první. Požadavek se započítá, jakmile je klíč přijat, bez ohledu na to, co následně odpoví Azure DevOps. Špatný název organizace nebo prošlý token tak stojí jeden požadavek: proto je dobré jednou provždy ověřit konfiguraci pomocí WhoAmI, místo abys tápal.

Dvě chyby 401 vypadají podobně a mají jinou příčinu. Ta, která obsahuje hlavičku WWW-Authenticate: Bearer, pochází ode mě: klíč Digital3D chybí nebo byl odmítnut a nic se nezapočítá. Ta, která ho neobsahuje, pochází z Azure DevOps: podívej se na X-Ado-Org a X-Ado-Pat.

Odpovědi jsou omezené, aby zůstaly stravitelné: 50 souborů a přibližně 2 MB při hromadném čtení, ve výchozím nastavení 2000 položek pro seznam souborů, ve výchozím nastavení 50 commitů pro protokol. Tyto limity se nastavují pomocí parametrů top a maxItems.

Sledování kvóty

Jakmile je klíč přijat, každá odpověď obsahuje tři hlavičky: X-RateLimit-Limit (tvůj denní limit), X-RateLimit-Remaining (kolik ti zbývá) a X-RateLimit-Reset (čas vynulování, v unixových sekundách). Slušně vychovaný agent čte X-RateLimit-Remaining a ubere plyn, než narazí do zdi.

• 429 : denní kvóta je vyčerpaná. Hlavička Retry-After udává počet sekund, které je třeba počkat do vynulování.
• 503 : služba nemohla ověřit klíč. Zkus to znovu o 30 sekund později.
• Ostatní chyby jsou objekt JSON s polem error, které říká, co je špatně.

Testování bez napsání jediného řádku kódu

Všechno je zdokumentované ve Swaggeru API. Klikni na „Authorize“, vyplň tři pole (klíč, organizaci, token) a pak vyzkoušej každé volání pomocí tlačítka „Try it out“. Pozor ale: tyto pokusy se započítávají do tvé kvóty stejně jako jakýkoli jiný požadavek. Ten samý Swagger slouží jako smlouva pro AI: dej jí adresu souboru https://devops.digital3d.com/swagger/v1/swagger.json a ona volání objeví sama.

Proč předplatné?

Protože tohle všechno běží na serveru, který platím. Bezplatná verze tu zůstává pro testování a lehké používání. Pokud agent každý den pracuje s tvými repozitáři, předplatné PRO za 12 € měsíčně zvyšuje limit na 1000 požadavků denně, zahrnuje kompletní TV průvodce a veškerý můj software a právě to udržuje službu při životě. Komerční používání bez předplatného není povoleno. A pokud potřebuješ víc, napiš mi.