Поделиться через

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

  • Статья

Внимание

Это документация по Azure Sphere (устаревшая версия). Служба Azure Sphere (устаревшая версия) выходит на пенсию 27 сентября 2027 г., и к этому времени пользователи должны перейти в Azure Sphere (интегрированная). Используйте селектор версий, расположенный над toC, чтобы просмотреть документацию по Azure Sphere (интегрированная).

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

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

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

Компоненты запроса REST API

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

  1. URI запроса в следующей форме:

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

    Параметры:

    • коллекция: одна или несколько коллекций. Поддерживаются несколько вложенных коллекций, поэтому относительные пути могут включать в себя /collection/id/collection/id ...

      Пример: /v2/tenants/{tenantId}/devices/{deviceId}/images

    • resourceId: идентификатор определенного ресурса, который обеспечивает доступ к определенным ресурсам в коллекции.

      Пример: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}

    • версия: версия API, которая определяет версию API. Каждый запрос API должен включать версию API, чтобы избежать разрыва приложения или службы по мере развития API.

      Пример: /v2

  2. Поля заголовка сообщения HTTP-запроса:

    • Обязательный метод HTTP (также известный как операция или команда), который сообщает службе, какой тип операции запрашивается.
    • Дополнительные поля заголовка, необходимые указанному методу URI и HTTP. В частности, заголовок авторизации, предоставляющий маркер носителя, содержащий маркер авторизации клиента для запроса.

  3. Необязательные поля текста сообщения HTTP-запроса для поддержки операции URI и HTTP.

    • Для операций HTTP POST или PUT текст должен быть указан в заголовке запроса типа контента, а также в приложении или json.

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

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

  1. Поля заголовка сообщения ответа HTTP:

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

  2. Необязательные поля текста сообщения ответа HTTP:

    • Объекты ответа в кодировке MIME могут быть возвращены в тексте ответа HTTP, например ответ метода GET, возвращающего данные. Эти объекты всегда возвращаются в структурированном формате JSON, как указано в заголовке ответа Content-Type.

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

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

Тип приложения Description Пример Механизм аутентификации
Интерактивная клиентская сторона Клиентское клиентское приложение на основе графического интерфейса Перечисление устройств с приложением 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) не поддерживается в этом выпуске.

См. также