Delen via

Overzicht van de openbare API van Azure Sphere

  • Artikel

Belangrijk

Dit is de Documentatie voor Azure Sphere (verouderd). Azure Sphere (verouderd) wordt op 27 september 2027 buiten gebruik gesteld en gebruikers moeten tegen deze tijd migreren naar Azure Sphere (geïntegreerd). Gebruik de versiekiezer boven de inhoudsweergave om de Documentatie van Azure Sphere (geïntegreerd) weer te geven.

De openbare Azure Sphere-API is een set service-eindpunten die HTTP-bewerkingen ondersteunen voor het maken en beheren van Azure Sphere-resources, zoals tenants, producten, implementaties en apparaatgroepen. De openbare Api van Azure Sphere maakt gebruik van het HTTP-protocol REST (REpresentational State Transfer) om bewerkingsaanvragen en -antwoorden te verzenden. De gegevens die worden geretourneerd in het antwoord van de bewerking, worden opgemaakt in JSON (JavaScript Object Notation). De beschikbare bewerkingen worden beschreven in de openbare API-verwijzing van Azure Sphere.

Klanten kunnen liever de Azure Sphere-opdrachtregelinterface (CLI) gebruiken in plaats van de openbare API om resourcebeheertaken uit te voeren. De CLI vereenvoudigt het verzenden en ontvangen van bewerkingsaanvragen en -antwoorden door een groot deel van de programmatische complexiteit van de openbare API te abstraheren. De CLI-opdrachten maken gebruik van de openbare API van Azure Sphere om taken uit te voeren, maar de eenvoudige syntaxis van de CLI-opdrachten maken ze veel gemakkelijker te gebruiken.

Sommige klanten willen mogelijk hun eigen gebruikersinterface (UI) bouwen om resourcebeheertaken uit te voeren. De openbare API van Azure Sphere kan worden gebruikt om een aangepaste gebruikersinterface te bouwen. Het is niet mogelijk om een aangepaste gebruikersinterface te bouwen met de Azure Sphere CLI.

Onderdelen van een REST API-aanvraag

Een REST API-aanvraag heeft de volgende drie onderdelen:

  1. De aanvraag-URI, in de volgende vorm:

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

    Parameters:

    • verzameling: een of meer verzamelingen. Meerdere geneste verzamelingen worden ondersteund, zodat relatieve paden /collection/id/collection/id...

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

    • resourceId: de id van een specifieke resource, waarmee toegang tot specifieke resources in een verzameling mogelijk is.

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

    • versie: de API-versie, die de versie van de API identificeert. Elke API-aanvraag moet een API-versie bevatten om te voorkomen dat uw app of service wordt onderbroken wanneer API's zich ontwikkelen.

      Voorbeeld: /v2

  2. Headervelden voor HTTP-aanvraagberichten:

    • Een vereiste HTTP-methode (ook wel een bewerking of werkwoord genoemd), waarmee de service aangeeft welk type bewerking u aanvraagt.
    • Aanvullende headervelden, zoals vereist door de opgegeven URI en HTTP-methode. Een autorisatieheader die een bearer-token met clientautorisatietoken voor de aanvraag biedt.

  3. Optionele hoofdtekstvelden voor HTTP-aanvraagberichten ter ondersteuning van de URI- en HTTP-bewerking.

    • Voor HTTP POST- of PUT-bewerkingen moet de hoofdtekst worden opgegeven in de aanvraagheader van het inhoudstype en toepassing/json.

Onderdelen van een REST API-antwoord

Een REST API-antwoord heeft de volgende twee onderdelen:

  1. Headervelden voor HTTP-antwoordberichten:

    • Een HTTP-statuscode. Geslaagde aanroepen retourneren 2xx-codes; 4xx- en 5xx-codes zijn foutstatussen. Zie de sectie openbare API-foutcodes van Azure Sphere voor meer informatie. U kunt ook een servicegedefinieerde statuscode retourneren, zoals opgegeven in de openbare API-verwijzing van Azure Sphere.
    • Optionele extra koptekstvelden zoals vereist om het antwoord op de aanvraag te ondersteunen, zoals een antwoordheader van het inhoudstype.

  2. Optionele hoofdtekstvelden voor HTTP-antwoordberichten:

    • Mime-gecodeerde antwoordobjecten kunnen worden geretourneerd in de hoofdtekst van het HTTP-antwoord, zoals een antwoord van een GET-methode die gegevens retourneert. Deze objecten worden altijd geretourneerd in een gestructureerde JSON-indeling, zoals aangegeven door de antwoordheader Content-Type.

Verificatie van een aanvraag

Voordat u een geldige aanvraag kunt indienen, moet uw toepassing of service worden geverifieerd met de openbare Azure Sphere-API. In de volgende tabel ziet u enkele manieren waarop u zich kunt verifiëren.

Type toepassing Beschrijving Voorbeeld Verificatiemechanisme
Interactieve clientzijde Toepassing aan de clientzijde op basis van GUI Windows-app die apparaten opsommen Microsoft Authentication Library (MSAL)
Interactief JavaScript Op GUI gebaseerde JavaScript-toepassing AngularJS-app met één pagina met implementaties voor een apparaatgroep. MSAL
Interactief web Webtoepassing op basis van GUI Aangepast webdashboard met samenvattingen van build OAuth 2

Notitie

Het Azure Active Directory-platform ontwikkelt zich in het Microsoft Identity-platform. Zie Wat is er nieuw in Azure Sphere voor meer informatie.

Verificatiebibliotheekwaarden

Als u de Microsoft Authentication Libraries (MSAL) aanroept om een Bearer-token te verkrijgen dat moet worden gebruikt voor verificatie, moet u vier waarden opgeven:

  • Azure Sphere-clienttoepassings-id: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (vereist voor geslaagde verificatie)
  • Bereik voor de gebruiker: https://sphere.azure.net/api/user_impersonation
  • Tenant-id van Azure Sphere: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
  • Azure Sphere API-eindpunt: https://prod.core.sphere.azure.net/

Zie Microsoft Authentication Library (MSAL) en verificatiestromen voor meer informatie over verificatie.

Een aanvraag maken

Nadat u bent geverifieerd met Azure Sphere, kunt u aanvragen indienen en antwoorden ontvangen.

In het volgende C#-voorbeeld wordt de HttpClient-klasse gebruikt om een aanvraag te doen.

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
}

Een antwoord ontvangen

Elke aanroep retourneert een JSON-antwoord in de volgende indeling:

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

Foutcodes voor openbare API in Azure Sphere

De openbare API van Azure Sphere retourneert de volgende foutcodes:

  • 400 - Foute aanvraag
  • 404 - Niet gevonden
  • 409 - Conflict
  • 410 - Weg
  • 429 - Te veel aanvragen
  • 500 - Interne serverfout

Richtlijnen voor het afhandelen van fouten vindt u in de volgende sectie. Zie RFC 7231 voor gedetailleerde informatie over specifieke foutcodes.

Richtlijnen voor foutafhandeling

4xx-fouten: ongeldige aanvragen kunnen leiden tot fouten. Controleer de syntaxis van uw aanvraag en de gegevens die worden doorgegeven.

429-fouten: Om Azure Sphere-services te beschermen tegen DDoS-aanvallen (Distributed Denial of Service), volgen en beperken we apparaten, gebruikers of tenants die grote aantallen aanroepen naar onze services uitvoeren. Een 429-foutbericht geeft aan dat het apparaat, de gebruiker of de tenant te vaak heeft geprobeerd de Azure Sphere-service binnen een korte periode aan te roepen. Wacht totdat u de Azure Sphere-service opnieuw aanroept.

500 fouten: Af en toe kunnen tijdelijke serverfouten optreden. Als u een serverfout ontvangt, voert u de aanvraag een paar keer opnieuw uit om te zien of de fout verdwijnt.

CORS-ondersteuning

CORS (Cross-Region Origin Sharing) wordt niet ondersteund in deze release.

Gerelateerde inhoud