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 Postman
  • Composants de base d’une paire requête/réponse d’API REST.
  • Comment inscrire votre application cliente auprès d’Azure Active Directory (Azure AD) pour sécuriser vos demandes 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

Comment appeler des API REST Azure avec Postman

La vidéo suivante vous montre comment vous authentifier rapidement auprès des API REST Azure via la méthode id client/secret. Nous vous encourageons à continuer à lire ci-dessous pour en savoir plus sur ce qui constitue une opération REST, mais si vous devez appeler rapidement les API, cette vidéo est pour vous.

Notes

La vidéo montre comment utiliser Postman avec une connexion locale. Postman, ou tout outil de test d’API qui synchronise les données dans le cloud, n’est pas recommandé si vous utilisez des jetons ou des clés d’authentification.

Vous pouvez lire la procédure complète sur le blog de Jon Gallant ici : API REST Azure avec Postman

Comment appeler des API REST Azure avec curl

Le processus décrit dans l’entrée de blog suivante est similaire à celui utilisé pour Postman, mais 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 des 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 obligatoire (é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 à Azure AD, il est retourné dans le corps de la réponse en tant qu’élément access_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 d’Azure AD

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 intervenants par Azure AD et fournit à votre client un jeton d’accès comme preuve d’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 Azure AD 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é à Azure AD avant l’exécution en l’inscrivant dans un locataire Azure AD. Avant d’inscrire votre client auprès d’Azure AD, tenez compte des prérequis suivants :

  • Si vous n’avez pas encore de locataire Azure AD, consultez Configurer un locataire Azure Active Directory.

  • Conformément à OAuth2 Authorization Framework, Azure AD 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 en toute sécurité ses propres informations d’identification lors de l’authentification Azure AD 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 Azure AD 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 Azure Active Directory.

Vous êtes maintenant prêt à inscrire votre application cliente auprès d’Azure AD.

Inscription du client

Pour inscrire un client qui accède à une API REST Azure Resource Manager, consultez Utiliser le portail pour créer une application Active Directory et un 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 d’Azure AD.
  • 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 à :

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 auprès d’Azure AD, car vous en avez besoin pour assembler l’en-tête de votre message de requête.

Obtenir un jeton d’accès

Une fois que vous avez une inscription client valide, vous disposez de deux façons d’intégrer à Azure AD 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 points de terminaison OAuth Azure AD. La seule exigence est que vous puissiez envoyer/recevoir des requêtes HTTPS à partir d’Azure AD 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 Azure AD 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 à Azure AD. 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 par une 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 passez 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 Azure Resource Manager (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 ressources dans le Portail Azure. Pour plus d’informations, consultez la identifierUris propriété de l’objet d’application Microsoft API Graph.

    La demande adressée au point de /authorize terminaison déclenche d’abord une invite de connexion pour authentifier l’utilisateur. La réponse que vous récupérez 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 échanger le code d’autorisation contre un jeton d’accès. Pour plus d’informations sur le format de la requête POST HTTPS adressée au point de terminaison et sur les /token exemples de requête/réponse, consultez Demander un jeton d’accès. Étant donné qu’il s’agit d’une requête POST, vous empaquetez vos paramètres spécifiques à l’application dans le corps de la requête. 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 de clé/secret que vous avez générée précédemment, lors de l’inscription du client.

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

Cet 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 cet octroi sont similaires à l’étape 2 de l’octroi de code d’autorisation. Pour plus d’informations sur le format de la demande POST HTTPS sur le point de /token terminaison et des 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 des frameworks et environnements de script facilitent l’assemblage et l’envoi du message de demande. Ils fournissent généralement une classe ou une API web/HTTP qui extrait la création ou la mise en forme de la requête, ce qui facilite l’écriture du code client (la classe HttpWebRequest dans .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 demande.

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 demande et à la réponse un canal sécurisé. Les informations (c’est-à-dire le code d’autorisation Azure AD, le jeton d’accès/porteur et les données sensibles de demande/réponse) 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 la ressource et tous les paramètres de chaîne de requête requis) sont déterminés par sa spécification d’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 demande est groupé dans l’en-tête du message de requête, ainsi que tous 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 demande, comme acquis précédemment auprès d’Azure AD.
  • 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 requête 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 d’API pour le service que vous demandez spécifie également l’encodage et le format.

Le corps de la requête 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 requête 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 Azure Resource Manager à l’aide de champs d’en-tête de requête similaires à ce qui suit (notez que le corps de la demande 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 Azure Resource Manager, 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 :

{
    "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 PUT HTTPS, vous devez recevoir un en-tête de réponse semblable à ce qui suit, confirmant que votre opération PUT d’ajout de « 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 champs d’en-tête de réponse Content-Type etContent-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 requêtes. 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 seule 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 :

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

Pour obtenir la page suivante des résultats, envoyez une demande GET à l’URL de la propriété nextLink. L’URL inclut un jeton de continuation pour indiquer où vous ê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.

Vous avez terminé. Une fois que vous avez inscrit votre application Azure AD 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 Azure AD, 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.