AZURE DEVOPS SERVICES REST API 참조

Azure DevOps Services/Azure DevOps Server REST API 참조를 시작합니다.

REST(Representational State Transfer) API는 HTTP 작업(메서드)의 집합을 지원하는 서비스 엔드포인트로, 서비스의 리소스에 대한 만들기, 검색, 업데이트 또는 삭제 액세스 권한을 제공합니다. 이 문서에서는 다음을 안내합니다.

• REST API 요청/응답 쌍의 기본 구성 요소입니다.
• REST 요청을 만들고 보내고 응답을 처리하는 방법에 대한 개요입니다.

대부분의 REST API는 클라이언트 라이브러리를 통해 액세스할 수 있으며 클라이언트 코드를 크게 간소화하는 데 사용할 수 있습니다.

REST API 요청/응답 쌍의 구성 요소

REST API 요청/응답 쌍은 5개의 구성 요소로 구분할 수 있습니다.

1. 다음 형식의 요청 URI입니다. VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

   • instance: 요청을 보내는 Azure DevOps Services organization 또는 TFS 서버입니다. 다음과 같이 구조화됩니다.
     • Azure DevOps Services:dev.azure.com/{organization}
     • TFS: {server:port}/tfs/{collection} (기본 포트는 8080이며 컬렉션 값은 이어야 하지만 모든 컬렉션일 DefaultCollection 수 있음)
   • 리소스 경로: 리소스 경로는 다음과 같습니다. _apis/{area}/{resource} 예: _apis/wit/workitems.
   • api-version: API가 발전함에 따라 앱 또는 서비스가 중단되지 않도록 모든 API 요청에 api 버전이 포함되어야 합니다. api-version은 형식입니다. 예를 들면 다음과 같습니다 {major}.{minor}[-{stage}[.{resource-version}]].
     • api-version=1.0
     • api-version=1.2-preview
     • api-version=2.0-preview.1

   참고: 영역 및 팀 프로젝트는 API 요청에 따라 선택 사항입니다. 아래 의 TFS-REST API 버전 매핑 매트릭스 를 확인하여 TFS 버전에 적용되는 REST API 버전을 찾습니다.

2. HTTP 요청 메시지 헤더 필드:

   • 요청하는 작업의 유형이 무엇인지를 서비스에 알리는 필수 HTTP 메서드(작업 또는 동사로 알려지기도 함)입니다. Azure REST API는 GET, HEAD, PUT, POST 및 PATCH 메서드를 지원합니다.
   • 지정된 URI 및 HTTP 메서드에서 필요로 하는 선택적 추가 헤더 필드입니다. 예를 들어 요청에 대한 클라이언트 권한 부여 정보를 포함하는 전달자 토큰을 제공하는 권한 부여 헤더입니다.

3. URI 및 HTTP 작업을 지원하는 선택적 HTTP 요청 메시지 본문 필드입니다. 예를 들어 POST 작업은 복잡한 매개 변수로 전달되는 MIME 인코딩된 개체를 포함합니다.

   • POST 또는 PUT 작업의 경우 본문에 대한 MIME 인코딩 형식도 콘텐츠 형식 요청 헤더에 지정해야 합니다. 일부 서비스에서는 application/json과 같은 특정 MIME 형식을 사용해야 합니다.

4. HTTP 응답 메시지 헤더 필드:

   • 범위가 2xx 성공 코드부터 4xx 또는 5xx 오류 코드인 HTTP 상태 코드입니다. 또는 API 설명서에 나와 있는 것처럼 서비스 정의된 상태 코드가 반환될 수 있습니다.
   • Content-type 응답 헤더와 같은 요청의 응답을 지원하는 데 필요한 선택적 추가 헤더 필드입니다.

5. 선택적 HTTP 응답 메시지 본문 필드:

   • MIME로 인코딩된 응답 개체는 데이터를 반환하는 GET 메서드의 응답과 같이 HTTP 응답 본문에 반환될 수 있습니다. 일반적으로 이러한 개체는 Content-type 응답 헤더로 표시된 것처럼 JSON 또는 XML과 같은 구조적 형식으로 반환됩니다. 예를 들어 Azure AD 액세스 토큰을 요청하면 응답 본문에 데이터 컬렉션의 여러 이름/값 쌍을 이루는 개체 중 하나인 요소로 access_token 반환됩니다. 이 예제에서는 의 Content-Type: application/json 응답 헤더도 포함됩니다.

요청 만들기

Authenticate

Azure DevOps Services 또는 TFS를 사용하여 애플리케이션 또는 서비스를 인증하는 방법에는 여러 가지가 있습니다. 다음 표는 가장 적합한 방법을 결정하는 훌륭한 방법입니다.

애플리케이션 유형	설명	예제	인증 메커니즘	코드 샘플
대화형 클라이언트 쪽	Azure DevOps Services REST API를 호출하여 사용자 상호 작용을 허용하는 클라이언트 애플리케이션	organization 프로젝트를 열거하는 콘솔 애플리케이션	MSAL(Microsoft 인증 라이브러리)	sample
대화형 JavaScript	GUI 기반 JavaScript 애플리케이션	사용자에 대한 프로젝트 정보를 표시하는 AngularJS 단일 페이지 앱	MSAL	sample
비대화형 클라이언트 쪽	헤드리스 텍스트 전용 클라이언트 쪽 애플리케이션	사용자에게 할당된 모든 버그를 표시하는 콘솔 앱	디바이스 프로필	sample
대화형 웹	GUI 기반 웹 애플리케이션	빌드 요약을 표시하는 사용자 지정 웹 dashboard	OAuth	sample
TFS 애플리케이션	클라이언트 OM 라이브러리를 사용하는 TFS 앱	팀 버그 대시보드를 표시하는 TFS 확장	클라이언트 라이브러리	sample
Azure DevOps Services 확장	Azure DevOps Services 확장	Azure DevOps 확장 샘플	VSS 웹 확장 SDK	샘플 연습

참고: 인증에 대한 자세한 내용은 인증 지침 페이지에서 확인할 수 있습니다.

요청 어셈블

Azure DevOps Services

Azure DevOps Services 경우 instancedev.azure.com/{organization}이므로 패턴은 다음과 같습니다.

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

예를 들어 Azure DevOps Services organization 팀 프로젝트 목록을 가져오는 방법은 다음과 같습니다.

curl -u {username}[:{personalaccesstoken}] https://dev.azure.com/{organization}/_apis/projects?api-version=2.0

HTTP 헤더를 통해 개인용 액세스 토큰을 제공하려면 먼저 Base64 문자열로 변환해야 합니다(다음 예제에서는 C#을 사용하여 Base64로 변환하는 방법을 보여 줍니다). Postman과 같은 특정 도구는 기본적으로 Base64 인코딩을 적용합니다. 이러한 도구를 통해 API를 시도하는 경우 PAT의 Base64 인코딩이 필요하지 않습니다. 그런 다음 결과 문자열을 형식으로 HTTP 헤더로 제공할 수 있습니다.

Authorization: Basic BASE64PATSTRING

여기서는 [HttpClient 클래스](/previous-versions/visualstudio/hh193681(v=vs.118)를 사용하는 C#에 있습니다.

public static async void GetProjects()
{
	try
	{
		var personalaccesstoken = "PAT_FROM_WEBSITE";

		using (HttpClient client = new HttpClient())
		{
			client.DefaultRequestHeaders.Accept.Add(
				new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

			client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
				Convert.ToBase64String(
					System.Text.ASCIIEncoding.ASCII.GetBytes(
						string.Format("{0}:{1}", "", personalaccesstoken))));

			using (HttpResponseMessage response = await client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects"))
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

이 사이트의 대부분의 샘플은 개인용 액세스 토큰을 사용하여 서비스를 인증하는 압축 예제입니다. 그러나 MSAL, OAuth 및 세션 토큰을 포함하여 Azure DevOps Services 사용할 수 있는 다양한 인증 메커니즘이 있습니다. 시나리오에 가장 적합한 지침은 인증 섹션을 참조하세요.

TFS

TFS의 경우 는 instance 이 {server:port}/tfs/{collection} 고 기본적으로 포트는 8080입니다. 기본 컬렉션은 DefaultCollection이지만 모든 컬렉션일 수 있습니다.

기본 포트 및 컬렉션을 사용하여 TFS에서 팀 프로젝트 목록을 가져오는 방법은 다음과 같습니다.

curl -u {username}[:{personalaccesstoken}] https://{server}:8080/tfs/DefaultCollection/_apis/projects?api-version=2.0

위의 예제에서는 개인용 액세스 토큰을 사용해야 하는 개인용 액세스 토큰을 사용합니다.

응답 처리

다음과 같은 응답을 받아야 합니다.

{
    "value": [
        {
            "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "description": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc/DefaultCollection"
            },
            "defaultTeam": {
                "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd"
            }
        },
        {
            "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "name": "Fabrikam-Fiber-Git",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "description": "Gitprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection"
            },
            "defaultTeam": {
                "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7"
            }
        }
    ],
    "count": 2
}

응답은 JSON입니다. Git Blob과 같은 몇 가지 예외가 있지만 일반적으로 REST API에서 다시 가져옵니다.

이제 작업 항목 추적 또는 Git 과 같은 특정 API 영역을 살펴보고 필요한 리소스에 연결할 수 있습니다. 이러한 API에서 사용되는 일반적인 패턴에 대해 자세히 알아보려면 계속 읽어보세요.

API 및 TFS 버전 매핑

아래에서 REST API 버전 및 해당 TFS 릴리스의 빠른 매핑을 찾을 수 있습니다. 모든 API 버전은 언급된 서버 버전과 이후 버전에서 작동합니다.

TFS 버전	REST API 버전	빌드 버전
vNext Azure DevOps Server	7.1
Azure DevOps Server 2022	7.0	versions >= 19.205.33122.1
Azure DevOps Server 2020	6.0	versions >= 18.170.30525.1
Azure DevOps Server 2019	5.0	versions >= 17.143.28621.4
TFS 2018 업데이트 3	4.1	versions >= 16.131.28106.2
TFS 2018 업데이트 2	4.1	versions >= 16.131.27701.1
TFS 2018 업데이트 1	4.0	versions >= 16.122.27409.2
TFS 2018 RTW	4.0	versions >= 16.122.27102.1
TFS 2017 업데이트 2	3.2	versions >= 15.117.26714.0
TFS 2017 업데이트 1	3.1	versions >= 15.112.26301.0
TFS 2017 RTW	3.0	versions >= 15.105.25910.0
TFS 2015 업데이트 4	2.3	versions >= 14.114.26403.0
TFS 2015 업데이트 3	2.3	versions >= 14.102.25423.0
TFS 2015 업데이트 2	2.2	versions >= 14.95.25122.0
TFS 2015 업데이트 1	2.1	versions >= 14.0.24712.0
TFS 2015 RTW	2.0	versions >= 14.0.23128.0

관련 내용

REST API 샘플 및 사용 사례에 대한 통합 설명서를 확인하세요.

• 인증 지침
• 샘플

클라이언트 라이브러리

이러한 REST API에 대한 클라이언트 라이브러리를 검색합니다.

• .NET 개념 설명서 및 .NET 참조 설명서
• Go
• Node.JS
• Python
• Swagger 2.0
• 웹 확장 SDK

이전 버전의 REST API는 어디에 있나요? (4.1 이전)

최근에 엔지니어링 시스템 및 설명서 생성 프로세스를 변경했습니다. 이러한 REST API를 사용하려는 모든 사용자에게 더 명확하고 심층적이고 정확한 설명서를 제공하기 위해 이 변경을 수행했습니다. 기술 제약 조건으로 인해 이 메서드를 사용하여 API 버전 4.1 이상을 문서화할 수 있습니다. 이 변경으로 인해 API 버전 4.1 이상에 대한 설명서를 더 쉽게 사용할 수 있을 것으로 믿습니다.

TFS에서 작업하거나 이전 버전의 REST API를 찾고 있는 경우 TFS 2015, 2017 및 2018에 대한 REST API 개요를 살펴볼 수 있습니다.