Azure Sphere 공용 API 개요

아티클
08/09/2023

Azure Sphere 공용 API는 테넌트, 제품, 배포 및 디바이스 그룹과 같은 Azure Sphere 리소스를 만들고 관리하기 위한 HTTP 작업을 지원하는 서비스 엔드포인트 집합입니다. Azure Sphere 공용 API는 REST(REpresentational State Transfer) HTTP 프로토콜을 사용하여 작업 요청 및 응답을 보냅니다. 작업 응답에서 반환된 데이터는 JSON(JavaScript 개체 표기법)으로 형식이 지정됩니다. 사용 가능한 작업은 Azure Sphere 공용 API 참조에 설명되어 있습니다.

고객은 공용 API 대신 Azure Sphere CLI(명령줄 인터페이스 )를 사용하여 리소스 관리 작업을 수행하는 것을 선호할 수 있습니다. CLI는 공용 API의 프로그래밍 방식 복잡성을 대부분 추상화하여 작업 요청 및 응답의 송수신을 간소화합니다. CLI 명령은 Azure Sphere 공용 API를 사용하여 작업을 수행하지만 CLI 명령의 간단한 구문을 사용하면 훨씬 쉽게 사용할 수 있습니다.

일부 고객은 리소스 관리 작업을 수행하기 위해 자체 UI(사용자 인터페이스)를 빌드하려고 할 수 있습니다. Azure Sphere 공용 API를 사용하여 사용자 지정 UI를 빌드할 수 있습니다. Azure Sphere CLI를 사용하여 사용자 지정 UI를 빌드할 수 없습니다.

REST API 요청의 구성 요소

REST API 요청에는 다음과 같은 세 가지 구성 요소가 있습니다.

다음 형식의 요청 URI입니다.

VERB https://prod.core.sphere.azure.net/v{version}/{collection}/{id}…[{resourceId} | {collection}]

매개 변수:
- collection: 하나 이상의 컬렉션입니다. 여러 중첩된 컬렉션이 지원되므로 상대 경로에는 /collection/id/collection/id...가 포함될 수 있습니다.
  
  예제: /v2/tenants/{tenantId}/devices/{deviceId}/images
- resourceId: 컬렉션 내의 특정 리소스에 액세스할 수 있는 특정 리소스의 ID입니다.
  
  예제: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}
- version: API 버전을 식별하는 API 버전입니다. 모든 API 요청에는 API가 발전함에 따라 앱 또는 서비스가 중단되지 않도록 api 버전이 포함되어야 합니다.
  
  예제: /v2
HTTP 요청 메시지 헤더 필드:
- 필요한 HTTP 메서드 (작업 또는 동사라고도 함)는 요청하는 작업의 유형을 서비스에 알려줍니다.
- 지정된 URI 및 HTTP 메서드에 필요한 추가 헤더 필드입니다. 특히 요청에 대한 클라이언트 권한 부여 토큰을 포함하는 전달자 토큰을 제공하는 권한 부여 헤더입니다.
URI 및 HTTP 작업을 지원하는 선택적 HTTP 요청 메시지 본문 필드입니다.
- HTTP POST 또는 PUT 작업의 경우 본문을 Content-Type 요청 헤더와 application/json에 지정해야 합니다.

REST API 응답의 구성 요소

REST API 응답에는 다음 두 가지 구성 요소가 있습니다.

HTTP 응답 메시지 헤더 필드:
- HTTP 상태 코드입니다. 성공한 호출은 2xx 코드를 반환합니다. 4xx 및 5xx 코드는 오류 상태입니다. 자세한 내용은 Azure Sphere 공용 API 오류 코드 섹션을 참조하세요. 또는 Azure Sphere 공용 API 참조에 지정된 대로 서비스 정의 상태 코드가 반환될 수 있습니다.
- 콘텐츠 형식 응답 헤더와 같이 요청에 대한 응답을 지원하는 데 필요한 추가 헤더 필드(선택 사항)입니다.
선택적 HTTP 응답 메시지 본문 필드:
- MIME로 인코딩된 응답 개체는 데이터를 반환하는 GET 메서드의 응답과 같이 HTTP 응답 본문에 반환될 수 있습니다. 이러한 개체는 Content-Type 응답 헤더에 표시된 대로 항상 구조화된 JSON 형식으로 반환됩니다.

요청 인증

유효한 요청을 만들려면 먼저 Azure Sphere 공용 API를 사용하여 애플리케이션 또는 서비스를 인증해야 합니다. 다음 표에서는 인증할 수 있는 몇 가지 방법을 보여줍니다.

애플리케이션 유형	설명	예제	인증 메커니즘
대화형 클라이언트 쪽	GUI 기반 클라이언트 쪽 애플리케이션	디바이스를 열거하는 Windows 앱	MSAL(Microsoft 인증 라이브러리)
대화형 JavaScript	GUI 기반 JavaScript 애플리케이션	디바이스 그룹에 대한 배포를 표시하는 AngularJS 단일 페이지 앱입니다.	MSAL
대화형 웹	GUI 기반 웹 애플리케이션	빌드 요약을 표시하는 사용자 지정 웹 dashboard	OAuth 2

참고

Azure Active Directory 플랫폼 은 Microsoft ID 플랫폼으로 발전하고 있습니다. 자세한 내용은 Azure Sphere의 새로운 기능 을 참조하세요.

인증 라이브러리 값

MSAL(Microsoft 인증 라이브러리)을 호출하여 인증에 사용할 전달자 토큰을 획득하는 경우 다음 네 가지 값을 제공해야 합니다.

Azure Sphere 클라이언트 애플리케이션 ID: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (성공적인 인증에 필요)
사용자 범위: https://sphere.azure.net/api/user_impersonation
Azure Sphere 테넌트 ID: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
Azure Sphere API 엔드포인트: https://prod.core.sphere.azure.net/

인증에 대한 자세한 내용은 MSAL(Microsoft 인증 라이브러리) 및 인증 흐름을 참조하세요.

요청 만들기

Azure Sphere를 사용하여 인증한 후 요청을 수행하고 응답을 받을 수 있습니다.

다음 C# 예제에서는 HttpClient 클래스 를 사용하여 요청을 수행합니다.

namespace SpherePublicAPISample
{
    using System;
    using System.Collections.Generic;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Threading;
    using System.Threading.Tasks;
    // You install the Microsoft.Identity.Client reference by using Nuget,
    // starting at https://www.nuget.org/packages/Microsoft.Identity.Client.
    // Follow the instructions to install using Package Manager.
    using Microsoft.Identity.Client;

    class Program
    {
        // Azure Sphere Public API resource URI
        private readonly List<string> Scopes = new List<string>() { "https://sphere.azure.net/api/user_impersonation" };

        // Azure Sphere Public API client application ID.
        private const string ClientApplicationId = "0b1c8f7e-28d2-4378-97e2-7d7d63f7c87f";

        // Azure Sphere Tenant ID.
        public const string Tenant = "7d71c83c-ccdf-45b7-b3c9-9c41b94406d9";

        // Azure Sphere Public API URI
        private static readonly Uri AzureSphereApiUri = new Uri("https://prod.core.sphere.azure.net/");

        // Program entry-point.
        // returns Zero on success, otherwise non-zero.
        private static int Main()
        {
            try
            {
                CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();

                Program program = new Program();

                program.ExecuteAsync(cancellationTokenSource.Token)
                    .GetAwaiter()
                    .GetResult();

                Console.ReadLine();
            }
            catch (Exception ex)
            {
                Console.Error.WriteLine(ex.ToString());
                return -1;
            }
            return 0;
        } // end of main

        private async Task ExecuteAsync(CancellationToken cancellationToken)
        {
            IPublicClientApplication publicClientApp = PublicClientApplicationBuilder
                .Create(ClientApplicationId)
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .WithRedirectUri("http://localhost")
                .Build();

            AuthenticationResult authResult = await publicClientApp.AcquireTokenInteractive(Scopes)
                .ExecuteAsync();

            string accessToken = authResult.AccessToken;

            // Call the Azure Sphere API to get tenants available to the authenticated user.
            string result = await GetAsync(accessToken, "v2/tenants", cancellationToken);

            Console.WriteLine(result);
        } // end of ExecuteAsync method

        private async Task<string> GetAsync(string accessToken, string relativeUrl, CancellationToken cancellationToken)
        {
            using (HttpClient client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

                Uri uri = new Uri(AzureSphereApiUri, relativeUrl);

                using (HttpResponseMessage response = await client.GetAsync(uri, cancellationToken))
                {
                    response.EnsureSuccessStatusCode();
                    return await response.Content.ReadAsStringAsync();
                }
            }
        } // end of GetAsync method

    } // end of class Program
}

응답 받기

각 호출은 다음 형식으로 JSON 응답을 반환합니다.

[{"Id":"{tenantId}","Name":"Contoso","Roles":null}]

Azure Sphere 공용 API 오류 코드

Azure Sphere 공용 API는 다음 오류 코드를 반환합니다.

400 - 잘못된 요청
404 - 찾을 수 없음
409 - 충돌
410 - 사라지다
429 - 요청이 너무 많음
500 - 내부 서버 오류

오류 처리에 대한 지침은 다음 섹션에서 제공합니다. 특정 오류 코드에 대한 자세한 내용은 RFC 7231을 참조하세요.

오류 처리 지침

4xx 오류: 잘못된 형식의 요청으로 인해 오류가 발생할 수 있습니다. 요청 구문과 전달되는 데이터를 확인합니다.

429 오류: DDoS(분산 서비스 거부) 공격으로부터 Azure Sphere 서비스를 보호하기 위해 서비스에 대해 많은 수의 호출을 하는 디바이스, 사용자 또는 테넌트를 추적하고 제한합니다. 429 오류 메시지는 디바이스, 사용자 또는 테넌트가 짧은 기간 내에 Azure Sphere 서비스를 너무 많이 호출하려고 했음을 나타냅니다. Azure Sphere 서비스를 다시 호출하기 전에 기다려 주세요.

500 오류: 경우에 따라 일시적인 서버 오류가 발생할 수 있습니다. 서버 오류가 발생하면 요청을 몇 번 다시 시도하여 오류가 사라지는지 확인합니다.

CORS 지원

CORS(지역 간 원본 공유)는 이 릴리스에서 지원되지 않습니다.