다음을 통해 공유

REST API 시작

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Azure DevOps REST API는 작업 항목, 리포지토리, 빌드, 릴리스 등에 대한 강력한 프로그래밍 방식 액세스를 제공합니다. 사용자 지정 통합을 빌드하든, 워크플로를 자동화하든, Azure DevOps 기능을 확장하든 간에 기본적인 패턴과 개념을 이해하는 것은 성공적인 구현에 필수적입니다.

팁 (조언)

코딩을 시작할 준비가 되셨나요? 최신 인증 패턴을 사용하는 전체 작업 예제를 보려면 REST API 샘플 로 건너뜁니다.

이 문서에서는 Azure DevOps REST API에 대한 기본 개념 및 패턴을 다룹니다. 실제 구현 예제는 REST API 샘플을 참조하세요.

URL 구조

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}

엔드포인트 예제:

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

Azure DevOps Server

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

기본 컬렉션은 DefaultCollection이지만, 원하는 다른 컬렉션을 사용할 수 있습니다.

예:

  • SSL: https://{server}/DefaultCollection/_apis/projects?api-version=7.2
  • 비 SSL: http://{server}:8080/DefaultCollection/_apis/projects?api-version=7.2

인증

Azure DevOps REST API는 다음과 같은 여러 인증 방법을 지원합니다.

  • Microsoft Entra ID - 프로덕션 애플리케이션에 권장됨
  • PAT(개인용 액세스 토큰) - 스크립트 및 테스트에 대한 간단한 인증
  • OAuth 2.0 - 비 Microsoft 애플리케이션의 경우
  • 서비스 주체 - 자동화된 시나리오의 경우

중요합니다

Microsoft Entra ID 인증은 프로덕션 애플리케이션에 권장되는 방법입니다. 구현 예제 및 전체 인증 지침은 REST API 샘플 및 인증 지침을 참조하세요.

응답 형식

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": "TeamFoundationVersionControlprojects"
        }
    ],
    "count": 1
}

응답은 JSON입니다. 이 포맷은 일반적으로 REST API에서 반환되는 것이나, Git blobs와 같은 몇 가지 예외가 있습니다.

팁 (조언)

이러한 응답을 구문 분석하는 방법을 보여 주는 전체 작업 예제는 REST API 샘플을 참조하세요.

HTTP 메서드 및 작업

Azure DevOps REST API는 표준 HTTP 메서드를 사용합니다.

메서드 다음 용도로 사용됩니다. 예시
가져오기 리소스 또는 리소스 목록 가져오기 프로젝트 가져오기, 작업 항목
게시하기 고급 쿼리를 사용하여 리소스를 만들거나 리소스 가져오기 작업 항목 만들기, 작업 항목 쿼리
놓다 리소스 만들기 또는 완전히 바꾸기 작업 항목 만들기/업데이트
패치 리소스의 특정 필드 업데이트 작업 항목 필드 업데이트
삭제 리소스 삭제 작업 항목 삭제

팁 (조언)

전체 코드 샘플이 있는 각 HTTP 메서드의 실제 예제는 REST API 샘플을 참조하세요.

요청 헤더 및 콘텐츠

요청 본문(일반적으로 POST, PUT 및 PATCH 포함)을 제공하는 경우 적절한 헤더를 포함합니다.

Content-Type: application/json

작업 항목에 대한 PATCH 작업의 경우 다음을 사용합니다.

Content-Type: application/json-patch+json

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)
}

응답 코드

HTTP 응답 코드를 이해하면 API 응답을 적절하게 처리할 수 있습니다.

응답 의미 비고
200 성공 응답 본문에 요청된 데이터가 포함되어 있습니다.
201 생성됨 리소스를 성공적으로 만들었습니다.
204 성공 응답 본문 없음(DELETE에서 공통)
400 잘못된 요청 잘못된 매개 변수 또는 요청 본문
401 권한 없음 인증 실패 또는 누락
403 금지 사용자에게 작업에 대한 권한이 없음
404 찾을 수 없음 리소스가 없거나 볼 수 있는 권한이 없음
409 충돌 현재 리소스 상태와 요청 충돌

API 버전 관리

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

지침

  • 항상 모든 요청(필수)을 사용하여 API 버전을 지정합니다.
  • API 버전 형식은 다음과 같이 지정합니다: {major}.{minor} 또는 {major}.{minor}-{stage} (예: 7.2, 7.2-preview)
  • 사용할 수 있는 경우, 특정 미리 보기 수정 버전을 사용하세요: 7.2-preview.1, 7.2-preview.2
  • 미리 보기 API가 더 이상 사용되지 않는 경우 릴리스 버전으로 업그레이드

사용법

API 버전을 URL 쿼리 매개 변수로 지정합니다.

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

또는 요청 헤더에서 다음을 수행합니다.

Accept: application/json;api-version=7.2

지원되는 버전은 REST API 버전 지정을 참조하세요.

추가 리소스

실제 구현 지침 및 전체 코드 예제는 다음을 참조하세요.

다음 단계

REST API 샘플 사용해 보기