Übersicht über die öffentliche Azure Sphere-API

  • Artikel

Die öffentliche Azure Sphere-API besteht aus einer Reihe von Dienstendpunkten, die HTTP-Vorgänge zum Erstellen und Verwalten von Azure Sphere-Ressourcen wie Mandanten, Produkten, Bereitstellungen und Gerätegruppen unterstützen. Die öffentliche Azure Sphere-API verwendet das REST-HTTP-Protokoll (REpresentational State Transfer), um Vorgangsanforderungen und -antworten zu senden. Die in der Vorgangsantwort zurückgegebenen Daten sind in JSON (JavaScript Object Notation) formatiert. Die verfügbaren Vorgänge sind in der öffentlichen Azure Sphere-API-Referenz dokumentiert.

Kunden bevorzugen möglicherweise die Verwendung der Azure Sphere-Befehlszeilenschnittstelle (CLI) anstelle der öffentlichen API, um Ressourcenverwaltungsaufgaben auszuführen. Die CLI vereinfacht das Senden und Empfangen von Vorgangsanforderungen und -antworten, indem ein Großteil der programmgesteuerten Komplexität der öffentlichen API abstrahiert wird. Die CLI-Befehle verwenden die öffentliche Azure Sphere-API zum Ausführen von Aufgaben, aber die einfache Syntax der CLI-Befehle macht sie viel einfacher zu verwenden.

Einige Kunden möchten möglicherweise eine eigene Benutzeroberfläche (UI) erstellen, um Ressourcenverwaltungsaufgaben auszuführen. Die öffentliche Azure Sphere-API kann zum Erstellen einer benutzerdefinierten Benutzeroberfläche verwendet werden. Es ist nicht möglich, eine benutzerdefinierte Benutzeroberfläche mit der Azure Sphere CLI zu erstellen.

Komponenten einer REST-API-Anforderung

Eine REST-API-Anforderung umfasst die folgenden drei Komponenten:

  1. Der Anforderungs-URI im folgenden Format:

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

    Parameter:

    • collection: Eine oder mehrere Auflistungen. Mehrere geschachtelte Sammlungen werden unterstützt, sodass relative Pfade /collection/id/collection/id ...

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

    • resourceId: Die ID einer bestimmten Ressource, die den Zugriff auf bestimmte Ressourcen innerhalb einer Sammlung ermöglicht.

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

    • version: Die API-Version, die die Version der API identifiziert. Jede API-Anforderung sollte eine API-Version enthalten, um zu vermeiden, dass Ihre App oder Ihr Dienst mit der Weiterentwicklung der APIs unterbrochen wird.

      Beispiel: /v2

  2. Headerfelder für HTTP-Anforderungsnachrichten:

    • Eine erforderliche HTTP-Methode (auch als Vorgang oder Verb bezeichnet), die dem Dienst mitteilt, welche Art von Vorgang Sie anfordern.
    • Zusätzliche Headerfelder, wie für den angegebenen URI und die HTTP-Methode erforderlich. Insbesondere ein Autorisierungsheader, der ein Bearertoken bereitstellt, das das Clientautorisierungstoken für die Anforderung enthält.

  3. Optionale Felder für den Nachrichtentext der HTTP-Anforderung zur Unterstützung des URI und des HTTP-Vorgangs.

    • Bei HTTP POST- oder PUT-Vorgängen sollte der Text im Anforderungsheader Content-Type sowie in application/json angegeben werden.

Komponenten einer REST-API-Antwort

Eine REST-API-Antwort weist die folgenden zwei Komponenten auf:

  1. Headerfelder für HTTP-Antwortnachrichten:

  2. Optionale Felder für den Text der HTTP-Antwortnachricht:

    • MIME-codierte Antwortobjekte können im HTTP-Antworttext zurückgegeben werden, z. B. eine Antwort von einer GET-Methode, die Daten zurückgibt. Diese Objekte werden immer in einem strukturierten JSON-Format zurückgegeben, wie im Content-Type-Antwortheader angegeben.

Authentifizierung einer Anforderung

Bevor Sie eine gültige Anforderung stellen können, muss Ihre Anwendung oder Ihr Dienst mit der öffentlichen Azure Sphere-API authentifiziert werden. In der folgenden Tabelle sind einige der Möglichkeiten zur Authentifizierung aufgeführt.

Anwendungstyp Beschreibung Beispiel Authentifizierungsmechanismus
Interaktiv clientseitig GUI-basierte clientseitige Anwendung Auflisten von Geräten durch Windows-Apps Microsoft Authentication Library (MSAL)
Interaktives JavaScript GUI-basierte JavaScript-Anwendung AngularJS-Single-Page-App, die Bereitstellungen für eine Gerätegruppe anzeigt. MSAL
Interaktives Web GUI-basierte Webanwendung Benutzerdefinierte Web-Dashboard anzeigen von Buildzusammenfassungen OAuth 2

Hinweis

Die Azure Active Directory-Plattform entwickelt sich zur Microsoft Identity Platform. Weitere Informationen finden Sie unter Neuerungen in Azure Sphere.

Werte der Authentifizierungsbibliothek

Wenn Sie die Microsoft Authentication Libraries (MSAL) aufrufen, um ein Bearertoken für die Authentifizierung abzurufen, müssen Sie vier Werte angeben:

  • ID der Azure Sphere-Clientanwendung: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (für eine erfolgreiche Authentifizierung erforderlich)
  • Bereich für den Benutzer: https://sphere.azure.net/api/user_impersonation
  • Azure Sphere-Mandanten-ID: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
  • Azure Sphere-API-Endpunkt: https://prod.core.sphere.azure.net/

Weitere Informationen zur Authentifizierung finden Sie unter Microsoft Authentication Library (MSAL) und Authentifizierungsflows.

Stellen einer Anforderung

Nachdem Sie sich bei Azure Sphere authentifiziert haben, können Sie Anforderungen senden und Antworten empfangen.

Im folgenden C#-Beispiel wird die HttpClient-Klasse verwendet, um eine Anforderung zu senden.

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
}

Empfangen einer Antwort

Jeder Aufruf gibt eine JSON-Antwort im folgenden Format zurück:

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

Fehlercodes der öffentlichen Azure Sphere-API

Die öffentliche Azure Sphere-API gibt die folgenden Fehlercodes zurück:

  • 400 – Ungültige Anforderung
  • 404 – Nicht gefunden
  • 409 – Konflikt
  • 410 – Nicht mehr vorhanden
  • 429 – Zu viele Anforderungen
  • 500 : Interner Serverfehler

Anleitungen zur Behandlung von Fehlern finden Sie im folgenden Abschnitt. Ausführliche Informationen zu bestimmten Fehlercodes finden Sie unter RFC 7231.

Leitfaden zur Fehlerbehandlung

4xx-Fehler: Falsch formatierte Anforderungen können zu Fehlern führen. Überprüfen Sie ihre Anforderungssyntax und die übergebenen Daten.

Fehler 429: Um Azure Sphere-Dienste vor verteilten Denial-of-Service-Angriffen (DDoS) zu schützen, verfolgen und drosseln wir Geräte, Benutzer oder Mandanten, die eine große Anzahl von Aufrufen an unsere Dienste tätigen. Eine Fehlermeldung vom Typ 429 gibt an, dass das Gerät, der Benutzer oder der Mandant innerhalb eines kurzen Zeitraums zu oft versucht hat, den Azure Sphere-Dienst aufzurufen. Warten Sie, bevor Sie den Azure Sphere-Dienst erneut aufrufen.

500 Fehler: Gelegentlich können vorübergehende Serverfehler auftreten. Wenn Sie einen Serverfehler erhalten, wiederholen Sie die Anforderung einige Male, um festzustellen, ob der Fehler nicht mehr auftritt.

CORS-Unterstützung

Die regionsübergreifende Ursprungsfreigabe (Cross-Region Origin Sharing, CORS) wird in dieser Version nicht unterstützt.

Verwandte Inhalte