Vue d’ensemble de l’API publique Azure Sphere

L’API publique Azure Sphere est un ensemble de points de terminaison de service qui prennent en charge les opérations HTTP pour créer et gérer des ressources Azure Sphere telles que des locataires, des produits, des déploiements et des 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 la référence de l’API publique Azure Sphere.

Les clients peuvent préférer utiliser l’interface de ligne de commande Azure Sphere (CLI) au lieu de l’API publique pour effectuer des tâches de gestion des ressources. L’interface CLI simplifie l’envoi et la réception de demandes et de réponses d’opération en abstraitant 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 facilite leur utilisation.

Certains clients peuvent souhaiter créer leur propre interface utilisateur 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 :

1. URI de 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 sont prises en charge, de sorte que les chemins 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 soit rompu à mesure que les API évoluent.

     Exemple : /v2

2. Champs d’en-tête du message de requête HTTP :

   • Méthode HTTP obligatoire (é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 de porteur contenant le jeton d’autorisation client pour la demande.

3. 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 :

1. Champs d'en-tête du message de réponse HTTP :

   • Code d’état HTTP. Les appels réussis retournent des codes 2xx ; Les codes 4xx et 5xx sont des états d’erreur : consultez la section Codes d’erreur de l’API publique Azure Sphere pour plus d’informations. Vous pouvez également renvoyer un code d’état 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 comme requis pour prendre en charge la réponse à la demande, comme un en-tête de réponse Content-Type.

2. Champs du corps du message de réponse HTTP facultatifs :

   • 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é avec l’API publique Azure Sphere. Le tableau suivant présente quelques-unes des façons dont vous pouvez vous authentifier.

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 l’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 la bibliothèque d’authentification Microsoft (MSAL) et les flux d’authentification.

Exécuter une requête

Une fois que vous avez authentifié avec 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 mal formées peuvent entraîner des erreurs. Vérifiez la syntaxe de votre requête et les données passées.

429 erreurs : 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 délai. 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 la demande quelques fois pour voir si l’erreur disparaît.

Prise en charge de CORS

Le partage d’origine inter-régions (CORS) n’est pas pris en charge dans cette version.

Contenu associé

• Plateforme d’identités Microsoft 2.0
• Vue d’ensemble de l’API .NET AAD