Panoramica dell'API pubblica azure sphere

  • Articolo

L'API pubblica di Azure Sphere è un set di endpoint del servizio che supportano le operazioni HTTP per la creazione e la gestione di risorse Azure Sphere, ad esempio tenant, prodotti, distribuzioni e gruppi di dispositivi. L'API pubblica azure sphere utilizza il protocollo HTTP REST (REpresentational State Transfer) per inviare le richieste di operazione e le risposte. I dati restituiti nella risposta all'operazione sono formattati in JSON (notazione oggetto JavaScript). Le operazioni disponibili sono documentate nel riferimento API pubblico azure sphere.

I clienti potrebbero preferire l'interfaccia da riga di comando (CLI) Azure Sphere invece dell'API pubblica per eseguire attività di gestione delle risorse. Il CLI semplifica l'invio e la ricezione di richieste di operazione e risposte, astrattando gran parte della complessità programmatica dell'API pubblica. I comandi CLI usano l'API pubblica Azure Sphere per eseguire attività, ma la semplice sintassi dei comandi CLI li rende molto più facili da usare.

Alcuni clienti potrebbero voler creare una propria interfaccia utente per eseguire attività di gestione delle risorse. L'API pubblica Azure Sphere può essere utilizzata per creare un'interfaccia utente personalizzata. Non è possibile creare un'interfaccia utente personalizzata con azure sphere CLI.

Componenti di una richiesta API REST

Una richiesta DI API REST ha i seguenti tre componenti:

  1. URI della richiesta, nel seguente formato:

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

    Parametri:

    • raccolta: 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}

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

      Esempio: /v2

  2. Campi dell'intestazione del messaggio di richiesta HTTP:

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

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

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

Componenti di una risposta API REST

Una risposta API REST ha i seguenti due componenti:

  1. Campi dell'intestazione dei messaggi 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, vedi la sezione Codici di errore delle API pubbliche Azure Sphere . In alternativa, potrebbe essere restituito un codice di stato definito dal servizio, come specificato nel riferimento API pubblico azure sphere.
    • Campi di intestazione aggiuntivi facoltativi necessari per supportare la risposta alla richiesta, ad esempio un'intestazione di risposta Tipo di contenuto.

  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 di risposta Content-Type.

Autenticazione di una richiesta

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

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

Nota

La piattaforma Azure Active Directory si sta evolvendo nella piattaforma Identità Microsoft. Per altre informazioni, vedi Novità di Azure Sphere.

Valori della raccolta di autenticazione

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

  • ID applicazione client Azure Sphere: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (necessario per l'autenticazione riuscita)
  • Ambito per l'utente: https://sphere.azure.net/api/user_impersonation
  • ID tenant 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 effettuato l'autenticazione con Azure Sphere, è possibile effettuare richieste e ricevere risposte.

L'esempio C# seguente usa 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 seguente formato:

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

Codici di errore dell'API pubblica Azure Sphere

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

  • 400 - Richiesta errata
  • 404 - Non trovato
  • 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 per la gestione degli errori

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

429 errori: Per proteggere i servizi Azure Sphere da attacchi DDoS (Distributed Denial of Service), Monitoriamo e limitiamo i dispositivi, gli utenti o i tenant che effettuano un numero elevato di chiamate ai nostri 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 in un breve periodo di tempo. Attendi prima di chiamare di nuovo il servizio Azure Sphere.

500 errori: In alcuni casi, possono verificarsi errori temporanei del server. Se viene visualizzato un errore del server, riprovare a inviare la richiesta alcune volte per verificare se l'errore scompare.

Supporto cors

Cors (Cross-Region Origin Sharing) non è supportato in questa versione.

Contenuto correlato