メインコンテンツへ移動

AI向けAzure DevOps API


あなたのAIアシスタントはコードを読めますが、Azure DevOpsのリポジトリで眠っているものまでは見えません。このAPIが橋渡しをします。プロジェクト、ファイル、コミット、プルリクエスト、すべてをシンプルなJSONで、あなた自身のアクセス権限を使って扱えます。

最初にはっきりさせておきましょう。これはまずマシン向けに作りました。AIエージェント、MCPサーバー(Claudeのようなアシスタントが外部ツールを呼び出せるようにするプロトコル)、あるいは単純なスクリプトです。人間も歓迎ですが、考え方としては、AIがAzure DevOpsのAPIがどう動くのかを推測しなくても、「このファイルを見せて」や「このコミットで何が変わったの」と頼めるようにすることです。このAPIは強力ですが、正直かなり取っつきにくいので。

これがサービスのSwaggerページで、すべての呼び出しが一覧になっています。

Health、WhoAmI、Projects、ReposのルートがあるDigital3DのAzure DevOps APIのSwaggerページ

無料版またはPRO版:利用できるもの

どちらのプランでも、書き込みを含めて同じ呼び出しを利用できます。唯一の違いは、1日あたりのリクエスト数です。緑のバーには、1日にリクエストできる数が表示されます。

無料API

0ユーロ、アカウントのキーだけで使えます

101日あたり
  • 1日あたり10リクエスト
  • 読み取りと書き込みを含むすべての呼び出し
  • 1回のリクエストで最大50ファイルを読み取り可能
  • エージェントを接続して、コードを理解できるか確認するには十分

PRO API

月12ユーロ、私のソフトウェアがすべて含まれます

1日あたり1000
  • 1日あたり1000リクエスト
  • 1日中あなたのリポジトリで作業するエージェントには十分
  • 11日間の完全なTVガイドと、私のソフトウェアがおまけで付いてきます
  • 同じキーのまま、次のリクエストから有効

PROに切り替える

カウンターは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用です。

ヘッダー設定する内容役割
AuthorizationBearer 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分もかかりません。

  • 毎日無料でダウンロードできるXMLTVファイル
  • 記事にコメントし、他の読者に返信する
  • フォローしている新しい記事をメールで通知する

現在コメントはありません。

Une erreur s'est produite. Cette application peut ne plus répondre jusqu'à ce qu'elle soit rechargée.Veuillez contacter l'auteur. Reload 🗙