Vue d’ensemble de l’API publique Azure Sphere

Article
08/09/2023

L’API publique Azure Sphere est un ensemble de points de terminaison de service qui prennent en charge les opérations HTTP pour la création et la gestion de ressources Azure Sphere telles que les locataires, les produits, les déploiements et les groupes d’appareils. L’API publique Azure Sphere utilise le protocole HTTP REST (REpresentational State Transfer) pour envoyer des demandes d’opération et des réponses. Les données retournées dans la réponse de l’opération sont mises en forme au format JSON (JavaScript Object Notation). Les opérations disponibles sont documentées dans les informations de référence sur l’API publique Azure Sphere.

Les clients peuvent préférer utiliser l’interface de ligne de commande (CLI) Azure Sphere plutôt que l’API publique pour effectuer des tâches de gestion des ressources. L’interface CLI simplifie l’envoi et la réception des demandes d’opération et des réponses en faisant abstraction d’une grande partie de la complexité programmatique de l’API publique. Les commandes CLI utilisent l’API publique Azure Sphere pour effectuer des tâches, mais la syntaxe simple des commandes CLI les rend beaucoup plus faciles à utiliser.

Certains clients peuvent vouloir créer leur propre interface utilisateur (IU) pour effectuer des tâches de gestion des ressources. L’API publique Azure Sphere peut être utilisée pour créer une interface utilisateur personnalisée. Il n’est pas possible de créer une interface utilisateur personnalisée avec l’interface CLI Azure Sphere.

Composants d’une requête d’API REST

Une requête d’API REST comporte les trois composants suivants :

URI de la requête, sous la forme suivante :

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

Paramètres:
- collection : une ou plusieurs collections. Plusieurs collections imbriquées étant prises en charge, les chemins d’accès relatifs peuvent inclure /collection/id/collection/id ...
  
  Exemple: /v2/tenants/{tenantId}/devices/{deviceId}/images
- resourceId : ID d’une ressource spécifique, qui permet d’accéder à des ressources spécifiques au sein d’une collection.
  
  Exemple: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}
- version : version de l’API, qui identifie la version de l’API. Chaque demande d’API doit inclure une version d’API pour éviter que votre application ou votre service ne s’interrompe à mesure que les API évoluent.
  
  Exemple: /v2
Champs d’en-tête de message de requête HTTP :
- Méthode HTTP requise (également appelée opération ou verbe), qui indique au service le type d’opération que vous demandez.
- Champs d’en-tête supplémentaires, comme requis par l’URI et la méthode HTTP spécifiés. Plus précisément, un en-tête d’autorisation qui fournit un jeton du porteur contenant le jeton d’autorisation du client pour la requête.
Champs de corps de message de requête HTTP facultatifs pour prendre en charge l’URI et l’opération HTTP.
- Pour les opérations HTTP POST ou PUT, le corps doit être spécifié dans l’en-tête de requête Content-Type, ainsi que dans application/json.

Composants d’une réponse d’API REST

Une réponse d’API REST comporte les deux composants suivants :

Champs d’en-tête de message de réponse HTTP :
- Code status HTTP. Les appels réussis retournent des codes 2xx ; Les codes 4xx et 5xx sont des états d’erreur. Pour plus d’informations, consultez la section Codes d’erreur de l’API publique Azure Sphere . Vous pouvez également retourner un code status défini par le service, comme spécifié dans la référence de l’API publique Azure Sphere.
- Champs d’en-tête supplémentaires facultatifs nécessaires pour prendre en charge la réponse à la demande, comme un en-tête de réponse Content-Type.
Champs facultatifs du corps du message de réponse HTTP :
- Les objets de réponse encodés MIME peuvent être retournés dans le corps de la réponse HTTP, par exemple une réponse d’une méthode GET qui retourne des données. Ces objets sont toujours retournés dans un format JSON structuré, comme indiqué par l’en-tête de réponse Content-Type.

Authentification d’une demande

Avant de pouvoir effectuer une demande valide, votre application ou service doit être authentifié auprès de l’API publique Azure Sphere. Le tableau suivant présente certaines des façons dont vous pouvez vous authentifier.

Type d’application	Description	Exemple	Mécanisme d’authentification
Côté client interactif	Application côté client basée sur l’interface utilisateur utilisateur	Énumération des appareils d’application Windows	Bibliothèque d’authentification Microsoft (MSAL)
JavaScript interactif	Application JavaScript basée sur l’interface graphique utilisateur	Application monopage AngularJS affichant les déploiements pour un groupe d’appareils.	MSAL
Web interactif	Application web basée sur l’interface utilisateur graphique	Tableau de bord web personnalisé affichant des résumés de build	OAuth 2

Note

La plateforme Azure Active Directory évolue vers la plateforme Microsoft Identity. Pour plus d’informations, consultez Nouveautés d’Azure Sphere.

Valeurs de la bibliothèque d’authentification

Si vous appelez les bibliothèques d’authentification Microsoft (MSAL) pour acquérir un jeton du porteur à utiliser pour l’authentification, vous devez fournir quatre valeurs :

ID d’application cliente Azure Sphere : 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (requis pour une authentification réussie)
Étendue de l’utilisateur : https://sphere.azure.net/api/user_impersonation
ID de locataire Azure Sphere : 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
Point de terminaison de l’API Azure Sphere : https://prod.core.sphere.azure.net/

Pour plus d’informations sur l’authentification, consultez Bibliothèque d’authentification Microsoft (MSAL) et Flux d’authentification.

Effectuer une demande

Une fois que vous vous êtes authentifié auprès d’Azure Sphere, vous pouvez effectuer des demandes et recevoir des réponses.

L’exemple C# suivant utilise la classe HttpClient pour effectuer une requête.

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
}

Recevoir une réponse

Chaque appel retourne une réponse JSON au format suivant :

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

Codes d’erreur de l’API publique Azure Sphere

L’API publique Azure Sphere retourne les codes d’erreur suivants :

400 - Requête incorrecte
404 - Introuvable
409 - Conflit
410 - Disparu
429 - Trop de demandes
500 - Erreur interne du serveur

Des conseils pour la gestion des erreurs sont fournis dans la section suivante. Pour plus d’informations sur des codes d’erreur spécifiques, consultez RFC 7231.

Conseils de gestion des erreurs

Erreurs 4xx : Les requêtes incorrectes peuvent entraîner des erreurs. Vérifiez la syntaxe de votre requête et les données transmises.

Erreurs 429 : Pour protéger les services Azure Sphere contre les attaques par déni de service distribué (DDoS), nous effectuons le suivi et la limitation des appareils, des utilisateurs ou des locataires qui effectuent un grand nombre d’appels à nos services. Un message d’erreur 429 indique que l’appareil, l’utilisateur ou le locataire a essayé d’appeler le service Azure Sphere trop de fois dans un court laps de temps. Veuillez patienter avant d’appeler à nouveau le service Azure Sphere.

500 erreurs : Parfois, des erreurs de serveur temporaires peuvent se produire. Si vous recevez une erreur de serveur, réessayez plusieurs fois pour voir si l’erreur disparaît.

Prise en charge de CORS

Cors (Cross-Region Origin Sharing) n’est pas pris en charge dans cette version.

Share via

Vue d’ensemble de l’API publique Azure Sphere

Composants d’une requête d’API REST

Composants d’une réponse d’API REST

Authentification d’une demande

Valeurs de la bibliothèque d’authentification

Effectuer une demande

Recevoir une réponse

Codes d’erreur de l’API publique Azure Sphere

Conseils de gestion des erreurs

Prise en charge de CORS

Ressources supplémentaires

Share via

Vue d’ensemble de l’API publique Azure Sphere

Composants d’une requête d’API REST

Composants d’une réponse d’API REST

Authentification d’une demande

Valeurs de la bibliothèque d’authentification

Effectuer une demande

Recevoir une réponse

Codes d’erreur de l’API publique Azure Sphere

Conseils de gestion des erreurs

Prise en charge de CORS

Contenu associé

Ressources supplémentaires