AI向けAzure DevOps API
あなたのAIアシスタントはコードを読めますが、Azure DevOpsのリポジトリで眠っているものまでは見えません。このAPIが橋渡しをします。プロジェクト、ファイル、コミット、プルリクエスト、すべてをシンプルなJSONで、あなた自身のアクセス権限を使って扱えます。
最初にはっきりさせておきましょう。これはまずマシン向けに作りました。AIエージェント、MCPサーバー(Claudeのようなアシスタントが外部ツールを呼び出せるようにするプロトコル)、あるいは単純なスクリプトです。人間も歓迎ですが、考え方としては、AIがAzure DevOpsのAPIがどう動くのかを推測しなくても、「このファイルを見せて」や「このコミットで何が変わったの」と頼めるようにすることです。このAPIは強力ですが、正直かなり取っつきにくいので。
これがサービスのSwaggerページで、すべての呼び出しが一覧になっています。
無料版またはPRO版:利用できるもの
どちらのプランでも、書き込みを含めて同じ呼び出しを利用できます。唯一の違いは、1日あたりのリクエスト数です。緑のバーには、1日にリクエストできる数が表示されます。
無料API
0ユーロ、アカウントのキーだけで使えます
- 1日あたり10リクエスト
- 読み取りと書き込みを含むすべての呼び出し
- 1回のリクエストで最大50ファイルを読み取り可能
- エージェントを接続して、コードを理解できるか確認するには十分
PRO API
月12ユーロ、私のソフトウェアがすべて含まれます
- 1日あたり1000リクエスト
- 1日中あなたのリポジトリで作業するエージェントには十分
- 11日間の完全なTVガイドと、私のソフトウェアがおまけで付いてきます
- 同じキーのまま、次のリクエストから有効
カウンターはUTCの午前0時にリセットされるので、フランスでは季節によって午前1時か2時です。10リクエストなんて、おしゃべりなエージェントならすぐになくなります。長持ちさせるための私のアドバイスです。files:batch呼び出しなら最大50ファイルを取得でき、1回のリクエストとしてしかカウントされません。
このAPIでできること
約20個の呼び出しがあり、すべてhttps://devops.digital3d.com/api/Devops/配下です。アルファベット順ではなく、用途ごとに整理しました。
| 必要なこと | 呼び出し | 返ってくるもの |
|---|---|---|
| 把握する | Projects, Repos, Repos/{repoId} | 組織のプロジェクト、Gitリポジトリ(すべて、またはプロジェクトのもの)、そしてデフォルトブランチ付きのリポジトリ情報。 |
| コードを閲覧する | tree, files, search | フォルダーのツリー構造、ブランチ内のすべてのファイル一覧、または **/*.cs のようなパターンによる検索。 |
| ファイルを読む | file, fileAt, files:batch | ブランチ上または特定のコミット時点のファイルの生の内容、または一度に最大50ファイル。 |
| 履歴を追う | branches, tags, commits, pushes | ブランチ、タグ、コミットログ(パスとブランチで絞り込み可能)、コミットの詳細と変更されたファイルの一覧。 |
| プルリクエストをレビューする | pullrequests | 有効な、完了した、または放棄されたマージリクエストと、そのうち1つの詳細。 |
| 書き込む | write | ファイルの作成または変更を、1つのコミットによるpushとして実行。 |
サービス呼び出しはもう2つあります。Healthはキーなしで応答し、カウントされることはありません。WhoAmIは、あなたのヘッダーが正しく理解されていることを確認します。
送信する3つのヘッダー
各リクエストには3つのヘッダーを付けます。1つは私用、2つはAzure DevOps用です。
| ヘッダー | 設定する内容 | 役割 |
|---|---|---|
Authorization | Bearer VotreCleApi | あなたのDigital3Dキーです。クォータを持っているのはこのキーです。 |
X-Ado-Org | あなたの組織名 | どのAzure DevOps組織に問い合わせるかをAPIに伝えます。 |
X-Ado-Pat | あなたの個人アクセストークン | あなたの権限で、余計な権限を一切加えずに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で表示されるのは一度だけです。
あなたのコードに関わることなので、ひとつ注意しておきます。このトークンはあなたのリポジトリへのアクセスを許可し、リクエストのたびに私のサーバーを経由します。権限は最低限にし、有効期限を設定し、必要なくなった日に失効させてください。私があなたの立場なら、そうします。
初回の呼び出し
まず、3つのヘッダーが通ることを確認してください:
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"複数のファイルを1回のリクエストで読むなら、パスの一覧を指定する 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 と書けます。何も指定しなければ、リポジトリのデフォルトブランチが使われます。
比較して書き込む
ここから、エージェントにとって本当に面白くなります。2つのコミットの違いを知るには:
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にリポジトリへの書き込みをさせるなら、ガードレールを用意しておくものだ。 そのための設定は3つある。 createBranchはブランチが存在しない場合に作成するので、エージェントを分離した場所で作業させ、プルリクエストでその成果を確認できる。 expectHeadCommitは、エージェントが見た最後のコミットを通知する : その間に誰かがプッシュしていたら、相手の作業を上書きする代わりに書き込みが拒否される。 そして、書き込めるファイルのサイズにはサーバー側で上限が設定されている。 そもそも書き込みを一切させたくないなら、最も安全なのは読み取り専用トークンだ : Azure DevOpsが自動的に拒否してくれる。
内部の仕組み
APIの動作を説明するいくつかの技術的な選択。
どのリクエストでも、どの組織にどのトークンで問い合わせるかを指定するのはあなた自身だ。 そのため同じAPIであらゆるAzure DevOps組織を利用でき、APIが見られるのはあなたのトークンが許可している範囲だけだ。
まずDigital3Dキーが検証される。 キーが受け入れられた時点で1リクエストとして数えられ、その後Azure DevOpsが何を返すかは関係ない。 つまり、組織名が間違っていたりトークンの期限が切れていたりしても1リクエストを消費する : だから、試行錯誤するよりも、WhoAmIで一度設定を確認しておく意味がある。
2つの401エラーはよく似ているが、原因は同じではない。 WWW-Authenticate: Bearerヘッダーが付いているほうは僕が返している : Digital3Dキーがないか拒否されていて、何もカウントされない。 付いていないほうはAzure DevOpsから返っている : X-Ado-OrgとX-Ado-Patを確認してみよう。
レスポンスには上限があり、扱いやすい量に抑えられている : まとめて読み取る場合は50ファイルで約2 MB、ファイル一覧はデフォルトで2000エントリ、ログはデフォルトで50コミットだ。 これらの上限はtopとmaxItemsパラメーターで調整できる。
クォータを確認する
キーが受け付けられると、各レスポンスには3つのヘッダーが付きます: X-RateLimit-Limit (1日の上限)、X-RateLimit-Remaining (残りの回数)、X-RateLimit-Reset (リセット時刻、Unix秒)です。行儀のいいエージェントはX-RateLimit-Remainingを読み、壁にぶつかる前にスピードを落とします。
429: その日のクォータを使い切りました。Retry-Afterヘッダーに、リセットまで待つ秒数が入っています。503: サービスがキーを確認できませんでした。30秒後にもう一度試してください。- その他のエラーは、何が問題なのかを示す
errorフィールドを持つJSONオブジェクトです。
コードを1行も書かずに試す
すべてAPIのSwaggerにドキュメント化されています。「Authorize」をクリックし、3つの項目 (キー、組織、トークン) を入力してから、「Try it out」ボタンで各呼び出しを試してください。ただし注意してください: これらの試行も、他のリクエストと同じようにクォータにカウントされます。このSwaggerはAIにとっての契約としても使えます: https://devops.digital3d.com/swagger/v1/swagger.jsonというファイルのアドレスを渡せば、AIが呼び出しを自分で見つけてくれます。
なぜサブスクリプションなのか?
これが全部、私が料金を払っているサーバー上で動いているからです。無料版はテストや軽い利用のために残しています。あなたのリポジトリでエージェントが毎日作業するなら、月額12ユーロのPROサブスクリプションで上限が1日1000リクエストまで増え、完全版のTVガイドと私のソフトウェア全部が含まれ、これがサービスを存続させています。サブスクリプションなしでの商用利用は認められていません。もっと必要なら、私に書いてください。

会話に参加する
この記事にコメントするにはアカウントが必要です。無料で作成でき、1分もかかりません。
現在コメントはありません。