REST API 시작

아티클
03/25/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

이 문서에 제공된 REST API를 사용하여 Azure DevOps와 앱을 통합합니다.

API는 다음 예제와 같이 일반적인 패턴을 따릅니다.

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

팁

API가 발전함에 따라 모든 요청에 API 버전을 포함하는 것이 좋습니다. 이 방법은 중단시킬 수 있는 API의 예기치 않은 변경을 방지하는 데 도움이 될 수 있습니다.

Azure DevOps Services

Azure DevOps Services의 instance 경우 다음과 dev.azure.com/{organization} collection 같으므로 패턴은 DefaultCollection다음과 같습니다.

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

다음 예제에서는 조직에서 프로젝트 목록을 가져오는 방법을 보여줍니다.

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

HTTP 헤더를 통해 PAT(개인용 액세스 토큰)를 제공하려면 먼저 Base64 문자열로 변환해야 합니다. 다음 예제에서는 C#을 사용하여 Base64로 변환하는 방법을 보여줍니다. 그런 다음 결과 문자열을 형식의 HTTP 헤더로 제공할 수 있습니다.

Authorization: Basic BASE64PATSTRING

다음 예제에서는 HttpClient 클래스를 사용하는 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 = client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects").Result)
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

대부분의 샘플은 서비스를 사용하여 인증하기 위한 컴팩트한 예제인 PAT를 사용합니다. 그러나 MSAL(Microsoft 인증 라이브러리), OAuth 및 세션 토큰을 포함하여 Azure DevOps Services에 사용할 수 있는 다양한 인증 메커니즘이 있습니다. 자세한 내용은 시나리오에 가장 적합한 인증 지침을 참조하세요.

Azure DevOps Server

Azure DevOps Server의 instance 경우 다음과 같습니다 {server:port}. 비 SSL 연결의 기본 포트는 8080입니다.

기본 컬렉션은 DefaultCollection있지만 모든 컬렉션을 사용할 수 있습니다.

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

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

비 SSL 연결에서 동일한 목록을 얻으려면 다음을 수행합니다.

curl -u {username}:{personalaccesstoken} http://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0

이러한 예제에서는 PAT를 만들어야 하는 PAT를 사용합니다.

응답

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

{
    "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"
            },
            "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"
            },
            "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
}

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

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

HTTP 동사

동사	다음 용도로 사용됩니다.
GET	리소스 또는 리소스 목록 가져오기
게시	리소스 만들기, 고급 쿼리를 사용하여 리소스 목록 가져오기
PUT	리소스가 없는 경우 또는 리소스가 없는 경우 업데이트합니다.
PATCH	리소스 업데이트
Delete	리소스 삭제

헤더 및 요청 콘텐츠 요청

요청 본문(일반적으로 POST, PUT 및 PATCH 동사 포함)을 제공하는 경우 본문을 설명하는 요청 헤더를 포함합니다. 예를 들면 다음과 같습니다.

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/build-release/requests

Content-Type: application/json

{
   "definition": {
      "id": 3
   },
   "reason": "Manual",
   "priority": "Normal"
}

HTTP 메서드 재정의

일부 웹 프록시는 HTTP 동사 GET 및 POST만 지원할 수 있지만 PATCH 및 DELETE와 같은 최신 HTTP 동사는 지원하지 않습니다. 호출이 이러한 프록시 중 하나를 통과할 수 있는 경우 헤더를 사용하여 POST 메서드를 사용하여 실제 동사를 보내 메서드를 재정의할 수 있습니다. 예를 들어 작업 항목(PATCH _apis/wit/workitems/3)을 업데이트할 수 있지만 GET 또는 POST만 허용하는 프록시를 통과해야 할 수 있습니다. 적절한 동사(이 경우 PATCH)를 HTTP 요청 헤더 매개 변수로 전달하고 POST를 실제 HTTP 메서드로 사용할 수 있습니다.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

응답 코드

응답	주의
200	성공하고 응답 본문이 있습니다.
201	리소스를 만들 때 성공합니다. 일부 API는 리소스를 성공적으로 만들 때 200을 반환합니다. 확실히 사용 중인 API에 대한 문서를 확인합니다.
204	성공, 그리고 응답 본문이 없습니다. 예를 들어 리소스를 삭제하면 이 응답이 표시됩니다.
400	URL 또는 요청 본문의 매개 변수가 잘못되었습니다.
401	인증에 실패했습니다. 종종 이 응답은 누락되거나 잘못된 형식의 권한 부여 헤더 때문입니다.
403	인증된 사용자에게 작업을 수행할 수 있는 권한이 없습니다.
404	리소스가 없거나 인증된 사용자에게 리소스가 있는지 확인할 수 있는 권한이 없습니다.
409	서버의 데이터 요청과 상태 간에 충돌이 있습니다. 예를 들어 끌어오기 요청을 제출하려고 하고 커밋에 대한 끌어오기 요청이 이미 있는 경우 응답 코드는 409입니다.

Azure DevOps Services는 Azure DevOps Services REST API에 Ajax 요청을 수행하는 것 dev.azure.com/* 외에는 기본 JavaScript 코드가 제공되도록 하는 CORS를 지원합니다. 각 요청은 자격 증명을 제공해야 합니다(PAT 및 OAuth 액세스 토큰은 모두 지원되는 옵션임). 예시:

    $( document ).ready(function() {
        $.ajax({
            url: 'https://dev.azure.com/fabrikam/_apis/projects?api-version=1.0',
            dataType: 'json',
            headers: {
                'Authorization': 'Basic ' + btoa("" + ":" + myPatToken)
            }
        }).done(function( results ) {
            console.log( results.value[0].id + " " + results.value[0].name );
        });
    });

(개인용 액세스 토큰으로 대체 myPatToken )

버전 관리

Azure DevOps REST API는 API가 진화함에 따라 애플리케이션 및 서비스가 계속 작동하도록 버전이 지정됩니다.

가이드라인

모든 요청(필수)을 사용하여 API 버전을 지정합니다.
다음과 같이 API 버전 서식 지정: {major}. {minor}-{stage}. {resource-version}. 예: 1.0, 1.1, 1.2-preview, 2.0.
미리 보기 상태일 때 다음 버전 형식1.0-preview.11.0-preview.2을 사용하여 API의 특정 수정 버전을 지정합니다. API가 릴리스되면(예: 1.0) 미리 보기 버전(1.0-preview)은 더 이상 사용되지 않으며 12주 후에 비활성화할 수 있습니다.
릴리스된 버전의 API로 업그레이드합니다. 미리 보기 API가 비활성화되면 버전을 지정 -preview 하는 요청이 거부됩니다.

사용

HTTP 요청의 헤더 또는 URL 쿼리 매개 변수로 API 버전을 지정합니다.

HTTP 요청 헤더:

Accept: application/json;api-version=1.0

쿼리 매개 변수;

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

지원되는 버전

지원되는 버전에 대한 자세한 내용은 REST API 버전 관리, 지원되는 버전을 참조 하세요.

다음을 통해 공유

REST API 시작

Azure DevOps Services

Azure DevOps Server

응답

HTTP 동사

헤더 및 요청 콘텐츠 요청

HTTP 메서드 재정의

응답 코드

버전 관리

가이드라인

사용

지원되는 버전

피드백

추가 리소스

다음을 통해 공유

REST API 시작

Azure DevOps Services

Azure DevOps Server

응답

HTTP 동사

헤더 및 요청 콘텐츠 요청

HTTP 메서드 재정의

응답 코드

CORS(원본 간 리소스 공유)

버전 관리

가이드라인

사용

지원되는 버전

피드백

추가 리소스