Omówienie publicznego interfejsu API usługi Azure Sphere

Artykuł
11/05/2024

Ważne

Jest to dokumentacja usługi Azure Sphere (starsza wersja). Usługa Azure Sphere (starsza wersja) zostanie wycofana 27 września 2027 r., a użytkownicy muszą przeprowadzić migrację do usługi Azure Sphere (zintegrowanej) do tej pory. Użyj selektora wersji znajdującego się powyżej spisu treści, aby wyświetlić dokumentację usługi Azure Sphere (zintegrowaną).

Publiczny interfejs API usługi Azure Sphere to zestaw punktów końcowych usługi, które obsługują operacje HTTP na potrzeby tworzenia zasobów usługi Azure Sphere, takich jak dzierżawy, produkty, wdrożenia i grupy urządzeń. Publiczny interfejs API usługi 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ą formatowane w formacie JSON (JavaScript Object Notation). Dostępne operacje są udokumentowane w dokumentacji publicznego interfejsu API usługi Azure Sphere.

Klienci mogą wolisz używać interfejsu wiersza polecenia usługi Azure Sphere zamiast publicznego interfejsu API do wykonywania zadań zarządzania zasobami. Interfejs wiersza polecenia upraszcza wysyłanie i odbieranie żądań operacji i odpowiedzi, abstrakując znaczną część programowej złożoności publicznego interfejsu API. Polecenia interfejsu wiersza polecenia używają publicznego interfejsu API usługi Azure Sphere do wykonywania zadań, ale prosta składnia poleceń interfejsu wiersza polecenia znacznie ułatwia korzystanie z nich.

Niektórzy klienci mogą chcieć utworzyć własny interfejs użytkownika w celu wykonywania zadań związanych z zarządzaniem zasobami. Publiczny interfejs API usługi Azure Sphere może służyć do tworzenia niestandardowego interfejsu użytkownika. Nie można utworzyć niestandardowego interfejsu użytkownika za pomocą interfejsu wiersza polecenia usługi Azure Sphere.

Składniki żądania interfejsu API REST

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

Identyfikator URI żądania w następującym formularzu:

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

Parametry:
- kolekcja: co najmniej jedna kolekcja. Obsługiwane są wiele zagnieżdżonych kolekcji, więc ścieżki względne mogą obejmować /collection/id/collection/id ...
  
  Przykład: /v2/tenants/{tenantId}/devices/{deviceId}/images
- resourceId: identyfikator określonego zasobu, który umożliwia dostęp do określonych zasobów w kolekcji.
  
  Przykład: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}
- version: wersja interfejsu API, która identyfikuje wersję interfejsu API. Każde żądanie interfejsu API powinno zawierać wersję interfejsu API, aby uniknąć awarii aplikacji lub usługi w miarę rozwoju interfejsów API.
  
  Przykład: /v2
Pola nagłówka komunikatu żądania HTTP:
- Wymagana metoda HTTP (nazywana również operacją lub zleceniem), która informuje usługę o żądanym typie operacji.
- Dodatkowe pola nagłówka wymagane przez określony identyfikator URI i metodę HTTP. W szczególności nagłówek autoryzacji, który zawiera token elementu nośnego zawierający token autoryzacji klienta dla żądania.
Opcjonalne pola treści komunikatu żądania HTTP do obsługi identyfikatora URI i operacji HTTP.
- W przypadku operacji HTTP POST lub PUT treść powinna być określona w nagłówku żądania Content-Type, a także w pliku application/json.

Składniki odpowiedzi interfejsu API REST

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

Pola nagłówka komunikatu odpowiedzi HTTP:
- Kod stanu HTTP. Pomyślne wywołania zwracają kody 2xx; Kody 4xx i 5xx są stanami błędów — zobacz sekcję Kody błędów publicznego interfejsu API usługi Azure Sphere, aby uzyskać szczegółowe informacje. Alternatywnie może zostać zwrócony kod stanu zdefiniowany przez usługę, jak określono w dokumentacji publicznego interfejsu API usługi Azure Sphere.
- Opcjonalne dodatkowe pola nagłówka zgodnie z wymaganiami w celu obsługi odpowiedzi na żądanie, takie jak nagłówek odpowiedzi Typu zawartości.
Opcjonalne pola treści komunikatu odpowiedzi HTTP:
- Obiekty odpowiedzi zakodowane w formacie MIME mogą być zwracane w treści odpowiedzi HTTP, takie jak odpowiedź z metody GET zwracającej dane. Te obiekty są zawsze zwracane w formacie JSON ze strukturą, zgodnie z nagłówkiem odpowiedzi Content-Type.

Uwierzytelnianie żądania

Aby można było wysłać prawidłowe żądanie, aplikacja lub usługa musi zostać uwierzytelniona za pomocą publicznego interfejsu API usługi Azure Sphere. W poniższej tabeli przedstawiono niektóre sposoby uwierzytelniania.

Typ aplikacji	opis	Przykład	Mechanizm uwierzytelniania
Interaktywna strona klienta	Aplikacja po stronie klienta oparta na graficznym interfejsie użytkownika	Wyliczanie urządzeń przez aplikację systemu Windows	Biblioteka Microsoft Authentication Library (MSAL)
Interaktywny kod JavaScript	Aplikacja JavaScript oparta na graficznym interfejsie użytkownika	Aplikacja jednostronicowa AngularJS wyświetla wdrożenia dla grupy urządzeń.	BIBLIOTEKA MSAL
Interaktywna sieć Web	Aplikacja internetowa oparta na graficznym interfejsie użytkownika	Niestandardowy pulpit nawigacyjny sieci Web wyświetlający podsumowania kompilacji	OAuth 2

Uwaga

Platforma Azure Active Directory ewoluuje w platformę Microsoft Identity. Aby uzyskać więcej informacji, zobacz Co nowego w usłudze Azure Sphere.

Wartości biblioteki uwierzytelniania

Jeśli wywołasz biblioteki uwierzytelniania firmy Microsoft (MSAL) w celu uzyskania tokenu elementu nośnego do użycia do uwierzytelniania, musisz podać cztery wartości:

Identyfikator aplikacji klienckiej usługi Azure Sphere: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (wymagany do pomyślnego uwierzytelnienia)
Zakres 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 usługi Azure Sphere: https://prod.core.sphere.azure.net/

Aby uzyskać więcej informacji na temat uwierzytelniania, zobacz Przepływy biblioteki Microsoft Authentication Library (MSAL) i uwierzytelniania.

Wysyłanie żądania

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

Poniższy przykład w języku C# używa klasy HttpClient do wykonania żądania.

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 usługi Azure Sphere

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

400 — Nieprawidłowe żądanie
404 — Nie odnaleziono
409 — Konflikt
410 — Zniknął
429 — zbyt wiele żądań
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 określonych kodów błędów, zobacz RFC 7231.

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

Błędy 4xx: Źle sformułowane żądania mogą prowadzić do błędów. Sprawdź składnię żądania i przekazywane dane.

Błędy 429: Aby chronić usługi Azure Sphere przed atakami typu "rozproszona odmowa usługi" (DDoS), śledzimy i ograniczamy urządzenia, użytkowników lub dzierżawy, które tworzą dużą liczbę wywołań do naszych usług. Komunikat o błędzie 429 wskazuje, że urządzenie, użytkownik lub dzierżawa próbowało wywołać usługę Azure Sphere zbyt wiele razy w krótkim czasie. Zaczekaj, zanim ponownie wywołasz usługę Azure Sphere.

Błędy 500: Czasami mogą wystąpić przejściowe błędy serwera. Jeśli wystąpi błąd serwera, spróbuj ponownie wykonać żądanie kilka razy, aby sprawdzić, czy błąd zniknie.

Obsługa mechanizmu CORS

Udostępnianie źródła między regionami (CORS) nie jest obsługiwane w tej wersji.

Udostępnij za pośrednictwem

Omówienie publicznego interfejsu API usługi Azure Sphere

Składniki żądania interfejsu API REST

Składniki odpowiedzi interfejsu API REST

Uwierzytelnianie żądania

Wartości biblioteki uwierzytelniania

Wysyłanie żądania

Odbieranie odpowiedzi

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

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

Obsługa mechanizmu CORS

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Omówienie publicznego interfejsu API usługi Azure Sphere

Składniki żądania interfejsu API REST

Składniki odpowiedzi interfejsu API REST

Uwierzytelnianie żądania

Wartości biblioteki uwierzytelniania

Wysyłanie żądania

Odbieranie odpowiedzi

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

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

Obsługa mechanizmu CORS

Powiązana zawartość

Opinia

Dodatkowe zasoby