네 인공지능을 위한 Azure DevOps API

네 AI 어시스턴트는 코드를 읽을 수 있지만, Azure DevOps 저장소에 잠들어 있는 것은 보지 못해. 이 API가 그 간극을 메워줘: 프로젝트, 파일, 커밋, 풀 리퀘스트를 네가 가진 접근 권한 그대로, 간단한 JSON으로 처리해.

처음부터 분명히 하자면: 나는 이걸 먼저 기계를 위해 설계했어. AI 에이전트, MCP 서버(Claude 같은 어시스턴트가 외부 도구를 호출할 수 있게 해주는 프로토콜), 아니면 단순한 스크립트 말이야. 사람도 환영하지만, 아이디어는 AI가 Azure DevOps API가 어떻게 작동하는지 추측할 필요 없이 “이 파일을 보여줘” 또는 “이 커밋에서 무엇이 바뀌었어”라고 물을 수 있게 하는 거야, 강력하지만 솔직히 꽤 복잡하거든.

모든 호출이 나열되어 있는 이 서비스의 Swagger 페이지는 여기야:

무료 또는 PRO: 네가 사용할 수 있는 것

두 요금제 모두 쓰기를 포함해 같은 호출에 접근할 수 있어. 유일한 차이는 하루 요청 수야. 초록색 막대는 하루에 요청할 수 있는 양을 보여줘.

카운터는 UTC 자정에 다시 시작하니까, 프랑스에서는 계절에 따라 새벽 1시 또는 2시야. 에이전트가 말이 많으면 요청 10회는 금방 사라져. 오래 쓰기 위한 내 조언은 이거야: files:batch 호출은 최대 50개 파일을 가져오면서 요청은 단 한 번으로만 계산돼.

이 API로 할 수 있는 일

모두 https://devops.digital3d.com/api/Devops/ 아래에 있는 호출이 스무 개 정도 있어. 알파벳순이 아니라 필요에 따라 묶어뒀어:

서비스 호출도 두 가지 있습니다. Health는 키 없이 응답하고 할당량에 절대 포함되지 않으며, WhoAmI는 헤더가 제대로 이해되었는지 확인합니다.

보내야 할 세 가지 헤더

모든 요청에는 헤더가 세 개 붙습니다. 하나는 저를 위한 것이고, 두 개는 Azure DevOps를 위한 것입니다.

Digital3D 키. 계정을 만드세요, 이메일 주소를 인증한 다음 계정에 표시된 키를 복사하세요. 다른 제 서비스에 사용하는 키와 같은 키입니다. 예전 버전을 사용하고 있었다면 주의하세요. X-Api-Key 헤더는 이제 Authorization으로 바뀌었습니다.

조직 이름. https://dev.azure.com에 로그인하고 주소를 확인하세요. https://dev.azure.com/ma-societe/에서는 보내야 할 값이 ma-societe입니다. 프로젝트 이름이 아니라 조직 이름입니다.

개인 액세스 토큰(PAT, 권한이 제한된 일종의 비밀번호입니다). Azure DevOps에서 오른쪽 위의 사용자 설정 아이콘을 클릭한 다음 “Personal access tokens”와 “New Token”을 클릭하세요. 알아보기 쉬운 이름과 짧은 기간(30일 또는 90일)을 지정하고, 필요한 권한만 부여하세요. 모든 내용을 읽는 데는 “Code (Read)”와 “Project and Team (Read)”면 충분합니다. 에이전트가 기록해야 할 때만 “Code (Read & Write)”를 추가하세요. 토큰은 바로 복사하세요. Azure DevOps는 토큰을 한 번만 표시합니다.

여러분의 코드이기 때문에 한마디 조심하라는 말을 하겠습니다. 이 토큰은 저장소에 접근할 수 있고, 모든 요청마다 제 서버를 거쳐 갑니다. 최소한의 권한과 만료일을 지정하고, 더 이상 필요하지 않게 되는 날 바로 폐기하세요. 제가 여러분이라면 그렇게 하겠습니다.

첫 번째 호출

먼저 세 개의 헤더가 통과하는지 확인하세요:

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

그다음은 저장소 목록입니다. 각 저장소에는 식별자(GUID)가 있고, 다른 모든 호출은 {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"

저장소의 기본 브랜치에서 모든 C# 파일을 찾으려면:

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"

그리고 한 번의 요청으로 여러 파일을 읽으려면 경로 목록을 포함한 POST입니다:

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

브랜치가 필요한 모든 곳에서(refName), main이라고 쓰거나 완전한 형식인 refs/heads/main이라고 쓸 수 있습니다. 아무것도 넣지 않으면 저장소의 기본 브랜치가 사용됩니다.

비교하고 쓰기

여기서부터 에이전트에게 정말 흥미로워집니다. 두 커밋 사이에 무엇이 달라졌는지 알아보려면:

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

summaryOnly을 true로 설정하면(기본값), 응답은 간결한 요약입니다: 변경된 파일의 합계와 경로입니다. 의도된 동작입니다. AI는 읽는 단어 하나하나에 비용을 지불하므로, 요약으로 충분할 때 Azure DevOps의 날것인 응답을 그대로 건넬 필요는 없습니다.

그리고 파일을 쓰려면:

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

자, 이제 2분만 진지하게 얘기해 보자. AI가 저장소에 쓰도록 내버려 두는 건 안전장치를 마련해 두고 하는 일이다. 이를 위한 설정은 세 가지가 있다. createBranch는 브랜치가 없으면 만들어 주므로, 에이전트를 따로 작업하게 하고 pull request에서 작업 내용을 검토할 수 있다. expectHeadCommit는 에이전트가 본 마지막 커밋을 알려 준다. 그 사이에 누군가 푸시했다면 다른 사람의 작업을 덮어쓰는 대신 쓰기를 거부한다. 그리고 작성되는 파일의 크기는 서버 측에서 제한된다. 아예 쓰기를 허용하고 싶지 않다면 읽기 전용 토큰이 가장 안전하다. Azure DevOps가 알아서 거부할 테니까.

내부 구조

API의 동작을 설명해 주는 몇 가지 기술적 선택.

각 요청마다 어떤 조직에 어떤 토큰으로 질의할지 정하는 건 바로 너다. 따라서 같은 API로 어떤 Azure DevOps 조직이든 사용할 수 있고, API는 네 토큰이 허용하는 것 이상을 볼 수 없다.

Digital3D 키가 먼저 확인된다. 키가 승인되는 즉시 요청 하나로 계산되며, 그다음에 Azure DevOps가 어떻게 응답하는지는 상관없다. 따라서 잘못된 조직 이름이나 만료된 토큰도 요청 하나를 소모한다. 그러니 이것저것 시도하기보다는 WhoAmI로 설정을 한 번 제대로 확인해 두는 게 좋다.

두 401 오류는 비슷해 보이지만 원인은 같지 않다. WWW-Authenticate: Bearer 헤더가 붙은 오류는 내가 보내는 것이다. Digital3D 키가 없거나 거부된 것이고, 아무것도 계산되지 않는다. 이 헤더가 붙지 않은 오류는 Azure DevOps에서 온 것이다. X-Ado-Org와 X-Ado-Pat 쪽을 살펴봐라.

응답은 부담 없이 처리할 수 있도록 제한되어 있다. 일괄 읽기는 파일 50개와 약 2MB, 파일 목록은 기본값으로 항목 2000개, 로그는 기본값으로 커밋 50개다. 이 제한은 top과 maxItems 매개변수로 조정할 수 있다.

할당량 확인하기

키가 승인되면 각 응답에는 세 개의 헤더가 붙습니다: X-RateLimit-Limit(오늘의 한도), X-RateLimit-Remaining(남은 한도), 그리고 X-RateLimit-Reset(초 단위 Unix 시간으로 표시한 한도 초기화 시각)입니다. 예의 바른 에이전트라면 X-RateLimit-Remaining을 읽고 벽에 부딪히기 전에 속도를 줄입니다.

• 429: 오늘의 할당량이 소진되었습니다. Retry-After 헤더에 초기화 전까지 기다려야 하는 초 수가 나옵니다.
• 503: 서비스가 키를 확인하지 못했습니다. 30초 후에 다시 시도하면 됩니다.
• 그 밖의 오류는 무엇이 잘못되었는지 알려주는 error 필드가 들어 있는 JSON 객체입니다.

코드 한 줄 쓰지 않고 테스트하기

모든 내용은 API Swagger에 문서화되어 있습니다. “Authorize”를 클릭하고 세 필드(키, 조직, 토큰)를 입력한 다음 “Try it out” 버튼으로 각 호출을 시도해 보세요. 그래도 주의할 점은 있습니다: 이런 테스트도 다른 요청과 마찬가지로 할당량에 포함됩니다. 이 Swagger는 AI의 계약서 역할도 합니다: https://devops.digital3d.com/swagger/v1/swagger.json 파일 주소를 알려주면 AI가 호출을 혼자서 찾아냅니다.

왜 구독이 필요한가?

이 모든 것이 내가 비용을 내는 서버에서 돌아가기 때문입니다. 무료 서비스는 테스트와 가벼운 사용을 위해 그대로 남겨 둡니다. 에이전트가 매일 당신의 저장소에서 작업한다면, 월 12€인 PRO 구독으로 한도가 하루 1000건으로 늘어나고, TV 가이드 전체와 내 소프트웨어 전부가 포함되며, 이 구독이 서비스를 계속 살려 둡니다. 구독 없이 상업적으로 사용하는 것은 허용되지 않습니다. 더 많이 필요하다면 내게 연락하세요.