Condividi tramite

Panoramica dell'API pubblica di Azure Sphere

  • Articolo

Importante

Questa è la documentazione di Azure Sphere (legacy). Azure Sphere (legacy) viene ritirato il 27 settembre 2027 e gli utenti devono eseguire la migrazione ad Azure Sphere (integrato) entro questo periodo. Usare il selettore di versione posizionato sopra il sommario per visualizzare la documentazione di Azure Sphere (integrata).

L'API pubblica di Azure Sphere è un set di endpoint di servizio che supportano le operazioni HTTP per la creazione e la gestione di risorse di Azure Sphere, ad esempio tenant, prodotti, distribuzioni e gruppi di dispositivi. L'API pubblica di Azure Sphere usa il protocollo HTTP REST (REpresentational State Transfer) per inviare richieste e risposte operative. I dati restituiti nella risposta dell'operazione vengono formattati in JSON (JavaScript Object Notation). Le operazioni disponibili sono documentate nelle informazioni di riferimento sulle API pubbliche di Azure Sphere.

I clienti possono preferire l'uso dell'interfaccia della riga di comando di Azure Sphere anziché l'API pubblica per eseguire attività di gestione delle risorse. L'interfaccia della riga di comando semplifica l'invio e la ricezione di richieste e risposte di operazioni astraendo gran parte della complessità programmatica dell'API pubblica. I comandi dell'interfaccia della riga di comando usano l'API pubblica di Azure Sphere per eseguire attività, ma la semplice sintassi dei comandi dell'interfaccia della riga di comando semplifica l'uso.

Alcuni clienti possono voler creare un'interfaccia utente personalizzata per eseguire attività di gestione delle risorse. L'API pubblica di Azure Sphere può essere usata per creare un'interfaccia utente personalizzata. Non è possibile creare un'interfaccia utente personalizzata con l'interfaccia della riga di comando di Azure Sphere.

Componenti di una richiesta API REST

Una richiesta api REST include i tre componenti seguenti:

  1. URI della richiesta, nel formato seguente:

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

    Parametri:

    • collection: una o più raccolte. Sono supportate più raccolte annidate, quindi i percorsi relativi possono includere /collection/id/collection/id ...

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

    • resourceId: ID di una risorsa specifica, che consente l'accesso a risorse specifiche all'interno di una raccolta.

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

    • version: versione dell'API, che identifica la versione dell'API. Ogni richiesta API deve includere una versione api per evitare che l'app o l'interruzione del servizio si interrompa man mano che le API si evolvono.

      Esempio: /v2

  2. Campi di intestazione del messaggio di richiesta HTTP:

    • Un metodo HTTP necessario (noto anche come operazione o verbo) che indica al servizio il tipo di operazione richiesto.
    • Campi di intestazione aggiuntivi, come richiesto dall'URI e dal metodo HTTP specificati. In particolare, un'intestazione di autorizzazione che fornisce un token di connessione contenente il token di autorizzazione client per la richiesta.

  3. Campi facoltativi del corpo del messaggio di richiesta HTTP per supportare l'URI e l'operazione HTTP.

    • Per le operazioni HTTP POST o PUT, il corpo deve essere specificato nell'intestazione della richiesta Content-Type e in application/json.

Componenti di una risposta api REST

Una risposta dell'API REST include i due componenti seguenti:

  1. Campi di intestazione del messaggio di risposta HTTP:

    • Codice di stato HTTP. Le chiamate riuscite restituiscono codici 2xx; I codici 4xx e 5xx sono stati di errore. Per informazioni dettagliate, vedere la sezione Codici di errore dell'API pubblica di Azure Sphere. In alternativa, è possibile che venga restituito un codice di stato definito dal servizio, come specificato nel riferimento all'API pubblica di Azure Sphere.
    • Campi di intestazione aggiuntivi facoltativi necessari per supportare la risposta alla richiesta, ad esempio un'intestazione di risposta Content-Type.

  2. Campi facoltativi del corpo del messaggio di risposta HTTP:

    • Gli oggetti risposta con codifica MIME possono essere restituiti nel corpo della risposta HTTP, ad esempio una risposta da un metodo GET che restituisce dati. Questi oggetti vengono sempre restituiti in un formato JSON strutturato, come indicato dall'intestazione della risposta Content-Type.

Autenticazione di una richiesta

Prima di poter effettuare una richiesta valida, l'applicazione o il servizio deve essere autenticato con l'API pubblica di Azure Sphere. La tabella seguente illustra alcuni dei modi in cui è possibile eseguire l'autenticazione.

Tipo di applicazione Descrizione Esempio Meccanismo di autenticazione
Lato client interattivo Applicazione lato client basata sull'interfaccia utente grafica Dispositivi di enumerazione di app Windows Microsoft Authentication Library (MSAL)
JavaScript interattivo Applicazione JavaScript basata su GUI App a pagina singola AngularJS che visualizza le distribuzioni per un gruppo di dispositivi. MSAL
Web interattivo Applicazione Web basata su GUI Dashboard Web personalizzato che visualizza riepiloghi di compilazione OAuth 2

Nota

La piattaforma Azure Active Directory si sta evolvendo in Microsoft Identity Platform. Per altre informazioni, vedere Novità di Azure Sphere.

Valori della libreria di autenticazione

Se si chiama Microsoft Authentication Libraries (MSAL) per acquisire un token di connessione da usare per l'autenticazione, è necessario specificare quattro valori:

  • ID applicazione client di Azure Sphere: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (obbligatorio per l'autenticazione riuscita)
  • Ambito per l'utente: https://sphere.azure.net/api/user_impersonation
  • ID tenant di Azure Sphere: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
  • Endpoint DELL'API Azure Sphere: https://prod.core.sphere.azure.net/

Per altre informazioni sull'autenticazione, vedere Microsoft Authentication Library (MSAL) e Flussi di autenticazione.

Effettuare una richiesta

Dopo aver eseguito l'autenticazione con Azure Sphere, è possibile effettuare richieste e ricevere risposte.

Nell'esempio C# seguente viene usata la classe HttpClient per effettuare una richiesta.

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
}

Ricevere una risposta

Ogni chiamata restituisce una risposta JSON nel formato seguente:

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

Codici di errore dell'API pubblica di Azure Sphere

L'API pubblica di Azure Sphere restituisce i codici di errore seguenti:

  • 400 - Richiesta non valida
  • 404 - Pagina non trovata
  • 409 - Conflitto
  • 410 - Via
  • 429 - Troppe richieste
  • 500 - Errore interno del server

Le indicazioni per la gestione degli errori sono disponibili nella sezione seguente. Per informazioni dettagliate su codici di errore specifici, vedere RFC 7231.

Indicazioni sulla gestione degli errori

Errori 4xx: le richieste non valide possono causare errori. Controllare la sintassi della richiesta e i dati passati.

429 errori: per proteggere i servizi di Azure Sphere da attacchi DDoS (Distributed Denial of Service), vengono monitorati e limitati i dispositivi, gli utenti o i tenant che effettuano un numero elevato di chiamate ai servizi. Un messaggio di errore 429 indica che il dispositivo, l'utente o il tenant ha tentato di chiamare il servizio Azure Sphere troppe volte entro un breve periodo di tempo. Attendere prima di chiamare di nuovo il servizio Azure Sphere.

500 errori: occasionalmente possono verificarsi errori temporanei del server. Se viene visualizzato un errore del server, ripetere la richiesta alcune volte per verificare se l'errore viene eliminato.

Supporto CORS

La condivisione tra le origini tra aree (CORS) non è supportata in questa versione.

Contenuto correlato