다음을 통해 공유


Azure REST API 참조

Azure REST API 참조 설명서를 시작합니다.

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

  • curl을 사용하여 Azure REST API를 호출하는 방법
  • REST API 요청/응답 쌍의 기본 구성 요소입니다.
  • REST 요청을 보호하기 위해 Microsoft Entra ID 클라이언트 애플리케이션을 등록하는 방법입니다.
  • REST 요청을 만들고 보내고 응답을 처리하는 방법에 대한 개요입니다.

대부분의 Azure 서비스 REST API에는 Azure 서비스를 사용하기 위한 네이티브 인터페이스를 제공하는 클라이언트 라이브러리가 있습니다.

.Net | Java | | Node.js파이썬 | 이동 | C + +

curl을 사용하여 Azure REST API를 호출하는 방법

다음 블로그 게시물에 설명된 프로세스는 curl을 사용하여 Azure REST API를 호출하는 방법을 보여 줍니다. 무인 스크립트에서 curl을 사용하는 것이 좋습니다. 예를 들어 DevOps 자동화 시나리오에서.

curl을 통해 Azure REST API 호출

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

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

  1. {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}으로 구성되는 요청 URI. 요청 URI는 요청 메시지 헤더에 포함되어 있지만, 대부분 언어 또는 프레임워크는 요청 메시지에서 이를 별도로 전달해야 하기 때문에 여기에서는 별도로 분류합니다.

    • URI 체계: 요청을 전송하는 데 사용되는 프로토콜을 나타냅니다. 예를 들어 http 또는 https입니다.
    • URI 호스트: graph.microsoft.com과 같이 REST 서비스 엔드포인트가 호스팅되는 서버의 도메인 이름 또는 IP 주소를 지정합니다.
    • 리소스 경로: 리소스 또는 해당 리소스 선택을 결정하는 데 서비스에서 사용되는 여러 세그먼트를 포함할 수 있는 리소스 컬렉션을 지정합니다. 예를 들어: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners 애플리케이션 컬렉션 내에서 특정 애플리케이션의 소유자 목록을 쿼리하는 데 사용할 수 있습니다.
    • 쿼리 문자열(선택 사항): API 버전 또는 리소스 선택 조건과 같은 추가적인 단순 매개 변수를 제공합니다.
  2. HTTP 요청 메시지 헤더 필드:

    • 필요한 HTTP 메서드 (작업 또는 동사라고도 함)는 요청하는 작업의 유형을 서비스에 알려줍니다. Azure REST API는 GET, HEAD, PUT, POST 및 PATCH 메서드를 지원합니다.
    • 지정된 URI 및 HTTP 메서드에서 필요로 하는 선택적 추가 헤더 필드입니다. 예를 들어 요청에 대한 클라이언트 권한 부여 정보를 포함하는 전달자 토큰을 제공하는 권한 부여 헤더입니다.
  3. URI 및 HTTP 작업을 지원하는 선택적 HTTP 요청 메시지 본문 필드입니다. 예를 들어 POST 작업은 복잡한 매개 변수로 전달되는 MIME 인코딩된 개체를 포함합니다. POST 또는 PUT 작업의 경우 Content-type 요청 헤더에서도 본문에 대한 MIME 인코딩 형식을 지정해야 합니다. 일부 서비스에서는 application/json과 같은 특정 MIME 형식을 사용해야 합니다.

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

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

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

클라이언트 애플리케이션을 Microsoft Entra ID 등록

대부분의 Azure 서비스(예: Azure Resource Manager 공급자 및 클래식 배포 모델)는 서비스의 API를 호출하기 전에 클라이언트 코드가 유효한 자격 증명으로 인증되어야 합니다. 인증은 Microsoft Entra ID 다양한 행위자 간에 조정되며 클라이언트에 인증 증명으로 액세스 토큰을 제공합니다. 그런 다음 토큰은 후속 REST API 요청의 HTTP 권한 부여 헤더에서 Azure 서비스로 전송됩니다. 토큰의 클레임 은 서비스에 정보를 제공하여 클라이언트의 유효성을 검사하고 필요한 권한 부여를 수행할 수 있도록 합니다.

통합 Microsoft Entra 인증을 사용하지 않는 REST API를 사용하거나 클라이언트를 이미 등록한 경우 요청 만들기 섹션으로 건너뜁니다.

사전 요구 사항

클라이언트 애플리케이션은 Microsoft Entra 테넌트에서 등록하여 런타임 전에 id 구성을 Microsoft Entra ID 알려야 합니다. 클라이언트를 Microsoft Entra ID 등록하기 전에 다음 필수 조건을 고려하세요.

  • 아직 Microsoft Entra 테넌트가 없는 경우 Microsoft Entra 테넌트 설정을 참조하세요.

  • OAuth2 권한 부여 프레임워크에 따라 Microsoft Entra ID 두 가지 유형의 클라이언트를 지원합니다. 각각을 이해하면 시나리오에 가장 적합한 항목을 결정하는 데 도움이 됩니다.

    • 웹/기밀 클라이언트는 웹 서버에서 실행되며 자체 ID(예: 서비스 또는 디먼)로 리소스에 액세스하거나, 로그인한 사용자의 ID(예: 웹앱)로 리소스에 액세스하기 위한 위임된 권한 부여를 얻을 수 있습니다. 웹 클라이언트만 액세스 토큰을 획득하기 위해 Microsoft Entra 인증 중에 자체 자격 증명을 안전하게 유지 관리하고 표시할 수 있습니다.
    • 네이티브/퍼블릭 클라이언트가 설치되어 디바이스에서 실행됩니다. 로그인한 사용자의 ID를 사용하여 사용자를 대신하여 액세스 토큰을 획득하는 위임된 권한 부여에 따라 리소스에만 액세스할 수 있습니다.
  • 등록 프로세스는 애플리케이션이 등록된 Microsoft Entra 테넌트에서 애플리케이션 개체와 서비스 주체 개체라는 두 개의 관련 개체를 만듭니다. 이러한 구성 요소 및 런타임에 사용되는 방법에 대한 자세한 배경 정보는 Microsoft Entra ID 애플리케이션 및 서비스 주체 개체를 참조하세요.

이제 클라이언트 애플리케이션을 Microsoft Entra ID 등록할 준비가 되었습니다.

클라이언트 등록

Azure Resource Manager REST API에 액세스하는 클라이언트를 등록하려면 포털을 사용하여 리소스에 액세스할 수 있는 Microsoft Entra 애플리케이션 및 서비스 주체 만들기를 참조하세요. 이 문서(등록 자동화를 위해 PowerShell 및 CLI 버전에서도 사용 가능)는 다음 방법을 보여 줍니다.

  • Microsoft Entra ID 클라이언트 애플리케이션을 등록합니다.
  • 클라이언트가 Azure Resource Manager API에 액세스할 수 있도록 권한 요청을 설정합니다.
  • 클라이언트에 권한을 부여하기 위한 AZURE RBAC(Resource Manager Role-Based Access Control) 설정을 구성합니다.

클라이언트가 Azure Resource Manager API 이외의 API에 액세스하는 경우 다음을 참조하세요.

이제 클라이언트 애플리케이션 등록을 완료했으므로 REST 요청을 만들고 응답을 처리하는 클라이언트 코드로 이동합니다.

요청 만들기

이 섹션에서는 앞에서 설명한 5개 구성 요소 중 처음 3개에 대해 설명합니다. 먼저 요청 메시지 헤더를 어셈블하는 데 사용하는 Microsoft Entra ID 액세스 토큰을 획득해야 합니다.

액세스 토큰 획득

유효한 클라이언트 등록이 완료되면 Microsoft Entra ID 통합하여 액세스 토큰을 획득하는 두 가지 방법이 있습니다.

  • 이 문서에서 사용하는 플랫폼 및 언어 중립적 OAuth2 서비스 엔드포인트. 이 섹션에 제공된 지침에서는 Microsoft Entra OAuth 엔드포인트를 사용할 때 클라이언트의 플랫폼 또는 언어/스크립트에 대해 아무 것도 가정하지 않습니다. 유일한 요구 사항은 httpS 요청을 Microsoft Entra ID 송수신하고 응답 메시지를 구문 분석할 수 있다는 것입니다.
  • 플랫폼 및 언어별 MSAL(Microsoft 인증 라이브러리)은 이 문서의 scope. 라이브러리는 OAuth2 엔드포인트 요청에 대한 비동기 래퍼와 캐싱 및 새로 고침 토큰 관리와 같은 강력한 토큰 처리 기능을 제공합니다. 자세한 내용은 MSAL(Microsoft 인증 라이브러리) 개요를 참조하세요.

클라이언트를 인증하고 액세스 토큰을 획득하는 데 사용하는 두 개의 Microsoft Entra 엔드포인트를 OAuth2 /authorize/token 엔드포인트라고 합니다. 사용 방법은 애플리케이션의 등록 및 런타임에 애플리케이션을 지원하는 데 필요한 OAuth2 권한 부여 흐름 유형에 따라 달라집니다. 이 문서의 목적을 위해 클라이언트는 권한 부여 코드 또는 클라이언트 자격 증명과 같은 권한 부여 흐름 중 하나를 사용한다고 가정합니다. 나머지 섹션에서 사용되는 액세스 토큰을 가져오려면 시나리오와 가장 일치하는 흐름에 대한 지침을 따릅니다.

권한 부여 코드 부여(대화형 클라이언트)

이 권한 부여는 웹 및 네이티브 클라이언트 모두에서 사용되며, 클라이언트 애플리케이션에 대한 리소스 액세스를 위임하기 위해 로그인한 사용자의 자격 증명이 필요합니다. 엔드포인트를 /authorize 사용하여 사용자 로그인/동의에 대한 응답으로 권한 부여 코드를 가져온 다음 /token 엔드포인트를 사용하여 액세스 토큰에 대한 권한 부여 코드를 교환합니다.

  1. 먼저 클라이언트가 Microsoft Entra ID 권한 부여 코드를 요청해야 합니다. 엔드포인트에 대한 HTTPS GET 요청 /authorize 형식과 요청/응답 메시지 예제에 대한 자세한 내용은 권한 부여 코드 요청을 참조하세요. URI에는 클라이언트 애플리케이션과 관련된 다음 쿼리 문자열 매개 변수가 포함됩니다.

    • client_id: 등록하는 동안 클라이언트 애플리케이션에 할당된 GUID(애플리케이션 ID라고도 함).

    • 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 리소스 애플리케이션의 구성을 참조하세요. 자세한 내용은 Microsoft Graph API 애플리케이션 개체의 속성을 참조 identifierUris 하세요.

    엔드포인트에 대한 /authorize 요청은 먼저 사용자를 인증하는 로그인 프롬프트를 트리거합니다. 다시 가져오는 응답은 에서 redirect_uri지정한 URI로 리디렉션(302)으로 전달됩니다. 응답 헤더 메시지에는 리디렉션 URI와 쿼리 매개 변수가 포함된 필드가 포함되어 location 있습니다 code . 매개 변수에는 code 2단계에 필요한 권한 부여 코드가 포함되어 있습니다.

  2. 다음으로, 클라이언트는 액세스 토큰에 대한 권한 부여 코드를 사용해야 합니다. 엔드포인트에 대한 HTTPS POST 요청 /token 형식 및 요청/응답 예제에 대한 자세한 내용은 액세스 토큰 요청을 참조하세요. POST 요청이므로 요청 본문에 애플리케이션별 매개 변수를 패키지합니다. 앞에서 언급한 매개 변수 중 일부 외에도(다른 새 매개 변수와 함께) 다음을 전달합니다.

    • code: 이 쿼리 매개 변수에는 1단계에서 얻은 권한 부여 코드가 포함되어 있습니다.

    • client_secret: 클라이언트가 웹 애플리케이션으로 구성된 경우에만 이 매개 변수가 필요합니다. 이는 클라이언트 등록에서 이전에 생성한 것과 동일한 비밀/키 값입니다.

클라이언트 자격 증명 부여(비대화형 클라이언트)

이 권한 부여는 웹 클라이언트에서만 사용되므로 애플리케이션이 등록 시 제공되는 클라이언트의 자격 증명을 사용하여 리소스에 직접 액세스할 수 있습니다(사용자 위임 없음). 권한 부여는 일반적으로 서비스 또는 디먼으로 실행되는 비대화형 클라이언트(UI 없음)에서 사용됩니다. 액세스 토큰을 /token 획득하려면 엔드포인트만 필요합니다.

이 권한 부여에 대한 클라이언트/리소스 상호 작용은 권한 부여 코드 부여의 2단계와 유사합니다. 엔드포인트에 대한 HTTPS POST 요청 /token 형식 및 요청/응답 예제에 대한 자세한 내용은 Microsoft ID 플랫폼 "토큰 가져오기" 섹션 및 OAuth 2.0 클라이언트 자격 증명 흐름을 참조하세요.

요청 메시지 어셈블

대부분의 프로그래밍 언어 또는 프레임워크 및 스크립팅 환경을 사용하면 요청 메시지를 쉽게 어셈블하고 보낼 수 있습니다. 일반적으로 요청의 생성 또는 서식을 추상화하는 웹/HTTP 클래스 또는 API를 제공하므로 클라이언트 코드(HttpWebRequest예: .NET Framework 클래스)를 더 쉽게 작성할 수 있습니다. 간결하게 하기 위해 대부분의 작업이 자동으로 처리되므로 이 섹션에서는 요청의 중요한 요소만 다룹니다.

요청 URI

중요한 정보가 전송되고 수신되기 때문에 모든 REST 요청에는 URI 체계에 대한 HTTPS 프로토콜이 필요하므로 요청 및 응답에 보안 채널이 제공됩니다. 정보(즉, Microsoft Entra 권한 부여 코드, 액세스/전달자 토큰 및 중요한 요청/응답 데이터)는 낮은 전송 계층으로 암호화되어 메시지의 개인 정보를 보호합니다.

서비스의 나머지 요청 URI(호스트, 리소스 경로 및 필요한 쿼리 문자열 매개 변수)는 관련 REST API 사양에 따라 결정됩니다. 예를 들어 Azure Resource Manager 공급자 API는 를 사용하고 https://management.azure.com/Azure 클래식 배포 모델은 를 사용합니다https://management.core.windows.net/. 둘 다 쿼리 문자열 매개 변수가 api-version 필요합니다.

요청 헤더

요청 URI는 서비스의 REST API 사양 및 HTTP 사양에 필요한 추가 필드와 함께 요청 메시지 헤더에 번들로 제공됩니다. 요청에는 다음과 같은 일반적인 헤더 필드가 필요할 수 있습니다.

  • Authorization: Microsoft Entra ID 이전에 획득한 대로 요청을 보호하기 위한 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 요청 메서드를 보낼 수 있습니다.

PUT /subscriptions/.../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개 구성 요소 중 마지막 두 가지로 끝납니다.

응답을 처리하려면 응답 헤더와 필요에 따라 응답 본문을 구문 분석합니다(요청에 따라 다름). 이전 섹션에서 제공된 HTTPS GET 예제에서 /subscriptions 엔드포인트를 사용하여 사용자의 구독 목록을 검색했습니다. 응답이 성공했다고 가정하면 다음 예제와 유사한 응답 헤더 필드를 받아야 합니다.

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

또한 다음과 같이 Azure 구독 목록과 JSON 형식으로 인코딩된 개별 속성이 포함된 응답 본문을 받아야 합니다.

{
    "value":[
        {
        "id":"/subscriptions/...",
        "subscriptionId":"...",
        "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/.../resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

요청과 마찬가지로 대부분의 프로그래밍 언어 및 프레임워크를 사용하면 응답 메시지를 쉽게 처리할 수 있습니다. 일반적으로 요청 후 애플리케이션에 이 정보를 반환하므로 형식화된/구조화된 형식으로 처리할 수 있습니다. 주로 응답 헤더에서 HTTP 상태 코드를 확인하고 API 사양(또는 Content-TypeContent-Length 응답 헤더 필드)에 따라 응답 본문을 구문 분석하는 데 관심이 있습니다.

비동기 작업, 제한 및 페이징

이 문서에서 설명하는 Create/Send/Process-Response 패턴은 동기적이며 모든 REST 메시지에 적용됩니다. 그러나 일부 서비스는 비동기 패턴을 지원하므로 비동기 요청을 모니터링하거나 완료하기 위해 응답 헤더를 추가로 처리해야 합니다. 자세한 내용은 Azure 비동기 작업 추적을 참조하세요.

Resource Manager 애플리케이션이 너무 많은 요청을 보내지 못하도록 시간당 읽기 및 쓰기 요청 수에 제한을 적용합니다. 애플리케이션이 이러한 제한을 초과하면 요청이 제한됩니다. 응답 헤더에는 scope 대한 나머지 요청 수가 포함됩니다. 자세한 내용은 Resource Manager 요청 제한을 참조하세요.

일부 목록 작업은 응답 본문에 라는 nextLink 속성을 반환합니다. 결과가 너무 커서 한 응답에서 반환할 수 없는 경우 이 속성이 표시됩니다. 일반적으로 응답에는 목록 작업이 1,000개 이상의 항목을 반환할 때 nextLink 속성이 포함됩니다. nextLink가 결과에 없으면 반환된 결과가 완료됩니다. nextLink에 URL이 포함된 경우 반환된 결과는 총 결과 집합의 일부일 뿐입니다.

응답 형식은 다음과 같습니다.

{
  "value": [
    <returned-items>
  ],
  "nextLink": "https://management.azure.com/{operation}?api-version={version}&%24skiptoken={token}"
}

결과의 다음 페이지를 가져오려면 nextLink 속성의 URL에 GET 요청을 보냅니다. URL에는 결과에 있는 위치를 나타내는 연속 토큰이 포함됩니다. 반환된 결과에 URL이 더 이상 포함되지 않을 때까지 nextLink URL로 요청을 계속 보냅니다.

Azure API의 복원력

Azure REST API는 복원력 및 지속적인 가용성을 위해 설계되었습니다. REST API의 컨트롤 플레인 작업(management.azure.com 전송된 요청)은 다음과 같습니다.

  • 지역별로 분산됩니다 일부 서비스는 지역적입니다.

  • 여러 가용성 영역이 있는 위치에서 가용성 영역(지역도 포함)으로 분산됩니다.

  • 단일 논리 데이터 센터에 종속되지 않습니다.

  • 유지 관리 작업을 위해 다운되지 않습니다.

정말 간단하죠. Microsoft Entra 애플리케이션을 등록하고 액세스 토큰을 획득하고 HTTP 요청을 처리하는 모듈식 기술을 갖은 후에는 코드를 복제하여 새 REST API를 활용하는 것이 매우 쉽습니다. 애플리케이션 등록 및 Microsoft Entra 프로그래밍 모델에 대한 자세한 내용은 Microsoft ID 플랫폼 설명서를 참조하세요.

HTTP 요청/응답 테스트에 대한 자세한 내용은 다음을 참조하세요.

  • Fiddler. Fiddler는 REST 요청을 가로챌 수 있는 무료 웹 디버깅 프록시로, HTTP 요청/응답 메시지를 쉽게 진단할 수 있도록 합니다.
  • JWT.ms 전달자 토큰에 클레임을 빠르고 쉽게 덤프하여 콘텐츠의 유효성을 검사할 수 있습니다.