Freigeben über

Übersicht über die öffentliche Azure Sphere-API

  • Artikel

Wichtig

Dies ist die Dokumentation zu Azure Sphere (Legacy). Azure Sphere (Legacy) wird am 27. September 2027 eingestellt, und Benutzer müssen bis zu diesem Zeitpunkt zu Azure Sphere (integriert) migrieren. Verwenden Sie die Versionsauswahl oberhalb des Inhaltsverzeichniss, um die Dokumentation zu Azure Sphere (Integriert) anzuzeigen.

Die öffentliche Azure Sphere-API ist eine 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 HTTP-Protokoll REST (REpresentational State Transfer), um Vorgangsanforderungen und -antworten zu senden. Die in der Vorgangsantwort zurückgegebenen Daten werden 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 Befehlszeilenschnittstelle (Azure Sphere Command-Line Interface , 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 erleichtert ihnen die Verwendung.

Einige Kunden möchten möglicherweise eine eigene Benutzeroberfläche 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 verfügt über die folgenden drei Komponenten:

  1. Der Anforderungs-URI in der folgenden Form:

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

    Parameter:

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

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

    • resourceId: Die ID einer bestimmten Ressource, die den Zugriff auf bestimmte Ressourcen innerhalb einer Auflistung 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 abgebrochen wird, wenn SICH APIs entwickeln.

      Beispiel: /v2

  2. Nachrichtenheaderfelder mit HTTP-Anforderungen:

    • eine erforderliche HTTP-Methode (ebenfalls unter den Bezeichnungen „Vorgang“ oder „Verb“ bekannt), über die der Dienst erfährt, welchen Vorgangstyp Sie anfordern;
    • Zusätzliche Kopfzeilenfelder, wie für die angegebene URI- und HTTP-Methode erforderlich. Insbesondere ein Autorisierungsheader, der ein Bearertoken mit Clientautorisierungstoken für die Anforderung bereitstellt.

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

    • Bei HTTP POST- oder PUT-Vorgängen sollte der Textkörper sowohl im Content-Type-Anforderungsheader als auch in application/json angegeben werden.

Komponenten einer REST-API-Antwort

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

  1. Nachrichtenheaderfelder mit HTTP-Anworten:

    • Http-Statuscode. Erfolgreiche Anrufe geben 2xx-Codes zurück; 4xx- und 5xx-Codes sind Fehlerstatus – Details finden Sie im Abschnitt " Öffentliche Azure Sphere-API-Fehlercodes ". Alternativ kann ein dienstdefinierter Statuscode zurückgegeben werden, wie in der öffentlichen Azure Sphere-API-Referenz angegeben.
    • Optionale zusätzliche Kopfzeilenfelder, die erforderlich sind, um die Antwort auf die Anforderung zu unterstützen, z. B. einen Inhaltstyp-Antwortheader.

  2. Optionale Nachrichtentextfelder mit HTTP-Antworten:

    • 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 durch den 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 aufgeführt, wie Sie sich authentifizieren können.

Art der Anwendung BESCHREIBUNG Beispiel Authentifizierungsmechanismus
Interaktive Clientseite GUI-basierte clientseitige Anwendung Aufzählen von Geräten für Windows-Apps Microsoft Authentication Library (MSAL)
Interaktives JavaScript GUI-basierte JavaScript-Anwendung AngularJS-Einzelseiten-App mit Bereitstellungen für eine Gerätegruppe. MSAL
Interaktives Web GUI-basierte Webanwendung Benutzerdefiniertes Webdashboard mit Buildzusammenfassungen OAuth 2

Hinweis

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

Werte der Authentifizierungsbibliothek

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

  • Azure Sphere-Clientanwendungs-ID: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (erforderlich für die erfolgreiche Authentifizierung)
  • 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 Authentifizierungsflüsse.

Erstellen einer Anforderung

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

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

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 werden im folgenden Abschnitt bereitgestellt. Ausführliche Informationen zu bestimmten Fehlercodes finden Sie unter RFC 7231.

Anleitung zur Fehlerbehandlung

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

429 Fehler: 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 Anrufen an unsere Dienste tätigen. Eine Fehlermeldung von 429 weist darauf hin, dass das Gerät, der Benutzer oder der Mandant versucht hat, den Azure Sphere-Dienst zu oft innerhalb eines kurzen Zeitraums 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 ein paar Mal, um festzustellen, ob der Fehler nicht mehr angezeigt wird.

CORS-Support

Die cross-Region Origin Sharing (CORS) wird in dieser Version nicht unterstützt.

Verwandte Inhalte