次の方法で共有

REST API を使い始める

Azure DevOps サービス |Azure DevOps Server |Azure DevOps Server 2022

Azure DevOps REST API は、作業項目、リポジトリ、ビルド、リリースなどへのプログラムによる強力なアクセスを提供します。 カスタム統合の構築、ワークフローの自動化、Azure DevOps機能の拡張など、実装を成功させるには基本的なパターンと概念を理解することが不可欠です。

ヒント

コーディングを開始する準備はできましたか? 最新の認証パターンを使用した完全な作業例については、 REST API のサンプル に進んでください。

この記事では、Azure DevOps REST API の基本的な概念とパターンについて説明します。 実際の実装例については、 REST API のサンプルを参照してください。

ヒント

この記事の後半でAIを使用してこのタスクを支援することができます。また、作業を開始するには、Azure DevOps MCP ServerでAIサポートを有効にする方法を参照してください。

URL 構造

API は、次の例に示すように、一般的なパターンに従います。

VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}

ヒント

API が進化するにつれて、すべての要求に API バージョンを含めます。 この方法は、アプリケーションを中断する可能性がある API の予期しない変更を回避するのに役立ちます。

Azure DevOps Services の場合、instance は dev.azure.com/{organization}、collection は DefaultCollection であるため、パターンは次の例のようになります。

VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}

エンドポイントの例:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

認証

Azure DevOps REST API では、いくつかの認証方法がサポートされています。

  • Microsoft Entra ID - 運用アプリケーションに推奨
  • 個人用アクセス トークン (AT) - スクリプトとテストのための簡単な認証
  • サービス プリンシパルとマネージド ID - 自動化されたシナリオ用

重要

より安全なMicrosoft Entraトークンを、リスクの高い個人アクセス トークンよりも使用することを検討してください。 詳細については、「 PAT 使用量の削減」を参照してください。 認証ガイダンスを確認して、ニーズに適した認証メカニズムを選択します。

応答形式

Azure DevOps REST API は通常、JSON 応答を返します。 応答構造の例を次に示します。

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "Team Foundation Version Control projects"
        }
    ],
    "count": 1
}

応答は JSON です。これは通常、REST API から返されるものですが、 Git BLOB など、いくつかの例外があります。

ヒント

これらの応答を解析する方法を示す完全な作業例については、 REST API のサンプルを参照してください。

HTTP メソッドと操作

Azure DevOps REST API では、標準の HTTP メソッドが使用されます。

メソッド 使用目的... 例
GET リソースまたはリソースの一覧を取得する プロジェクト、作業項目を取得する
POST 高度なクエリを使用してリソースを作成するか、リソースを取得する 作業項目の作成、作業項目のクエリ
PUT リソースを作成または完全に置き換える ビルド定義を置き換え、ポリシーを更新する
PATCH リソースの特定のフィールドを更新する 作業項目フィールドを更新する
削除 リソースの削除 作業項目の削除

ヒント

完全なコード サンプルを含む各 HTTP メソッドの実際の例については、 REST API のサンプルを参照してください。

要求ヘッダーとコンテンツ

要求本文 (通常は POST、PUT、PATCH) を指定する場合は、適切なヘッダーを含めます。

Content-Type: application/json

PATCH 操作を作業項目に適用する場合は、次を使用します。

Content-Type: application/json-patch+json

HTTP メソッドのオーバーライド

一部の Web プロキシでは、HTTP 動詞 GET と POST のみがサポートされます。 PATCH や DELETE などの最新の HTTP 動詞はサポートされていません。 呼び出しがこれらのプロキシのいずれかを通過する可能性がある場合は、POST メソッドとヘッダーを使用してメソッドをオーバーライドすることで、実際の動詞を送信します。 たとえば、 作業項目 (PATCH _apis/wit/workitems/3) を更新したいが、GET または POST のみを許可するプロキシを経由する必要がある場合があります。 適切な動詞 (この場合は PATCH) を HTTP 要求ヘッダー パラメーターとして渡し、実際の HTTP メソッドとして POST を使用できます。

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

応答コード

HTTP 応答コードを理解することは、API 応答を適切に処理するのに役立ちます。

[応答] 意味 注記
200 Success 応答本文に要求されたデータが含まれている
201 作成済み リソースが正常に作成されました
204 Success 応答本文なし (DELETE と共通)
400 正しくない要求 パラメーターまたは要求本文が無効です
401 無許可 認証に失敗したか、見つからない
4:03 許可されていません ユーザーに操作のアクセス許可がない
404 見つかりません リソースが存在しないか、閲覧するためのアクセス権限がない
409 葛藤 要求が現在のリソースの状態と競合する

API のバージョン管理

Azure DevOps REST API は、API の進化に伴ってアプリケーションが動作し続けられるようにバージョン管理されています。

ガイドライン

  • すべての要求で API バージョンを常に指定する (必須)
  • {major}.{minor}または{major}.{minor}-{stage} ({major}.{minor}、7.2-preview など) として API バージョンを書式設定する
  • 使用可能な場合は、特定のプレビュー リビジョンを使用します: 7.2-preview.1、 7.2-preview.2
  • プレビュー API が非推奨になった場合のリリース済みバージョンへのアップグレード

使用方法

URL クエリ パラメーターとして API バージョンを指定します。

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

または、要求ヘッダーで次の手順を実行します。

Accept: application/json;api-version=7.2

サポートされているバージョンについては、 REST API のバージョン管理を参照してください。

その他のリソース

実際の実装ガイダンスと完全なコード例については、次を参照してください。

AI を使用して REST API 呼び出しを構築する

エージェント モードで Azure DevOps MCP Server を AI エージェントに接続する場合は、自然言語プロンプトを使用して REST API 呼び出しを生成およびトラブルシューティングできます。

Task プロンプトの例
GET 要求をビルドする Show me how to construct a GET request to list all projects in my Azure DevOps organization using the REST API
POST ボディを作成する Generate the JSON-patch body for creating a work item using the Azure DevOps REST API
認証の処理 Write C# code to call the Azure DevOps REST API with a Bearer token from Microsoft Entra ID
API 領域を探索する What Azure DevOps REST API endpoints are available for managing Git pull requests?
API 応答の解析 Show me how to deserialize an Azure DevOps REST API response into C# objects and handle pagination with continuation tokens
API エラーのデバッグ I'm getting a 400 error when calling the Azure DevOps work item update API — help me understand the correct PATCH format

注

エージェント モードと MCP サーバーでは自然言語が使用されるため、これらのプロンプトを調整したり、フォローアップの質問をして結果を絞り込むことができます。

次のステップ

REST API サンプルを試す

  • Last updated on