Sdílet prostřednictvím


Přehled veřejného rozhraní API Azure Sphere

Důležité

Toto je dokumentace k Azure Sphere (starší verze). Azure Sphere (starší verze) se vyřazuje 27. září 2027 a uživatelé musí do této doby migrovat do Azure Sphere (integrované). K zobrazení dokumentace k Azure Sphere (integrované) použijte selektor verzí umístěný nad obsahem.

Veřejné rozhraní API Azure Sphere je sada koncových bodů služby, které podporují operace HTTP pro vytváření a správu prostředků Azure Sphere, jako jsou tenanti, produkty, nasazení a skupiny zařízení. Veřejné rozhraní API Azure Sphere používá k odesílání požadavků na operace a odpovědi protokol HTTP REST (REpresentational State Transfer). Data vrácená v odpovědi operace jsou naformátovaná ve formátu JSON (JavaScript Object Notation). Dostupné operace jsou popsané v referenčních informacích k veřejnému rozhraní API Azure Sphere.

Zákazníci můžou raději používat rozhraní příkazového řádku Azure Sphere místo veřejného rozhraní API k provádění úloh správy prostředků. Rozhraní příkazového řádku zjednodušuje odesílání a přijímání požadavků na operace a odpovědi abstrakcí velké programové složitosti veřejného rozhraní API. Příkazy rozhraní příkazového řádku používají k provádění úloh veřejné rozhraní API Azure Sphere, ale jednoduchá syntaxe příkazů rozhraní příkazového řádku usnadňuje jejich používání.

Někteří zákazníci můžou chtít vytvořit vlastní uživatelské rozhraní pro provádění úloh správy prostředků. Veřejné rozhraní API Azure Sphere se dá použít k vytvoření vlastního uživatelského rozhraní. Pomocí rozhraní příkazového řádku Azure Sphere není možné vytvořit vlastní uživatelské rozhraní.

Komponenty požadavku rozhraní REST API

Požadavek rozhraní REST API má následující tři komponenty:

  1. Identifikátor URI požadavku v následujícím formátu:

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

    Parametry:

    • kolekce: Jedna nebo více kolekcí. Podporuje se více vnořených kolekcí, takže relativní cesty mohou zahrnovat /collection/id/collection/id ...

      Příklad: /v2/tenants/{tenantId}/devices/{deviceId}/images

    • resourceId: ID konkrétního prostředku, které umožňuje přístup k určitým prostředkům v rámci kolekce.

      Příklad: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}

    • verze: Verze rozhraní API, která identifikuje verzi rozhraní API. Každý požadavek rozhraní API by měl obsahovat verzi rozhraní API, aby se zabránilo přerušení vaší aplikace nebo služby při vývoji rozhraní API.

      Příklad: /v2

  2. Pole hlavičky zprávy požadavku HTTP:

    • Požadovaná metoda HTTP (označovaná také jako operace nebo příkaz), která službě říká, jaký typ operace požadujete.
    • Další pole hlaviček vyžadovaná zadaným identifikátorem URI a metodou HTTP. Konkrétně autorizační hlavička, která poskytuje nosný token obsahující autorizační token klienta pro požadavek.
  3. Volitelná pole textu zprávy požadavku HTTP pro podporu identifikátoru URI a operace HTTP.

    • V případě operací HTTP POST nebo PUT by se text měl zadat v hlavičce požadavku Content-Type a také v souboru application/json.

Komponenty odpovědi rozhraní REST API

Odpověď rozhraní REST API má následující dvě komponenty:

  1. Pole hlavičky zprávy HTTP:

    • Stavový kód HTTP. Úspěšná volání vrací kódy 2xx; Kódy 4xx a 5xx jsou stavy chyb – podrobnosti najdete v části Kódy chyb veřejného rozhraní API Azure Sphere. Případně může být vrácen stavový kód definovaný službou, jak je uvedeno v referenčních informacích k veřejnému rozhraní API Azure Sphere.
    • Volitelná další pole hlaviček, která jsou potřebná pro podporu odpovědi na požadavek, například hlavičku odpovědi typu obsahu.
  2. Volitelná pole textu zprávy HTTP:

    • Objekty odpovědi kódované mime mohou být vráceny v těle odpovědi HTTP, například odpověď z metody GET, která vrací data. Tyto objekty se vždy vrátí ve strukturovaném formátu JSON, jak je uvedeno v hlavičce odpovědi Content-Type.

Ověření žádosti

Než budete moct provést platný požadavek, musí se vaše aplikace nebo služba ověřit pomocí veřejného rozhraní API Azure Sphere. Následující tabulka uvádí některé způsoby, jak se můžete ověřit.

Typ aplikace Popis Příklad Mechanismus ověřování
Interaktivní klient na straně Klientská aplikace založená na grafickém uživatelském rozhraní Výčet zařízení pro aplikace pro Windows Microsoft Authentication Library (MSAL)
Interaktivní JavaScript JavaScriptová aplikace založená na grafickém uživatelském rozhraní Jednostráňová aplikace AngularJS zobrazující nasazení pro skupinu zařízení MSAL
Interaktivní web Webová aplikace založená na grafickém uživatelském rozhraní Vlastní webový řídicí panel zobrazující souhrny sestavení OAuth 2

Poznámka:

Platforma Azure Active Directory se vyvíjí na platformu Microsoft Identity Platform. Další informace najdete v tématu Co je nového v Azure Sphere.

Hodnoty knihovny ověřování

Pokud zavoláte knihovnu MSAL (Microsoft Authentication Library), abyste získali nosný token, který se má použít k ověřování, musíte zadat čtyři hodnoty:

  • ID klientské aplikace Azure Sphere: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (vyžaduje se pro úspěšné ověření)
  • Rozsah pro uživatele: https://sphere.azure.net/api/user_impersonation
  • ID tenanta Azure Sphere: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
  • Koncový bod rozhraní API Azure Sphere: https://prod.core.sphere.azure.net/

Další informace o ověřování naleznete v tématu Microsoft Authentication Library (MSAL) a toky ověřování.

Vytvoření požadavku

Po ověření pomocí Azure Sphere můžete provádět žádosti a přijímat odpovědi.

Následující příklad jazyka C# používá třídu HttpClient k vytvoření požadavku.

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
}

Přijetí odpovědi

Každé volání vrátí odpověď JSON v následujícím formátu:

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

Kódy chyb veřejného rozhraní API Azure Sphere

Veřejné rozhraní API Azure Sphere vrátí následující kódy chyb:

  • 400 – Chybný požadavek
  • 404 – Nenalezeno
  • 409 – Konflikt
  • 410 - Pryč
  • 429 – Příliš mnoho požadavků
  • 500 – Vnitřní chyba serveru

Pokyny pro zpracování chyb najdete v následující části. Podrobné informace o konkrétních kódech chyb najdete v dokumentu RFC 7231.

Pokyny pro zpracování chyb

Chyby 4xx: Chybné požadavky můžou vést k chybám. Zkontrolujte syntaxi požadavku a předávaná data.

Chyby 429: Abychom ochránili služby Azure Sphere před distribuovanými útoky na dostupnost služby (DDoS), sledujeme a omezujeme zařízení, uživatele nebo tenanty, které do našich služeb zadávají velký počet volání. Chybová zpráva 429 značí, že se zařízení, uživatel nebo tenant pokusili volat službu Azure Sphere příliš mnohokrát během krátkého časového období. Počkejte prosím, než znovu zavoláte službu Azure Sphere.

Chyby 500: Občas může dojít k přechodným chybám serveru. Pokud se zobrazí chyba serveru, zkuste požadavek několikrát zopakovat, abyste zjistili, jestli chyba zmizí.

Podpora sdílení prostředků mezi zdroji (CORS)

Sdílení zdrojů mezi oblastmi (CORS) není v této verzi podporované.