Azure REST API 참조
Azure REST API 참조를 시작합니다.
REST(표현 상태 전송) API는 서비스의 리소스에 대한 만들기/검색/업데이트/삭제 액세스를 제공하는 HTTP 작업 집합(메서드)을 지원하는 서비스 엔드포인트입니다. 아래 섹션에서는 다음을 안내합니다.
- REST API 요청/응답 쌍의 기본 구성 요소
- REST 요청을 보호하기 위해 클라이언트 애플리케이션을 Azure Active Directory(Azure AD)에 등록하는 방법
- REST 요청을 만들고 보내고 응답을 처리하는 개요
참고
대부분의 Azure 서비스 REST API에는 대부분의 클라이언트 코드를 처리하는 해당 클라이언트 SDK 라이브러리가 있습니다. 다음을 참조하세요.
REST API 요청/응답의 구성 요소
REST API 요청/응답 쌍을 5개 구성 요소로 구분할 수 있습니다.
{URI-scheme} :// {URI-host} / {resource-path} ? {query-string}으로 구성되는 요청 URI. 대부분의 언어/프레임워크에서 요청 메시지와 별도로 전달해야 하지만 실제로 요청 메시지 헤더에 포함되어 있으므로 여기서는 이를 별도로 호출합니다.- URI 체계: 요청을 전송하는 데 사용되는 프로토콜을 나타냅니다. 예를 들어
http또는https입니다. - URI 호스트: REST 서비스 엔드포인트가 호스트되는 서버의 도메인 이름 또는 IP 주소(예:
graph.microsoft.com - 리소스 경로: 리소스 또는 리소스 컬렉션을 지정합니다. 여기에는 해당 리소스 선택을 결정하는 데 서비스에서 사용하는 여러 세그먼트가 포함될 수 있습니다. 예를 들어:
beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners애플리케이션 컬렉션 내에서 특정 애플리케이션의 소유자 목록을 쿼리하는 데 사용할 수 있습니다. - 쿼리 문자열(선택 사항): API 버전, 리소스 선택 조건 등과 같은 추가 간단한 매개 변수를 제공하는 데 사용됩니다.
- URI 체계: 요청을 전송하는 데 사용되는 프로토콜을 나타냅니다. 예를 들어
- HTTP 요청 메시지 헤더 필드
- 필요한 HTTP 메서드 (작업 또는 동사라고도 함)는 요청하는 작업 유형을 서비스에 알려줍니다. Azure REST API는 GET, HEAD, PUT, POST 및 PATCH 메서드를 지원합니다.
- 지정된 URI 및 HTTP 메서드에 필요한 추가 헤더 필드(선택 사항)입니다. 예를 들어 요청에 대한 클라이언트 권한 부여 정보를 포함하는 전달자 토큰을 제공하는 Authorization 헤더입니다.
- URI 및 HTTP 작업을 지원하는 선택적 HTTP 요청 메시지 본문 필드입니다. 예를 들어 POST 작업에는 복잡한 매개 변수로 전달된 MIME 인코딩 개체가 포함됩니다. POST/PUT 작업의 경우 요청 헤더에도 본문에 대한 MIME 인코딩 형식을 지정
Content-type해야 합니다. 일부 서비스에서는 와 같은application/json특정 MIME 형식을 사용해야 합니다. - HTTP 응답 메시지 헤더 필드
- 2xx 성공 코드에서 4xx/5xx 오류 코드에 이르는 HTTP 상태 코드입니다. 또는 API 설명서에 나와 있는 것처럼 서비스 정의된 상태 코드가 반환될 수 있습니다.
- 요청의 응답을 지원하는 데 필요한 선택적 추가 헤더 필드(예: 응답 헤더)입니다
Content-type.
- 선택적 HTTP 응답 메시지 본문 필드
- MIME로 인코딩된 응답 개체는 데이터를 반환하는 GET 메서드의 응답과 같이 HTTP 응답 본문에 반환될 수 있습니다. 일반적으로 이러한 형식은 응답 헤더에 표시된 대로 JSON 또는 XML로 구조화된 형식으로 반환됩니다
Content-type. 예를 들어 Azure AD 액세스 토큰을 요청할 때 응답 본문에 데이터 컬렉션의 여러 이름/값 쌍을 이루는 개체 중 하나인 요소로access_token반환됩니다. 이 예제에서는 의Content-Type: application/json응답 헤더도 포함됩니다.
- MIME로 인코딩된 응답 개체는 데이터를 반환하는 GET 메서드의 응답과 같이 HTTP 응답 본문에 반환될 수 있습니다. 일반적으로 이러한 형식은 응답 헤더에 표시된 대로 JSON 또는 XML로 구조화된 형식으로 반환됩니다
Azure AD 클라이언트 애플리케이션 등록
대부분의 Azure 서비스(예: Azure Resource Manager 공급자 및 클래식 서비스 관리 API)는 클라이언트 코드가 유효한 자격 증명으로 인증되어야 서비스의 API를 호출할 수 있습니다. 인증은 인증/권한 부여 증명으로 클라이언트에 액세스 토큰을 제공하는 Azure AD 다양한 행위자 간에 조정됩니다. 그런 다음 토큰은 모든 후속 REST API 요청의 HTTP 권한 부여 헤더에서 Azure 서비스로 전송됩니다. 토큰의 클레임 은 서비스에 정보를 제공하여 클라이언트의 유효성을 검사하고 필요한 권한 부여를 수행할 수 있도록 합니다.
통합 Azure AD 인증을 사용하지 않는 REST API를 사용 중이거나 클라이언트를 이미 등록한 경우 요청 만들기 섹션으로 건너뛸 수 있습니다.
사전 요구 사항
클라이언트 애플리케이션은 Azure AD 테넌트에서 등록하여 런타임 전에 Azure AD ID 구성을 알려야 합니다. 다음은 클라이언트를 Azure AD 등록하기 전에 고려해야 할 항목 목록입니다.
- 아직 Azure AD 테넌트가 없는 경우 Azure Active Directory 테넌트를 가져오는 방법을 참조하세요.
- OAuth2 권한 부여 프레임워크에 따라 Azure AD 2가지 유형의 클라이언트를 지원합니다. 각 시나리오를 이해하면 시나리오에 가장 적합한 항목을 결정하는 데 도움이 됩니다.
- 등록 프로세스는 애플리케이션이 등록된 Azure AD 테넌트(애플리케이션 개체 및 서비스 주체 개체)에 2개 관련 개체를 만듭니다. 이러한 구성 요소에 대한 자세한 배경과 런타임에 사용되는 방법에 대한 자세한 내용은 Azure Active Directory의 애플리케이션 및 서비스 주체 개체를 검토하세요.
이제 클라이언트 애플리케이션을 Azure AD 등록할 준비가 되었습니다.
클라이언트 등록
Azure Resource Manager REST API에 액세스할 클라이언트를 등록하려면 포털을 사용하여 단계별 등록 지침에 대한 리소스에 액세스할 수 있는 Active Directory 애플리케이션 및 서비스 주체 만들기를 참조하세요. 이 문서(등록 자동화를 위해 PowerShell 및 CLI 버전에서도 사용 가능)는 다음 방법을 보여 줍니다.
- Azure AD 클라이언트 애플리케이션 등록
- 클라이언트가 Azure Resource Manager API에 액세스할 수 있도록 권한 요청 설정
- 클라이언트에 권한을 부여하기 위한 Azure Resource Manager RBAC(역할 기반 Access Control) 설정 구성
다른 모든 클라이언트의 경우 Azure Active Directory와 애플리케이션 통합을 참조하세요. 이 문서에서 설명하는 방법:
- "애플리케이션 추가" 섹션의 Azure AD 클라이언트 애플리케이션 등록
- "애플리케이션 업데이트" 섹션에서 비밀 키 만들기(웹 클라이언트를 등록하는 경우)
- "애플리케이션 업데이트" 섹션의 API에 필요한 권한 요청 추가
이제 클라이언트 애플리케이션 등록을 완료했으므로 클라이언트 코드로 이동하여 REST 요청을 만들고 응답을 처리할 수 있습니다.
요청 만들기
이 섹션에서는 앞에서 설명한 5개 구성 요소 중 처음 3개에 대해 설명합니다. 먼저 요청 메시지 헤더를 어셈블하는 데 사용할 Azure AD 액세스 토큰을 획득해야 합니다.
액세스 토큰 획득
유효한 클라이언트 등록이 있으면 기본적으로 Azure AD 통합하여 액세스 토큰을 획득하는 두 가지 방법이 있습니다.
- Azure AD 플랫폼/언어 중립적인 OAuth2 서비스 엔드포인트를 사용합니다. 사용 중인 Azure REST API 엔드포인트와 마찬가지로 이 섹션에 제공된 지침은 Azure AD 엔드포인트를 사용할 때 클라이언트의 플랫폼 또는 언어/스크립트에 대해 가정하지 않으며, httpS 요청을 Azure AD 송수신하고 응답 메시지를 구문 분석할 수 있습니다.
- 플랫폼/언어별 MSAL(Microsoft 인증 라이브러리)입니다. 라이브러리는 OAuth2 엔드포인트 요청에 대한 비동기 래퍼와 캐싱 및 새로 고침 토큰 관리와 같은 강력한 토큰 처리 기능을 제공합니다. 참조 설명서, 라이브러리 다운로드 및 샘플 코드를 비롯한 자세한 내용은 Microsoft 인증 라이브러리를 참조하세요.
클라이언트를 인증하고 액세스 토큰을 획득하는 데 사용할 2개의 Azure AD 엔드포인트를 OAuth2 /authorize 및 /token 엔드포인트라고 합니다. 애플리케이션을 사용하는 방법은 애플리케이션의 등록 및 런타임에 애플리케이션을 지원하기 위해 필요한 OAuth2 권한 부여 흐름 유형에 따라 달라집니다. 이 문서의 목적을 위해 클라이언트가 권한 부여 흐름(권한 부여 코드 또는 클라이언트 자격 증명) 중 하나를 사용한다고 가정합니다. 시나리오와 가장 일치하는 지침에 따라 나머지 섹션에서 사용할 액세스 토큰을 획득합니다.
권한 부여 코드 부여(대화형 클라이언트)
이 권한 부여는 웹 및 네이티브 클라이언트 모두에서 사용할 수 있으며, 클라이언트 애플리케이션에 리소스 액세스를 위임하기 위해 로그인한 사용자의 자격 증명이 필요합니다. 엔드포인트를 /authorize 사용하여 권한 부여 코드(사용자 로그인/동의에 대한 응답)를 가져온 다음 /token , 엔드포인트를 사용하여 액세스 토큰에 대한 권한 부여 코드를 교환합니다.
먼저 클라이언트는 Azure AD 권한 부여 코드를 요청해야 합니다. 엔드포인트에 대한 HTTPS GET 요청
/authorize형식 및 요청/응답 메시지 예제에 대한 자세한 내용은 권한 부여 코드 요청을 참조하세요. URI에는 클라이언트 애플리케이션과 관련된 다음을 포함하여 쿼리 문자열 매개 변수가 포함됩니다.client_id- 애플리케이션 ID라고도 하며, 위의 섹션에서 등록할 때 클라이언트 애플리케이션에 할당된 GUID입니다.redirect_uri- 클라이언트 애플리케이션을 등록하는 동안 지정된 회신/리디렉션 URI의 URL로 인코딩된 버전입니다. 전달하는 값은 등록과 정확히 일치해야 합니다.resource- 호출하는 REST API로 지정된 URL로 인코딩된 식별자 URI입니다. 웹/REST API(리소스 애플리케이션이라고도 함)는 구성에서 하나 이상의 애플리케이션 ID URI를 노출할 수 있습니다. 예를 들면 다음과 같습니다.- Azure Resource Manager 공급자(및 클래식 서비스 관리) API 사용
https://management.core.windows.net/ - 다른 리소스는 API 설명서 또는 Azure Portal 리소스 애플리케이션의 구성을 참조하세요. 자세한 내용은 Azure AD 애플리케이션 개체의 속성도
identifierUris참조하세요.
- Azure Resource Manager 공급자(및 클래식 서비스 관리) API 사용
엔드포인트에 대한
/authorize요청은 먼저 최종 사용자를 인증하는 로그인 프롬프트를 트리거합니다. 다시 가져오는 응답은 에서redirect_uri지정한 URI로 리디렉션(302)으로 전달됩니다. 응답 헤더 메시지에는 2단계에 필요한 권한 부여 코드가 포함된 쿼리 매개 변수 뒤에code리디렉션 URI가 포함된 필드가 포함location됩니다.다음으로, 클라이언트는 액세스 토큰에 대한 권한 부여 코드를 사용해야 합니다. 엔드포인트에 대한 HTTPS POST 요청 형식 및 요청/응답 메시지 예제에 대한 자세한 내용은 권한 부여 코드를 사용하여 액세스 토큰 요청을
/token참조하세요. POST 요청이므로 이번에는 요청 본문에 애플리케이션별 매개 변수를 패키지합니다. 위에서 언급한 일부 항목 외에도(다른 새 항목과 함께) 을 전달합니다.code- 1단계에서 얻은 권한 부여 코드를 포함하는 쿼리 매개 변수입니다.client_secret- 클라이언트가 웹 애플리케이션으로 구성된 경우에만 이 매개 변수가 필요합니다. 이는 클라이언트 등록에서 이전에 생성한 것과 동일한 비밀/키 값입니다.
클라이언트 자격 증명 부여(비대화형 클라이언트)
이 권한 부여는 웹 클라이언트에서만 사용할 수 있으므로 애플리케이션은 등록 시 제공되는 클라이언트의 자격 증명을 사용하여 리소스에 직접 액세스할 수 있습니다(사용자 위임 없음). 일반적으로 디먼/서비스로 실행되는 비대화형 클라이언트(UI 없음)에서 사용되며 액세스 토큰을 획득하려면 엔드포인트만 /token 필요합니다.
이 권한 부여에 대한 클라이언트/리소스 상호 작용은 권한 부여 코드 부여의 2단계와 매우 유사합니다. 엔드포인트에 대한 HTTPS POST 요청 형식 및 요청/응답 메시지 예제에 대한 자세한 내용은 클라이언트 자격 증명을 사용하여 서비스 간 호출 의 "액세스 토큰 요청" 섹션을 /token 참조하세요.
요청 메시지 어셈블
대부분의 프로그래밍 언어/프레임워크 및 스크립팅 환경을 사용하면 요청 메시지를 쉽게 어셈블하고 보낼 수 있습니다. 일반적으로 요청의 생성/서식을 추상화하는 웹/HTTP 클래스 또는 API를 제공하여 클라이언트 코드를 더 쉽게 작성할 수 있습니다(예: .NET Framework HttpWebRequest 클래스). 간결하게 하기 위해 이 중 대부분이 자동으로 처리된다는 점을 감안할 때 요청의 중요한 요소만 다룹니다.
요청 URI
모든 보안 REST 요청에는 중요한 정보가 전송/수신되므로 요청 및 응답에 보안 채널을 제공하는 URI 체계에 대한 HTTPS 프로토콜이 필요합니다. 이 정보(예: Azure AD 권한 부여 코드, 액세스/전달자 토큰, 중요한 요청/응답 데이터)는 낮은 전송 계층으로 암호화되어 메시지의 개인 정보를 보호합니다.
서비스의 나머지 요청 URI(호스트, 리소스 경로 및 필요한 쿼리 문자열 매개 변수)는 관련 REST API 사양에 따라 결정됩니다. 예를 들어 Azure Resource Manager 공급자 API는 를 사용하고 https://management.azure.com/클래식 Azure Service Management API는 를 사용합니다https://management.core.windows.net/. 둘 다 쿼리 문자열 매개 변수가 필요합니다api-version.
요청 헤더
요청 URI는 서비스의 REST API 사양 및 HTTP 사양에 따라 결정되는 추가 필드와 함께 요청 메시지 헤더에 번들로 제공됩니다. 다음은 요청에 필요할 수 있는 몇 가지 일반적인 헤더 필드입니다.
Authorization: Azure AD 이전에 획득한 대로 요청을 보호하기 위한 OAuth2 전달자 토큰을 포함합니다.Content-Type: 일반적으로 "application/json"(JSON 형식의 이름/값 쌍)으로 설정되고 요청 본문의 MIME 형식을 지정합니다.Host: REST 서비스 엔드포인트가 호스트되는 서버의 도메인 이름 또는 IP 주소입니다.
요청 본문
앞에서 설명한 것처럼 요청 메시지 본문은 요청하는 특정 작업 및 해당 매개 변수 요구 사항에 따라 선택 사항입니다. 필요한 경우 요청하는 서비스의 API 사양도 인코딩 및 형식을 지정합니다.
요청 본문은 헤더에서 빈 줄로 구분되며 헤더 필드별로 서식을 Content-Type 지정해야 합니다. "application/json" 형식 본문의 예는 다음과 같이 표시됩니다.
{
"<name>": "<value>"
}
요청 보내기
이제 서비스의 요청 URI가 있고 관련 요청 메시지 헤더/본문을 만들었으므로 REST 서비스 엔드포인트에 요청을 보낼 준비가 되었습니다.
예를 들어 Azure Resource Manager 공급자에 대한 HTTPS GET 요청 메서드는 다음과 유사한 요청 헤더 필드를 사용하여 전송될 수 있지만 요청 본문은 비어 있습니다.
GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com
<no body>
Azure Resource Manager 공급자에 대한 HTTPS PUT 요청 메서드는 다음과 유사한 요청 헤더 AND 본문 필드를 사용하여 전송될 수 있습니다.
PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourcegroups/ExampleResourceGroup?api-version=2016-02-01 HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com
{
"location": "West US"
}
요청을 수행하면 응답 메시지 헤더 및 선택적 본문이 반환됩니다.
응답 메시지 처리
이제 5개 구성 요소 중 마지막 2개까지 완료하겠습니다.
응답을 처리하려면 응답 헤더와 필요에 따라 응답 본문을 구문 분석해야 합니다(요청에 따라). 위에 제공된 HTTPS GET 예제에서는 /subscriptions 엔드포인트를 사용하여 사용자의 구독 목록을 검색했습니다. 응답이 성공했다고 가정하면 다음과 유사한 응답 헤더 필드를 받아야 합니다.
HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;
및 응답 본문은 다음과 유사하게 JSON 형식으로 인코딩된 Azure 구독 및 해당 개별 속성 목록을 포함합니다.
{
"value":[
{
"id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
"subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
"displayName":"My Azure Subscription",
"state":"Enabled",
"subscriptionPolicies":{
"locationPlacementId":"Public_2015-09-01",
"quotaId":"MSDN_2014-05-01",
"spendingLimit":"On"}
}
]
}
마찬가지로 HTTPS PUT 예제의 경우 다음과 유사한 응답 헤더를 수신하여 "ExampleResourceGroup"을 추가하는 PUT 작업이 성공했는지 확인해야 합니다.
HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;
및 응답 본문은 다음과 유사하게 JSON 형식으로 인코딩된 새로 추가된 리소스 그룹의 콘텐츠를 확인합니다.
{
"id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
"name":"ExampleResourceGroup",
"location":"westus",
"properties":
{
"provisioningState":"Succeeded"
}
}
요청과 마찬가지로 대부분의 프로그래밍 언어/프레임워크를 사용하면 응답 메시지를 쉽게 처리할 수 있습니다. 일반적으로 요청 후 애플리케이션에 이 정보를 반환하므로 형식화된/구조화된 형식으로 처리할 수 있습니다. 주로 응답 헤더에서 HTTP 상태 코드를 확인하고, 숨은 경우 API 사양(또는 Content-Type 및 Content-Length 응답 헤더 필드)에 따라 응답 본문을 구문 분석하는 데 관심이 있습니다.
이것으로 끝입니다. Azure AD 애플리케이션을 등록하고 액세스 토큰을 획득하고 HTTP 요청을 만들고 처리하기 위한 구성 요소화된 기술이 있으면 코드를 복제하여 새 REST API를 활용하는 것이 매우 쉽습니다.
관련 콘텐츠
- HowTo 및 QuickStart 문서의 포괄적인 인덱스 및 샘플 코드를 포함하여 애플리케이션 등록 및 Azure AD 프로그래밍 모델에 대한 자세한 내용은 Microsoft ID 플랫폼(개발자용 Azure Active Directory)를 참조하세요.
- HTTP 요청/응답을 테스트하려면 검사.
이 문서 다음에 오는 LiveFyre 주석 섹션을 사용하여 피드백을 제공하고 콘텐츠를 구체화하고 구체화하는 데 도움을 주세요.