Обзор общедоступного API Azure Sphere

Статья
08/09/2023

Общедоступный API Azure Sphere — это набор конечных точек служб, которые поддерживают операции HTTP для создания ресурсов Azure Sphere и управления ими, таких как клиенты, продукты, развертывания и группы устройств. Общедоступный API Azure Sphere использует протокол HTTP REST (REpresentational State Transfer) для отправки запросов и ответов на операции. Данные, возвращаемые в ответе операции, форматируются в формате JSON (нотация объектов JavaScript). Доступные операции описаны в справочнике по общедоступному API Azure Sphere.

Клиенты могут использовать интерфейс командной строки (CLI) Azure Sphere вместо общедоступного API для выполнения задач по управлению ресурсами. Интерфейс командной строки упрощает отправку и получение запросов и ответов на операции, абстрагируя большую часть программной сложности общедоступного API. Команды CLI используют общедоступный API Azure Sphere для выполнения задач, но простой синтаксис команд CLI значительно упрощает их использование.

Некоторые клиенты могут захотеть создать собственный пользовательский интерфейс для выполнения задач управления ресурсами. Общедоступный API Azure Sphere можно использовать для создания пользовательского интерфейса. Создать пользовательский интерфейс с помощью Azure Sphere CLI невозможно.

Компоненты запроса 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— идентификатор определенного ресурса, который обеспечивает доступ к определенным ресурсам в коллекции.
  
  Примере: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}
- version: версия API, которая определяет версию API. Каждый запрос API должен содержать версию API, чтобы избежать прерывания работы приложения или службы по мере развития API.
  
  Примере: /v2
Поля заголовка сообщения HTTP-запроса:
- Обязательный метод HTTP (также известный как операция или глагол), который сообщает службе, какой тип операции вы запрашиваете.
- Дополнительные поля заголовка, необходимые для указанных URI и метода HTTP. В частности, заголовок авторизации, который предоставляет токен носителя, содержащий маркер авторизации клиента для запроса.
Необязательные поля текста сообщения HTTP-запроса для поддержки URI и операции HTTP.
- Для операций HTTP POST или PUT текст должен быть указан в заголовке запроса Content-Type, а также в приложении или json.

Компоненты ответа REST API

Ответ REST API состоит из следующих двух компонентов:

Поля заголовка сообщения ответа HTTP:
- Код состояния HTTP. Успешные вызовы возвращают коды 2xx; Коды 4xx и 5xx — это состояния ошибок. Дополнительные сведения см. в разделе Коды ошибок общедоступного API Azure Sphere . Кроме того, можно вернуть код состояния, определенный службой, как указано в справочнике по общедоступному API Azure Sphere.
- Необязательные дополнительные поля заголовка, необходимые для поддержки ответа на запрос, например заголовок ответа типа контента.
Необязательные поля текста сообщения ответа HTTP:
- Объекты ответа в кодировке MIME могут возвращаться в тексте ответа HTTP, например ответ из метода GET, возвращающего данные. Эти объекты всегда возвращаются в структурированном формате JSON, как указано в заголовке ответа Content-Type.

Проверка подлинности запроса

Перед выполнением действительного запроса приложение или служба должны пройти проверку подлинности с помощью общедоступного API Azure Sphere. В следующей таблице показаны некоторые из способов проверки подлинности.

Тип приложения	Описание	Примере	Механизм проверки подлинности
Интерактивная клиентская сторона	Клиентское приложение на основе графического интерфейса пользователя	Перечисление устройств в приложении Windows	Библиотека проверки подлинности Майкрософт (MSAL)
Интерактивный JavaScript	Приложение JavaScript на основе графического интерфейса пользователя	Одностраничное приложение AngularJS, отображающее развертывания для группы устройств.	MSAL
Интерактивный веб-сайт	Веб-приложение на основе графического интерфейса пользователя	Настраиваемая веб-панель мониторинга, отображающая сводки по сборке	OAuth 2

Примечание

Платформа Azure Active Directory превращается в платформу удостоверений Майкрософт. Дополнительные сведения см . в статье Новые возможности Azure Sphere.

Значения библиотеки проверки подлинности

При вызове библиотек проверки подлинности Майкрософт (MSAL) для получения маркера носителя для проверки подлинности необходимо указать четыре значения:

Идентификатор клиентского приложения Azure Sphere: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (требуется для успешной проверки подлинности)
Область для пользователя: https://sphere.azure.net/api/user_impersonation
Идентификатор клиента Azure Sphere: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
Конечная точка API Azure Sphere: https://prod.core.sphere.azure.net/

Дополнительные сведения о проверке подлинности см. в статье Библиотека проверки подлинности Майкрософт (MSAL) и Потоки проверки подлинности.

Создание запроса

После проверки подлинности в 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}]

Коды ошибок общедоступного API Azure Sphere

Общедоступный API Azure Sphere возвращает следующие коды ошибок:

400 — недопустимый запрос
404 — не найдено
409 — конфликт
410 — Ушло
429 — слишком много запросов
500 — внутренняя ошибка сервера

Инструкции по обработке ошибок приведены в следующем разделе. Подробные сведения о конкретных кодах ошибок см. в статье RFC 7231.

Руководство по обработке ошибок

Ошибки 4xx: Неправильно сформированные запросы могут привести к ошибкам. Проверьте синтаксис запроса и передаваемые данные.

Ошибки 429: Чтобы защитить службы Azure Sphere от распределенных атак типа "отказ в обслуживании" (DDoS), мы отслеживаем и регулируем устройства, пользователей или клиентов, которые делают большое количество вызовов к нашим службам. Сообщение об ошибке 429 указывает, что устройство, пользователь или клиент пытались вызвать службу Azure Sphere слишком много раз в течение короткого периода времени. Подождите, прежде чем снова вызвать службу Azure Sphere.

500 ошибок: Иногда могут возникать временные ошибки сервера. Если возникает ошибка сервера, повторите запрос несколько раз, чтобы узнать, исчезнет ли ошибка.

Поддержка CORS

В этом выпуске не поддерживается общий доступ к источникам между регионами (CORS).