API Azure DevOps untuk kecerdasan buatan Anda

Asisten AI Anda bisa membaca kode, tetapi tidak bisa melihat apa yang tertidur di repositori Azure DevOps Anda. API ini menjembatani keduanya: proyek, file, commit, pull request, semuanya dalam JSON sederhana, dengan hak akses Anda sendiri.

Mari kita perjelas sejak awal: saya merancangnya terutama untuk mesin. Agen AI, server MCP (protokol yang memungkinkan asisten seperti Claude memanggil alat dari luar) atau skrip sederhana. Manusia juga boleh menggunakannya, tetapi idenya adalah agar AI bisa meminta «tunjukkan file ini» atau «apa yang berubah dalam commit ini» tanpa harus menebak-nebak cara kerja API Azure DevOps, yang memang kuat tetapi terus terang sangat ruwet.

Berikut halaman Swagger layanan ini, tempat semua pemanggilan dicantumkan:

Gratis atau PRO: apa yang Anda dapatkan

Kedua paket memberikan akses ke pemanggilan yang sama, termasuk penulisan. Satu-satunya perbedaan adalah jumlah permintaan per hari. Bilah hijau menunjukkan apa yang bisa Anda minta dalam sehari.

Penghitung dimulai lagi pada tengah malam UTC, jadi pukul 1 atau 2 pagi di Prancis tergantung musim. Sepuluh permintaan bisa cepat habis dengan agen yang banyak bicara. Saran saya agar bisa bertahan lebih lama: pemanggilan files:batch mengembalikan hingga 50 file dan hanya dihitung sebagai satu permintaan.

Yang bisa dilakukan API ini

Sekitar dua puluh pemanggilan, semuanya berada di bawah https://devops.digital3d.com/api/Devops/. Saya mengelompokkannya berdasarkan kebutuhan, bukan berdasarkan urutan alfabet:

Ada juga dua panggilan layanan: Health, yang merespons tanpa kunci dan tidak pernah dihitung, dan WhoAmI, yang mengonfirmasi bahwa header kamu dipahami dengan baik.

Tiga header yang harus dikirim

Setiap permintaan membawa tiga header. Satu untukku, dua untuk Azure DevOps.

Kunci Digital3D. Buat akun, validasi alamat emailmu, lalu salin kunci yang ditampilkan di akunmu. Ini kunci yang sama seperti untuk layanan-layananku yang lain. Jika kamu menggunakan versi lama, perhatikan: header X-Api-Key telah digantikan oleh Authorization.

Nama organisasi. Masuklah ke https://dev.azure.com dan lihat alamatnya. Di https://dev.azure.com/ma-societe/, nilai yang harus dikirim adalah ma-societe. Ini nama organisasinya, bukan nama proyek.

Token akses personal (PAT, semacam kata sandi dengan hak akses terbatas). Di Azure DevOps, klik ikon pengaturan pengguna di kanan atas, lalu “Personal access tokens” dan “New Token”. Beri nama yang jelas, masa berlaku singkat (30 atau 90 hari), dan hanya hak akses yang diperlukan: “Code (Read)” dan “Project and Team (Read)” sudah cukup untuk membaca semuanya. Tambahkan “Code (Read & Write)” hanya jika agenmu harus menulis. Salin tokennya segera, Azure DevOps hanya menampilkannya sekali.

Sedikit peringatan, karena ini kode milikmu: token ini memberi akses ke repositorimu, dan melewati serverku pada setiap permintaan. Beri token ini hak akses seminimal mungkin, tanggal kedaluwarsa, dan cabut pada hari kamu tidak lagi membutuhkannya. Itulah yang akan kulakukan kalau berada di posisimu.

panggilan pertama

Mulailah dengan memeriksa bahwa ketiga header berhasil:

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

Lalu, daftar repositorinya. Setiap repositori memiliki sebuah pengenal (GUID), dan pengenal inilah yang diharapkan semua panggilan lainnya sebagai pengganti {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"

Untuk mencari semua file C# dalam sebuah repositori, pada cabang defaultnya:

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"

Dan untuk membaca beberapa file dalam satu permintaan, ini adalah POST dengan daftar path:

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

Di mana pun sebuah cabang diharapkan (refName), kamu bisa menulis main atau bentuk lengkapnya refs/heads/main. Kalau kamu tidak menulis apa-apa, cabang default repositori yang digunakan.

membandingkan dan menulis

Nah, ini menjadi benar-benar menarik untuk sebuah agen. Untuk mengetahui apa yang memisahkan dua commit:

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

Dengan summaryOnly bernilai true (nilai default), responsnya adalah ringkasan ringkas: total dan path file yang diubah. Ini memang disengaja. AI membayar setiap kata yang dibacanya, jadi sebaiknya jangan menyajikan respons mentah Azure DevOps kepadanya ketika ringkasan sudah cukup.

Dan untuk menulis file:

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

Oke, mari serius dua menit: membiarkan AI menulis ke repositori, itu dilakukan dengan pagar pengaman. Ada tiga pengaturan untuk itu. createBranch membuat branch jika belum ada, sehingga agen bisa bekerja terpisah dan pekerjaannya bisa kamu periksa dalam pull request. expectHeadCommit menyatakan commit terakhir yang dilihat agen: jika seseorang melakukan push sementara itu, penulisan ditolak alih-alih menimpa pekerjaannya. Dan ukuran file yang ditulis dibatasi di sisi server. Dan jika kamu sama sekali tidak ingin ada penulisan, yang paling aman tetap token hanya-baca: Azure DevOps akan menolaknya sendiri.

Di balik layar

Beberapa pilihan teknis yang menjelaskan perilaku API.

Kamulah yang menentukan, pada setiap permintaan, organisasi mana yang ditanyai dan dengan token yang mana. Jadi API yang sama bisa digunakan untuk organisasi Azure DevOps mana pun, dan API ini tidak melihat apa pun selain yang diizinkan oleh tokenmu.

Kunci Digital3D diperiksa terlebih dahulu. Sebuah permintaan dihitung segera setelah kunci diterima, apa pun respons Azure DevOps setelahnya. Nama organisasi yang salah atau token yang kedaluwarsa tetap menghabiskan satu permintaan: itulah sebabnya penting untuk memvalidasi konfigurasimu sekali dengan WhoAmI, daripada mencoba-coba.

Dua error 401 terlihat mirip dan penyebabnya tidak sama. Error yang memuat header WWW-Authenticate: Bearer berasal dariku: kunci Digital3D tidak ada atau ditolak, dan tidak ada yang dihitung. Error yang tidak memuatnya berasal dari Azure DevOps: periksa bagian X-Ado-Org dan X-Ado-Pat.

Respons dibatasi agar tetap mudah dicerna: 50 file dan sekitar 2 MB untuk pembacaan berkelompok, 2000 entri secara default untuk daftar file, 50 commit secara default untuk log. Batas-batas ini diatur dengan parameter top dan maxItems.

Melacak kuotamu

Begitu kunci diterima, setiap respons membawa tiga header: X-RateLimit-Limit (batas harianmu), X-RateLimit-Remaining (sisa yang masih kamu punya) dan X-RateLimit-Reset (waktu pengaturan ulang, dalam detik Unix). Agen yang tahu tata krama membaca X-RateLimit-Remaining dan mengurangi kecepatannya sebelum menabrak tembok.

• 429 : kuota harian habis. Header Retry-After memberi tahu jumlah detik yang harus ditunggu sebelum pengaturan ulang.
• 503 : layanan tidak berhasil memverifikasi kunci. Coba lagi 30 detik kemudian.
• Kesalahan lainnya berupa objek JSON dengan field error yang menjelaskan apa yang salah.

Menguji tanpa menulis satu baris kode pun

Semuanya didokumentasikan di Swagger API. Klik “Authorize”, isi ketiga field tersebut (kunci, organisasi, token), lalu coba setiap pemanggilan dengan tombol “Try it out”. Tetap hati-hati: percobaan ini masuk hitungan kuotamu, seperti permintaan apa pun. Swagger yang sama ini berfungsi sebagai kontrak untuk AI: berikan alamat file https://devops.digital3d.com/swagger/v1/swagger.json kepadanya dan AI itu menemukan sendiri semua pemanggilan.

Kenapa berlangganan?

Karena semua ini berjalan di server yang saya bayar. Versi gratis tetap tersedia untuk pengujian dan penggunaan ringan. Kalau sebuah agen bekerja setiap hari pada repositorimu, langganan PRO seharga €12 per bulan menaikkan batas menjadi 1000 permintaan per hari, mencakup panduan TV lengkap dan semua perangkat lunakku, dan itulah yang membuat layanan ini tetap hidup. Penggunaan komersial tanpa langganan tidak diizinkan. Dan kalau kamu membutuhkan lebih banyak, tulis kepadaku.