Informations de référence sur l’API REST Azure

Bienvenue dans la documentation de référence sur l’API REST Azure.

Les API REST (Representational State Transfer) sont des points de terminaison de service prenant en charge des ensembles d’opérations HTTP (méthodes) qui fournissent, créent, récupèrent, mettent à jour ou suppriment l’accès aux ressources du service. Cet article vous guide tout au long des procédures suivantes :

• Comment appeler des API REST Azure avec curl
• Composants de base d’une paire requête/réponse d’API REST.
• Comment inscrire votre application cliente auprès de Microsoft Entra ID pour sécuriser vos requêtes REST.
• Vue d’ensemble de la création et de l’envoi d’une requête REST et de la gestion de la réponse.

Conseil

La plupart des API REST de service Azure ont des bibliothèques clientes qui fournissent une interface native pour l’utilisation des services Azure :

.NET | Java | | Node.jsPython | Aller | C++

Comment appeler des API REST Azure avec curl

Le processus décrit dans le billet de blog suivant montre comment appeler une API REST Azure à l’aide de curl. Vous pouvez envisager d’utiliser curl dans des scripts sans assistance. Par exemple, dans les scénarios d’automatisation DevOps.

Appel de l’API REST Azure via curl

Composants d’une demande/réponse d’API REST

Une paire demande/réponse d’API REST peut être divisée en cinq composants :

1. L’URI de demande, qui se compose de : {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Bien que l’URI de demande soit inclus dans l’en-tête de message de la demande, nous l’appelons séparément ici, car la plupart des langages ou des frameworks vous obligent à le transmettre séparément du message de demande.

   • Schéma d’URI : indique le protocole utilisé pour transmettre la demande. Par exemple, http ou https.
   • Hôte de l’URI : spécifie le nom de domaine ou l’adresse IP du serveur où le point de terminaison de service REST est hébergé, tel que graph.microsoft.com.
   • Chemin de la ressource : spécifie la ressource ou la collection de ressources, qui peut inclure plusieurs segments utilisés par le service pour déterminer la sélection de ces ressources. Par exemple : beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners peut être utilisé pour interroger la liste de propriétaires d’applications spécifiques dans la collection d’applications.
   • Chaîne de requête (facultative) : fournit des paramètres simples supplémentaires, tels que la version de l’API ou les critères de sélection des ressources.

2. 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. Les API REST Azure prennent en charge les méthodes GET, HEAD, PUT, POST et PATCH.
   • Des champs d’en-tête supplémentaires facultatifs, suivant l’URI et la méthode HTTP spécifiés. Par exemple, un en-tête d’autorisation qui fournit un jeton du porteur contenant les informations d’autorisation du client pour la demande.

3. Des champs du corps de message de demande HTTP, pour prendre en charge l’URI et l’opération HTTP. Par exemple, les opérations POST contiennent des objets codés au format MIME qui sont passés comme paramètres complexes. Pour les opérations POST ou PUT, le type de codage MIME pour le corps doit être spécifié dans l’en-tête de demande Content-type. Certains services vous obligent à utiliser un type MIME spécifique, tel que application/json.

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

   • Un code d’état HTTP, compris entre 2xx (opérations réussies) et 4xx ou 5xx (erreur). Ou bien un code d’état défini par le service peut être retourné, comme indiqué dans la documentation de l’API.
   • Des champs d’en-tête supplémentaires facultatifs, nécessaires à la prise en charge de la réponse de la demande, tels qu’un en-tête de réponse Content-type.

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

   • Les objets de réponse codés au format MIME sont retournés dans le corps de la réponse HTTP, par exemple une réponse à partir d’une méthode GET qui retourne des données. En règle générale, ces objets sont retournés dans un format structuré tel que JSON ou XML, comme indiqué par l’en-tête de réponse Content-type. Par exemple, lorsque vous demandez un jeton d’accès à Microsoft Entra ID, il est retourné dans le corps de la réponse en tant qu’élémentaccess_token, l’un des objets associés nom/valeur dans une collection de données. Dans cet exemple, un en-tête de réponse de Content-Type: application/json est également inclus.

Inscrire votre application cliente auprès de Microsoft Entra ID

La plupart des services Azure (tels que les fournisseurs Azure Resource Manager et le modèle de déploiement classique) nécessitent que votre code client s’authentifie avec des informations d’identification valides avant de pouvoir appeler l’API du service. L’authentification est coordonnée entre les différents acteurs par Microsoft Entra ID et fournit à votre client un jeton d’accès comme preuve de l’authentification. Le jeton est ensuite envoyé au service Azure dans l’en-tête Autorisation HTTP des demandes d’API REST suivantes. Les revendications du jeton fournissent également des informations au service, ce qui lui permet de valider le client et d’effectuer toute autorisation requise.

Si vous utilisez une API REST qui n’utilise pas l’authentification Microsoft Entra intégrée, ou si vous avez déjà inscrit votre client, passez à la section Créer la demande.

Prérequis

Votre application cliente doit faire connaître sa configuration d’identité à Microsoft Entra ID avant l’exécution en l’inscrivant dans un locataire Microsoft Entra. Avant d’inscrire votre client auprès de Microsoft Entra ID, tenez compte des conditions préalables suivantes :

• Si vous n’avez pas encore de locataire Microsoft Entra, consultez Configurer un locataire Microsoft Entra.

• Conformément à oAuth2 Authorization Framework, Microsoft Entra ID prend en charge deux types de clients. La compréhension de chacune d’entre elles vous aide à décider qui convient le mieux à votre scénario :

  • les clients web/confidentiels s’exécutent sur un serveur web et peuvent accéder aux ressources sous leur propre identité (par exemple, un service ou un démon), ou obtenir une autorisation déléguée pour accéder aux ressources sous l’identité d’un utilisateur connecté (par exemple, une application web). Seul un client web peut gérer et présenter de manière sécurisée ses propres informations d’identification pendant Microsoft Entra authentification pour acquérir un jeton d’accès.
  • Les clients natifs/publics sont installés et exécutés sur un appareil. Ils peuvent accéder aux ressources uniquement sous autorisation déléguée, en utilisant l’identité de l’utilisateur connecté pour acquérir un jeton d’accès pour le compte de l’utilisateur.

• Le processus d’inscription crée deux objets associés dans le locataire Microsoft Entra où l’application est inscrite : un objet d’application et un objet principal de service. Pour plus d’informations sur ces composants et leur utilisation au moment de l’exécution, consultez Objets d’application et de principal de service dans Microsoft Entra ID.

Vous êtes maintenant prêt à inscrire votre application cliente auprès de Microsoft Entra ID.

Inscription du client

Pour inscrire un client qui accède à une API REST Azure Resource Manager, consultez Utiliser le portail pour créer Microsoft Entra application et le principal de service qui peuvent accéder aux ressources. L’article (également disponible dans les versions PowerShell et CLI pour automatiser l’inscription) vous montre comment :

• Inscrivez l’application cliente auprès de Microsoft Entra ID.
• Définissez les demandes d’autorisation pour autoriser le client à accéder à l’API Azure Resource Manager.
• Configurez les paramètres Azure Resource Manager Role-Based Access Control (RBAC) pour autoriser le client.

Si votre client accède à une API autre qu’une API Azure Resource Manager, reportez-vous à :

• Inscrire une application à l’aide de la plateforme d’identités Microsoft
  • Inscrivez l’application cliente avec Microsoft Entra ID, dans la section « Inscrire une application ».
  • Créez une clé secrète (si vous inscrivez un client web) dans la section « Ajouter des informations d’identification ».
• Configurer une application pour exposer une API web
  • Ajouter des autorisations à votre API web, en les exposant en tant qu’étendues
• Configurer une application cliente pour accéder à une API web
  • Ajoutez les demandes d’autorisation comme requis par les étendues définies pour l’API, dans la section « Ajouter des autorisations pour accéder à votre API web ».

Maintenant que vous avez terminé l’inscription de votre application cliente, passez à votre code client où vous créez la demande REST et gérez la réponse.

Créer la requête

Cette section couvre les trois premiers des cinq composants dont nous avons parlé précédemment. Vous devez d’abord acquérir le jeton d’accès à partir de Microsoft Entra ID, que vous utilisez pour assembler l’en-tête de votre message de demande.

Obtenir un jeton d’accès

Une fois que vous avez une inscription client valide, vous disposez de deux façons d’intégrer à Microsoft Entra ID pour acquérir un jeton d’accès :

• Points de terminaison de service OAuth2 et non linguistiques, que nous utilisons dans cet article. Les instructions fournies dans cette section ne supposent rien sur la plateforme ou le langage/script de votre client lorsque vous utilisez les Microsoft Entra points de terminaison OAuth. La seule exigence est que vous puissiez envoyer/recevoir des requêtes HTTPS vers/à partir de Microsoft Entra ID et analyser le message de réponse.
• Les bibliothèques d’authentification Microsoft (MSAL) spécifiques à la plateforme et au langage, qui dépassent le cadre de cet article. Les bibliothèques fournissent des wrappers asynchrones pour les demandes de point de terminaison OAuth2 et des fonctionnalités robustes de gestion des jetons telles que la mise en cache et la gestion des jetons d’actualisation. Pour plus d’informations, consultez Vue d’ensemble de la bibliothèque d’authentification Microsoft (MSAL).

Les deux points de terminaison Microsoft Entra que vous utilisez pour authentifier votre client et acquérir un jeton d’accès sont appelés OAuth2 /authorize et /token points de terminaison. Leur utilisation dépend de l’inscription de votre application et du type de flux d’octroi d’autorisation OAuth2 dont vous avez besoin pour prendre en charge votre application au moment de l’exécution. Pour les besoins de cet article, nous partons du principe que votre client utilise l’un des flux d’octroi d’autorisation suivants : code d’autorisation ou informations d’identification du client. Pour acquérir un jeton d’accès utilisé dans les sections restantes, suivez les instructions du flux qui correspond le mieux à votre scénario.

Octroi de code d’autorisation (clients interactifs)

Cet octroi est utilisé à la fois par les clients web et natifs, nécessitant des informations d’identification d’un utilisateur connecté afin de déléguer l’accès aux ressources à l’application cliente. Il utilise le point de /authorize terminaison pour obtenir un code d’autorisation (en réponse à la connexion/au consentement de l’utilisateur), suivi du point de /token terminaison pour échanger le code d’autorisation contre un jeton d’accès.

1. Tout d’abord, votre client doit demander un code d’autorisation à Microsoft Entra ID. Pour plus d’informations sur le format de la requête HTTPS GET adressée au point de terminaison, ainsi que sur les /authorize exemples de messages de demande/réponse, consultez Demander un code d’autorisation. L’URI contient les paramètres de chaîne de requête suivants, qui sont spécifiques à votre application cliente :

   • client_id: GUID qui a été affecté à votre application cliente lors de l’inscription, également appelé ID d’application.

   • redirect_uri: version encodée en URL de l’un des URI de réponse/redirection, spécifiée lors de l’inscription de votre application cliente. La valeur que vous transmettez doit correspondre exactement à votre valeur d’inscription.

   • resource: URI d’identificateur encodé en URL spécifié par l’API REST que vous appelez. Les API Web/REST (également appelées applications de ressources) peuvent exposer un ou plusieurs URI d’ID d’application dans leur configuration. Par exemple :

     • Les API du fournisseur de Resource Manager Azure (et du modèle de déploiement classique) utilisent https://management.core.windows.net/.
     • Pour toutes les autres ressources, consultez la documentation de l’API ou la configuration de l’application de ressource dans le Portail Azure. Pour plus d’informations, consultez la identifierUris propriété de l’objet d’application Microsoft API Graph.

   La demande au point de /authorize terminaison déclenche d’abord une invite de connexion pour authentifier l’utilisateur. La réponse que vous obtenez est remise en tant que redirection (302) vers l’URI que vous avez spécifié dans redirect_uri. Le message d’en-tête de réponse contient un location champ contenant l’URI de redirection suivi d’un code paramètre de requête. Le code paramètre contient le code d’autorisation dont vous avez besoin pour l’étape 2.

2. Ensuite, votre client doit utiliser le code d’autorisation contre un jeton d’accès. Pour plus d’informations sur le format de la requête HTTPS POST adressée au point de terminaison et sur les /token exemples de requête/réponse, consultez Demander un jeton d’accès. Comme il s’agit d’une requête POST, vous empaquetez vos paramètres spécifiques à l’application dans le corps de la demande. En plus de certains des paramètres mentionnés précédemment (ainsi que d’autres nouveaux), vous allez passer :

   • code: ce paramètre de requête contient le code d’autorisation que vous avez obtenu à l’étape 1.

   • client_secret: vous avez besoin de ce paramètre uniquement si votre client est configuré en tant qu’application web. Il s’agit de la même valeur secrète/clé que celle que vous avez générée précédemment, dans l’inscription du client.

Octroi d’informations d’identification client (clients non interactifs)

Cette octroi est utilisé uniquement par les clients web, ce qui permet à l’application d’accéder directement aux ressources (sans délégation d’utilisateur) à l’aide des informations d’identification du client, qui sont fournies au moment de l’inscription. L’octroi est généralement utilisé par les clients non interactifs (sans interface utilisateur) qui s’exécutent en tant que service ou démon. Il nécessite uniquement le point de /token terminaison pour acquérir un jeton d’accès.

Les interactions client/ressource pour cette octroi sont similaires à l’étape 2 de l’octroi de code d’autorisation. Pour plus d’informations sur le format de la demande HTTPS POST sur le /token point de terminaison et les exemples de requête/réponse, consultez la section « Obtenir un jeton » dans Plateforme d'identités Microsoft et le flux d’informations d’identification du client OAuth 2.0.

Assembler le message de requête

La plupart des langages de programmation ou frameworks et environnements de script facilitent l’assemblage et l’envoi du message de demande. Ils fournissent généralement une classe web/HTTP ou une API qui extrait la création ou la mise en forme de la requête, ce qui facilite l’écriture du code client (la HttpWebRequest classe dans le .NET Framework, par exemple). Par souci de concision, et étant donné que la plupart de la tâche est gérée pour vous, cette section couvre uniquement les éléments importants de la requête.

URI de demande

Étant donné que des informations sensibles sont transmises et reçues, toutes les requêtes REST nécessitent le protocole HTTPS pour le schéma d’URI, ce qui donne à la requête et à la réponse un canal sécurisé. Les informations (c’est-à-dire le code d’autorisation Microsoft Entra, le jeton d’accès/porteur et les données de demande/réponse sensibles) sont chiffrées par une couche de transport inférieure, garantissant ainsi la confidentialité des messages.

Le reste de l’URI de requête de votre service (l’hôte, le chemin de ressource et tous les paramètres de chaîne de requête requis) sont déterminés par la spécification de l’API REST associée. Par exemple, les API de fournisseur Azure Resource Manager utilisent https://management.azure.com/, et le modèle de déploiement Classique Azure utilise https://management.core.windows.net/. Les deux nécessitent un api-version paramètre de chaîne de requête.

En-tête de requête

L’URI de requête est groupé dans l’en-tête de message de demande, ainsi que les champs supplémentaires requis par la spécification de l’API REST de votre service et la spécification HTTP. Votre demande peut nécessiter les champs d’en-tête courants suivants :

• Authorization: contient le jeton du porteur OAuth2 pour sécuriser la requête, comme acquis précédemment à partir de Microsoft Entra ID.
• Content-Type: généralement défini sur « application/json » (paires nom/valeur au format JSON) et spécifie le type MIME du corps de la requête.
• Host: nom de domaine ou adresse IP du serveur sur lequel le point de terminaison de service REST est hébergé.

Corps de la demande

Comme mentionné précédemment, le corps du message de demande est facultatif, en fonction de l’opération spécifique que vous demandez et de ses exigences en matière de paramètres. Si nécessaire, la spécification de l’API pour le service que vous demandez spécifie également l’encodage et le format.

Le corps de la demande est séparé de l’en-tête par une ligne vide, mise en forme conformément au champ d’en-tête Content-Type . Un exemple de corps au format « application/json » s’affiche comme suit :

{
  "<name>": "<value>"
}

Envoyer la demande

Maintenant que vous disposez de l’URI de requête du service et que vous avez créé l’en-tête et le corps du message de demande associés, vous êtes prêt à envoyer la demande au point de terminaison du service REST.

Par exemple, vous pouvez envoyer une méthode de requête HTTPS GET pour un fournisseur de Resource Manager Azure à l’aide de champs d’en-tête de requête similaires à ce qui suit (notez que le corps de la requête est vide) :

GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com

<no body>

Vous pouvez également envoyer une méthode de requête PUT HTTPS pour un fournisseur de Resource Manager Azure, en utilisant des champs d’en-tête et de corps de requête similaires à l’exemple suivant :

PUT /subscriptions/.../resourcegroups/ExampleResourceGroup?api-version=2016-02-01  HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com

{
  "location": "West US"
}

Après avoir fait la demande, l’en-tête du message de réponse et le corps facultatif sont retournés.

Traiter le message de réponse

Le processus se termine par les deux derniers des cinq composants.

Pour traiter la réponse, analysez l’en-tête de réponse et, éventuellement, le corps de la réponse (en fonction de la demande). Dans l’exemple HTTPS GET fourni dans la section précédente, vous avez utilisé le point de terminaison /subscriptions pour récupérer la liste des abonnements d’un utilisateur. En supposant que la réponse a réussi, vous devez recevoir des champs d’en-tête de réponse similaires à l’exemple suivant :

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

Et vous devez recevoir un corps de réponse qui contient une liste d’abonnements Azure et leurs propriétés individuelles encodées au format JSON, comme suit :

{
    "value":[
        {
        "id":"/subscriptions/...",
        "subscriptionId":"...",
        "displayName":"My Azure Subscription",
        "state":"Enabled",

"subscriptionPolicies":{
            "locationPlacementId":"Public_2015-09-01",
            "quotaId":"MSDN_2014-05-01",
            "spendingLimit":"On"}
        }
    ]
}

De même, pour l’exemple HTTPS PUT, vous devez recevoir un en-tête de réponse similaire à ce qui suit, confirmant que votre opération PUT pour ajouter « ExampleResourceGroup » a réussi :

HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;

Et vous devez recevoir un corps de réponse qui confirme le contenu de votre groupe de ressources nouvellement ajouté, encodé au format JSON, comme suit :

{
    "id":"/subscriptions/.../resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

Comme pour la requête, la plupart des langages de programmation et des frameworks facilitent le traitement du message de réponse. Ils retournent généralement ces informations à votre application après la demande, ce qui vous permet de les traiter dans un format typé/structuré. Principalement, vous souhaitez confirmer le code http status dans l’en-tête de réponse et analyser le corps de la réponse en fonction de la spécification de l’API (ou des Content-Type champs d’en-tête de réponse et Content-Length ).

Opérations asynchrones, limitation et pagination

Le modèle Create/Send/Process-Response décrit dans cet article est synchrone et s’applique à tous les messages REST. Toutefois, certains services prennent également en charge un modèle asynchrone, qui nécessite un traitement supplémentaire des en-têtes de réponse pour surveiller ou terminer la demande asynchrone. Pour plus d’informations, consultez la rubrique Suivre les opérations asynchrones Azure.

Resource Manager applique une limite au nombre de demandes de lecture et d’écriture par heure pour empêcher une application d’envoyer trop de demandes. Si votre application dépasse ces limites, les demandes sont limitées. L’en-tête de réponse inclut le nombre de demandes restantes pour votre étendue. Pour plus d’informations, consultez Limitation des requêtes de Resource Manager.

Certaines opérations de liste retournent une propriété appelée nextLink dans le corps de la réponse. Vous voyez cette propriété lorsque les résultats sont trop volumineux pour être retournés dans une réponse. En règle générale, la réponse inclut la propriété nextLink lorsque l’opération de liste retourne plus de 1 000 éléments. Lorsque nextLink n’est pas présent dans les résultats, les résultats retournés sont terminés. Lorsque nextLink contient une URL, les résultats retournés ne font qu’une partie du jeu de résultats total.

La réponse est au format suivant :

{
  "value": [
    <returned-items>
  ],
  "nextLink": "https://management.azure.com/{operation}?api-version={version}&%24skiptoken={token}"
}

Pour obtenir la page suivante des résultats, envoyez une requête GET à l’URL dans la propriété nextLink. L’URL inclut un jeton de continuation pour indiquer où vous en êtes dans les résultats. Continuez à envoyer des requêtes à l’URL nextLink jusqu’à ce qu’elle ne contienne plus d’URL dans les résultats retournés.

Résilience des API Azure

Les API REST Azure sont conçues pour la résilience et la disponibilité continue. Les opérations de plan de contrôle (requêtes envoyées à management.azure.com) dans l’API REST sont les suivantes :

• Distribuées dans différentes régions. Certains services sont régionaux.

• Distribuées dans différentes zones de disponibilité (et régions) dans les localisations qui ont plusieurs zones de disponibilité.

• Non dépendantes d’un seul centre de données logique.

• Jamais arrêtées pour des activités de maintenance.

Contenu connexe

Vous avez terminé. Une fois que vous avez inscrit votre application Microsoft Entra et que vous disposez d’une technique modulaire pour l’acquisition d’un jeton d’accès et la gestion des requêtes HTTP, il est assez facile de répliquer votre code pour tirer parti des nouvelles API REST. Pour plus d’informations sur l’inscription d’application et le modèle de programmation Microsoft Entra, consultez la documentation Plateforme d'identités Microsoft.

Pour plus d’informations sur le test des requêtes/réponses HTTP, consultez :

• Fiddler. Ce dernier est un proxy de débogage web gratuit capable d’intercepter vos demandes REST, facilitant ainsi le diagnostic des messages de demande/réponse HTTP.
• JWT.ms, ce qui permet de vider rapidement et facilement les revendications dans votre jeton du porteur afin que vous puissiez valider leur contenu.