Udostępnij za pośrednictwem

Omówienie publicznego interfejsu API Azure Sphere

  • Artykuł

Publiczny interfejs API Azure Sphere to zestaw punktów końcowych usługi, które obsługują operacje HTTP w zakresie tworzenia zasobów usługi Azure Sphere i zarządzania nimi, takich jak dzierżawy, produkty, wdrożenia i grupy urządzeń. Publiczny interfejs API Azure Sphere używa protokołu HTTP REST (REpresentational State Transfer) do wysyłania żądań operacji i odpowiedzi. Dane zwrócone w odpowiedzi operacji są sformatowane w formacie JSON (Notacja obiektu JavaScript). Dostępne operacje są opisane w dokumentacji publicznego interfejsu API Azure Sphere.

Klienci mogą preferować używanie interfejsu wiersza polecenia Azure Sphere (CLI) zamiast publicznego interfejsu API do wykonywania zadań zarządzania zasobami. Cli upraszcza wysyłanie i odbieranie żądań operacji i odpowiedzi poprzez abstrakcję dużej złożoności programowej publicznego interfejsu API. Polecenia cli używają publicznego interfejsu API Azure Sphere do wykonywania zadań, ale prosta składnia poleceń cli ułatwiają korzystanie z nich.

Niektórzy klienci mogą zechcieć utworzyć własny interfejs użytkownika w celu wykonywania zadań zarządzania zasobami. Za pomocą publicznego interfejsu API Azure Sphere można utworzyć niestandardowy interfejs użytkownika. Nie można utworzyć niestandardowego interfejsu użytkownika za pomocą interfejsu użytkownika Azure Sphere CLI.

Składniki żądania interfejsu API REST

Żądanie interfejsu API REST ma następujące trzy składniki:

  1. Identyfikator URI żądania w następującej formie:

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

    Parametry:

    • kolekcja: co najmniej jedna kolekcja. Obsługiwane są wiele kolekcji zagnieżdżonych, więc ścieżki względne mogą zawierać /collection/id/collection/id ...

      Przykład: /v2/tenants/{tenantId}/devices/{deviceId}/images

    • identyfikator zasobu: identyfikator określonego zasobu, który umożliwia dostęp do określonych zasobów w kolekcji.

      Przykład: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}

    • wersja: Wersja interfejsu API, która identyfikuje wersję interfejsu API. Każde żądanie interfejsu API powinno zawierać wersję interfejsu API, aby uniknąć przerwania aplikacji lub usługi w miarę rozwoju interfejsów API.

      Przykład: /v2

  2. Pola nagłówka wiadomości żądania HTTP:

    • Wymagana metoda HTTP (nazywana również operacją lub czasownikiem), która informuje usługę, jakiego typu operacji żądasz.
    • Dodatkowe pola nagłówków, zgodnie z wymaganiami określonymi metodami URI i HTTP. W szczególności nagłówek autoryzacji, który zapewnia token na okaziciela zawierający token autoryzacji klienta dla żądania.

  3. Opcjonalne pola treści żądania HTTP do obsługi operacji URI i HTTP.

    • W przypadku operacji HTTP POST lub PUT treść powinna być określona w nagłówku żądania typu zawartości, a także w aplikacji/json.

Składniki odpowiedzi interfejsu API REST

Odpowiedź interfejsu API REST obejmuje następujące dwa składniki:

  1. Pola nagłówka wiadomości odpowiedzi HTTP:

  2. Opcjonalne pola treści wiadomości odpowiedzi HTTP:

    • Obiekty odpowiedzi zakodowane w formacie MIME mogą być zwracane w treści odpowiedzi HTTP, na przykład w odpowiedzi z metody GET zwracającej dane. Te obiekty są zawsze zwracane w ustrukturyzowanym formacie JSON, co wskazuje nagłówek odpowiedzi Typ zawartości.

Uwierzytelnianie żądania

Zanim będzie można złożyć prawidłowe żądanie, aplikacja lub usługa muszą zostać uwierzytelnione za pomocą publicznego interfejsu API Azure Sphere. W poniższej tabeli przedstawiono niektóre sposoby uwierzytelniania.

Typ aplikacji Opis Przykład Mechanizm uwierzytelniania
Interakcyjna strona klienta Aplikacja po stronie klienta oparta na interfejsie użytkownika Aplikacje systemu Windows wyliczające urządzenia Biblioteka uwierzytelniania firmy Microsoft (MSAL)
Interakcyjny javascript Aplikacja javascript oparta na interfejsie GRAFICZNYm Pojedyncza aplikacja AngularJS wyświetla wdrożenia dla grupy urządzeń. MSAL
Interakcyjna sieć Web Aplikacja sieci Web oparta na interfejsie użytkownika Niestandardowy pulpit nawigacyjny sieci Web z wyświetlonymi podsumowaniami kompilacji OAuth 2

Uwaga

Platforma Azure Active Directory przekształca się w platformę tożsamości firmy Microsoft. Aby uzyskać więcej informacji, zobacz Co nowego w usłudze Azure Sphere.

Wartości biblioteki uwierzytelniania

Jeśli nawiążesz połączenie z bibliotekami uwierzytelniania firmy Microsoft (MSAL) w celu uzyskania tokenu na okaziciela w celu uwierzytelniania, musisz podać cztery wartości:

  • Identyfikator aplikacji klienckiej Azure Sphere: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (wymagane do pomyślnego uwierzytelniania)
  • Zakres dla użytkownika: https://sphere.azure.net/api/user_impersonation
  • Identyfikator dzierżawy usługi Azure Sphere: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
  • Punkt końcowy interfejsu API Azure Sphere: https://prod.core.sphere.azure.net/

Aby uzyskać więcej informacji na temat uwierzytelniania, zobacz Biblioteka uwierzytelniania firmy Microsoft (MSAL) i przepływy uwierzytelniania.

Zdejmij wniosek

Po uwierzytelnieniu w usłudze Azure Sphere możesz składać żądania i odbierać odpowiedzi.

W poniższym przykładzie języka C# do złożenia żądania użyto klasy 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
}

Odbieranie odpowiedzi

Każde wywołanie zwraca odpowiedź JSON w następującym formacie:

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

Kody błędów publicznego interfejsu API Azure Sphere

Publiczny interfejs API Azure Sphere zwraca następujące kody błędów:

  • 400 - Zły wniosek
  • 404 - Nie znaleziono
  • 409 - Konflikt
  • 410 - Zniknął
  • 429 - Zbyt wiele wniosków
  • 500 — Wewnętrzny błąd serwera

Wskazówki dotyczące obsługi błędów podano w poniższej sekcji. Aby uzyskać szczegółowe informacje na temat konkretnych kodów błędów, zobacz RFC 7231.

Wskazówki dotyczące obsługi błędów

Błędy 4xx: Nieprawidłowo sformatowane żądania mogą prowadzić do błędów. Sprawdź składnię żądania i przekazywane dane.

429 błędów: Aby chronić usługi Azure Sphere przed rozproszonymi atakami typu "odmowa usługi" (DDoS), śledzimy i ograniczamy urządzenia, użytkowników lub dzierżawy, które napełniają dużą liczbą połączeń do naszych usług. Komunikat o błędzie 429 wskazuje, że urządzenie, użytkownik lub dzierżawa zbyt wiele razy próbowało zadzwonić do usługi Azure Sphere w krótkim czasie. Poczekaj na ponowne wywołanie usługi Azure Sphere.

500 błędów: Czasami mogą wystąpić przejściowe błędy serwera. Jeśli zostanie wyświetlony błąd serwera, spróbuj ponownie kilka razy, aby sprawdzić, czy błąd zniknie.

Pomoc techniczna cors

Udostępnianie pochodzenia między regionami (CORS) nie jest obsługiwane w tej wersji.

Zawartość pokrewna