Dela via

Översikt över det offentliga API:et för Azure Sphere

  • Artikel

Viktigt!

Det här är dokumentationen om Azure Sphere (Legacy). Azure Sphere (Legacy) upphör den 27 september 2027 och användarna måste migrera till Azure Sphere (integrerad) vid den här tiden. Använd versionsväljaren ovanför TOC för att visa dokumentationen om Azure Sphere (integrerad).

Det offentliga API:et för Azure Sphere är en uppsättning tjänstslutpunkter som stöder HTTP-åtgärder för att skapa och hantera Azure Sphere-resurser som klientorganisationer, produkter, distributioner och enhetsgrupper. Det offentliga API:et för Azure Sphere använder HTTP-protokollet REST (REpresentational State Transfer) för att skicka åtgärdsbegäranden och svar. De data som returneras i åtgärdssvaret formateras i JSON (JavaScript Object Notation). De tillgängliga åtgärderna dokumenteras i den offentliga API-referensen för Azure Sphere.

Kunder kanske föredrar att använda Azure Sphere-kommandoradsgränssnittet (CLI) i stället för det offentliga API:et för att utföra resurshanteringsuppgifter. CLI förenklar sändning och mottagning av åtgärdsbegäranden och svar genom att abstrahera mycket av den programmatiska komplexiteten i det offentliga API:et. CLI-kommandona använder det offentliga API:et för Azure Sphere för att utföra uppgifter, men den enkla syntaxen för CLI-kommandona gör dem mycket enklare att använda.

Vissa kunder kanske vill skapa ett eget användargränssnitt (UI) för att utföra resurshanteringsuppgifter. Det offentliga API:et för Azure Sphere kan användas för att skapa ett anpassat användargränssnitt. Det går inte att skapa ett anpassat användargränssnitt med Azure Sphere CLI.

Komponenter i en REST API-begäran

En REST API-begäran har följande tre komponenter:

  1. Begärande-URI:n i följande form:

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

    Parametrar:

    • samling: En eller flera samlingar. Flera kapslade samlingar stöds, så relativa sökvägar kan innehålla /collection/id/collection/id ...

      Exempel: /v2/tenants/{tenantId}/devices/{deviceId}/images

    • resourceId: ID:t för en specifik resurs, som ger åtkomst till specifika resurser i en samling.

      Exempel: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}

    • version: API-versionen, som identifierar versionen av API:et. Varje API-begäran bör innehålla en API-version för att undvika att din app eller tjänst avbryts när API:erna utvecklas.

      Exempel: /v2

  2. Meddelandehuvudfält för HTTP-begäran:

    • En nödvändig HTTP-metod (kallas även en åtgärd eller ett verb), som talar om för tjänsten vilken typ av åtgärd du begär.
    • Ytterligare rubrikfält, enligt vad som krävs av den angivna URI- och HTTP-metoden. Mer specifikt ett auktoriseringshuvud som tillhandahåller en ägartoken som innehåller klientauktoriseringstoken för begäran.

  3. Valfria meddelandetextfält för HTTP-begäran för att stödja URI- och HTTP-åtgärden.

    • För HTTP POST- eller PUT-åtgärder ska brödtexten anges i begärandehuvudet för innehållstyp samt application/json.

Komponenter i ett REST API-svar

Ett REST API-svar har följande två komponenter:

  1. FÄLT för HTTP-svarsmeddelanderubrik:

    • En HTTP-statuskod. Lyckade anrop returnerar 2xx-koder; 4xx- och 5xx-koder är felstatusar – mer information finns i avsnittet om offentliga API-felkoder i Azure Sphere. Alternativt kan en tjänstdefinierad statuskod returneras, enligt vad som anges i den offentliga API-referensen för Azure Sphere.
    • Valfria ytterligare rubrikfält som krävs för att stödja svaret på begäran, till exempel ett innehållstypsvarshuvud.

  2. Valfria brödtextfält för HTTP-svarsmeddelande:

    • MIME-kodade svarsobjekt kan returneras i HTTP-svarstexten, till exempel ett svar från en GET-metod som returnerar data. Dessa objekt returneras alltid i ett strukturerat JSON-format, enligt beskrivningen i svarshuvudet Innehållstyp.

Autentisering av en begäran

Innan du kan göra en giltig begäran måste ditt program eller din tjänst autentiseras med det offentliga API:et för Azure Sphere. I följande tabell visas några av de sätt som du kan autentisera.

Typ av program beskrivning Exempel Autentiseringsmekanism
Interaktiv klientsida GUI-baserat program på klientsidan Windows-appuppräkningsenheter Microsoft Authentication Library (MSAL)
Interaktiv JavaScript GUI-baserat JavaScript-program AngularJS-ensidesapp som visar distributioner för en enhetsgrupp. MSAL
Interaktiv webb GUI-baserad webbapp Anpassad webbinstrumentpanel som visar kompileringssammanfattningar OAuth 2

Kommentar

Azure Active Directory-plattformen utvecklas till Microsoft Identity-plattformen. Mer information finns i Nyheter i Azure Sphere.

Autentiseringsbiblioteksvärden

Om du anropar Microsoft Authentication Libraries (MSAL) för att hämta en ägartoken som ska användas för autentisering måste du ange fyra värden:

  • Azure Sphere-klientprogram-ID: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (krävs för lyckad autentisering)
  • Omfång för användaren: https://sphere.azure.net/api/user_impersonation
  • Klient-ID för Azure Sphere: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
  • Azure Sphere API-slutpunkt: https://prod.core.sphere.azure.net/

Mer information om autentisering finns i Microsoft Authentication Library (MSAL) och autentiseringsflöden.

Skapa en begäran

När du har autentiserats med Azure Sphere kan du göra begäranden och ta emot svar.

I följande C#-exempel används klassen HttpClient för att göra en begäran.

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
}

Ta emot ett svar

Varje anrop returnerar ett JSON-svar i följande format:

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

Felkoder för offentligt API för Azure Sphere

Det offentliga API:et för Azure Sphere returnerar följande felkoder:

  • 400 – felaktig begäran
  • 404 - Hittades inte
  • 409 – konflikt
  • 410 - Borta
  • 429 – För många begäranden
  • 500 – Internt serverfel

Vägledning för hantering av fel finns i följande avsnitt. Detaljerad information om specifika felkoder finns i RFC 7231.

Vägledning för felhantering

4xx-fel: Felaktiga begäranden kan leda till fel. Kontrollera din syntax för begäran och de data som skickas.

429 fel: För att skydda Azure Sphere-tjänster mot DDoS-attacker (Distribuerad överbelastning) spårar och begränsar vi enheter, användare eller klienter som gör ett stort antal anrop till våra tjänster. Ett 429-felmeddelande anger att enheten, användaren eller klienten försökte anropa Azure Sphere-tjänsten för många gånger inom en kort tidsperiod. Vänta innan du anropar Azure Sphere-tjänsten igen.

500 fel: Ibland kan tillfälliga serverfel uppstå. Om du får ett serverfel försöker du igen några gånger för att se om felet försvinner.

CORS-stöd

Cors (Cross-Region Origin Sharing) stöds inte i den här versionen.

Relaterat innehåll