Référence de l'API REST Azure

  • Article

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

Les API REST (Representational State Transfer) sont des points de terminaison de service qui prennent en charge des ensembles d’opérations HTTP (méthodes), qui fournissent un accès de création/récupération/mise à jour/suppression aux ressources du service. Les sections ci-dessous vous guident à travers :

  • 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 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

Notes

La plupart des API REST de service Azure ont une bibliothèque de sdk client correspondante, qui gère une grande partie du code client pour vous. Consultez l'article :

Kit de développement logiciel (SDK) .NET Azure
Kit de développement logiciel (SDK) Java Azure
Kit de développement logiciel (SDK) Azure CLI 2.0

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

Une paire requête/réponse d’API REST peut être séparée en 5 composants :

  1. L’URI de demande, qui se compose de : {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Notez que nous l’appelons séparément ici, car la plupart des langages/frameworks vous obligent à le transmettre séparément du message de demande, mais il est en fait inclus dans l’en-tête du message de demande.
    • Schéma d’URI : indique le protocole utilisé pour transmettre la requête. Par exemple, http ou https.
    • Hôte URI : nom de domaine ou adresse IP du serveur sur lequel le point de terminaison de service REST est hébergé, par exemple, 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 des propriétaires d’une application spécifique au sein de la collection d’applications.
    • Chaîne de requête (facultatif) : utilisée pour fournir des paramètres simples supplémentaires, tels que la version de l’API, les critères de sélection des ressources, etc.
  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.
    • Champs d’en-tête supplémentaires facultatifs requis par 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 encodés en MIME passés en tant que paramètres complexes. Le type d’encodage MIME pour le corps doit également être spécifié dans l’en-tête Content-type de requête, pour les opérations POST/PUT. Notez que certains services nécessitent l’utilisation d’un type MIME spécifique, tel que application/json.
  4. Champs d’en-tête de message de réponse HTTP
    • Un code http status, allant des codes de réussite 2xx aux codes d’erreur 4xx/5xx. Ou bien un code d’état défini par le service peut être retourné, comme indiqué dans la documentation de l’API.
    • Champs d’en-tête supplémentaires facultatifs nécessaires pour prendre en charge la réponse de la demande, comme un Content-type en-tête de réponse.
  5. 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. En règle générale, ils sont retournés dans un format structuré au format JSON ou XML, comme indiqué par l’en-tête de Content-type réponse. Par exemple, lors de la demande d’un jeton d’accès auprès d’Azure AD, il est retourné dans le corps de la réponse en tant qu’élément, l’un access_token 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 sera également inclus.

Inscrire votre application cliente auprès d’Azure AD

La plupart des services Azure (tels que les fournisseurs Azure Resource Manager et les API de gestion des services classiques) 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 Azure AD, qui fournit à votre client un jeton d’accès comme preuve de l’authentification/autorisation. Le jeton est ensuite envoyé au service Azure dans l’en-tête Autorisation HTTP de toutes les 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, vous pouvez passer à 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. Vous trouverez ci-dessous une liste d’éléments à prendre en compte avant d’inscrire votre client auprès d’Azure AD :

  • Si vous n’avez pas encore de locataire Azure AD, consultez Comment obtenir un locataire Azure Active Directory.
  • Selon OAuth2 Authorization Framework, Azure AD prend en charge 2 types de clients. La compréhension de chacune d’elles vous aidera à décider qui est le plus approprié pour votre scénario :
    • Les clients web/confidentiels (exécutés sur un serveur web) peuvent accéder aux ressources sous leur propre identité (c’est-à-dire: service/démon), ou obtenir une autorisation déléguée pour accéder aux ressources sous l’identité de l’utilisateur connecté (par exemple, application web). Seul un client web a la possibilité de gérer et de 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 (installés/exécutés sur un appareil) peuvent uniquement accéder aux ressources 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 2 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 Les objets Application et principal de service dans Azure Active Directory.

Nous sommes maintenant prêts à inscrire votre application cliente auprès d’Azure AD.

Inscription du client

Pour inscrire un client qui accédera à 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 pour obtenir des instructions d’inscription pas à pas. Cet article (également disponible dans les versions PowerShell et CLI pour automatiser l’inscription) vous explique comment :

  • inscrire l’application cliente auprès d’Azure AD
  • définir les demandes d’autorisation pour autoriser le client à accéder à l’API Azure Resource Manager
  • configurer les paramètres RBAC (Role Based Access Control) d’Azure Resource Manager pour autoriser le client

Pour tous les autres clients, consultez Intégration d’applications à Azure Active Directory. Cette article vous explique comment :

  • inscrire l’application cliente auprès d’Azure AD, dans la section « Ajout d’une application »
  • créer une clé secrète (si vous inscrivez un client web), dans la section « Mise à jour d’une application »
  • ajouter des demandes d’autorisation comme requis par l’API, dans la section « Mise à jour d’une application »

Maintenant que vous avez terminé l’inscription de votre application cliente, nous pouvons passer à votre code client, où vous allez créer la requête REST et gérer la réponse.

Créer la requête

Cette section couvre les 3 premiers des 5 composants que nous avons abordés précédemment. Tout d’abord, nous devons acquérir le jeton d’accès d’Azure AD, que nous utiliserons pour assembler notre en-tête de message de demande.

Obtenir un jeton d’accès

Une fois que vous avez une inscription client valide, il existe essentiellement 2 façons d’intégrer à Azure AD pour acquérir un jeton d’accès :

  • Points de terminaison de service OAuth2 neutres sur la plateforme/la langue d’Azure AD, ce que nous allons utiliser. Tout comme les points de terminaison d’API REST Azure que vous utilisez, les instructions fournies dans cette section ne font aucune hypothèse concernant la plateforme ou le langage/script de votre client lors de l’utilisation des points de terminaison Azure AD ; uniquement qu’il peut envoyer/recevoir des requêtes HTTPS vers/à partir d’Azure AD et analyser le message de réponse.
  • Bibliothèques d’authentification Microsoft (MSAL) spécifiques à la plateforme/au langage. Les bibliothèques fournissent des wrappers asynchrones pour les demandes de point de terminaison OAuth2 et des fonctionnalités de gestion des jetons robustes telles que la mise en cache et la gestion des jetons d’actualisation. Pour plus d’informations, notamment la documentation de référence, les téléchargements de bibliothèque et les exemples de code, consultez Bibliothèques d’authentification Microsoft.

Les 2 points de terminaison Azure AD que vous utiliserez 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. Dans le cadre de cet article, nous partons du principe que votre client utilisera l’un des flux d’octroi d’autorisation suivants : code d’autorisation ou informations d’identification du client. Suivez les instructions de celui qui correspond le mieux à votre scénario pour acquérir le jeton d’accès que vous utiliserez dans les sections restantes.

Octroi de code d’autorisation (clients interactifs)

Cet octroi peut être utilisé à la fois par les clients web et natifs, et nécessite 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. Consultez Demander un code d’autorisation pour plus d’informations sur le format de la requête GET HTTPS sur le /authorize point de terminaison, ainsi que des exemples de messages de demande/réponse. L’URI contient des paramètres de chaîne de requête, notamment les suivants qui sont spécifiques à votre application cliente :

    • client_id - également appelé ID d’application, il s’agit du GUID affecté à votre application cliente lorsque vous vous êtes inscrit dans la section ci-dessus

    • redirect_uri - une version encodée par l’URL de [l’un des] URI de réponse/redirection spécifiés lors de l’inscription de votre application cliente. Notez que la valeur que vous passez doit correspondre exactement à votre inscription !

    • resource - un 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 de fournisseur Azure Resource Manager (et de gestion des services classiques) utilisenthttps://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 également la identifierUris propriété de l’objet d’application Azure AD.

    La demande adressée au point de /authorize terminaison déclenche d’abord une invite de connexion pour authentifier l’utilisateur final. La réponse que vous obtenez sera 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, qui contient l’URI de redirection suivi d’un code paramètre de requête, contenant le code d’autorisation dont vous aurez besoin pour l’étape #2.

  2. Ensuite, votre client doit échanger le code d’autorisation contre un jeton d’accès. Consultez Utiliser le code d’autorisation pour demander un jeton d’accès pour plus d’informations sur le format de la demande POST HTTPS sur le /token point de terminaison, ainsi que des exemples de messages de demande/réponse. Étant donné qu’il s’agit d’une requête POST, vous allez cette fois empaqueter vos paramètres spécifiques à l’application dans le corps de la requête. En plus de celles mentionnées ci-dessus (ainsi que d’autres nouvelles), vous passerez :

    • code - il s’agit du paramètre de requête qui contiendra le code d’autorisation que vous avez obtenu à l’étape #1.
    • client_secret - vous n’aurez besoin de ce paramètre que si votre client est configuré en tant qu’application web. Il s’agit de la même valeur de secret/clé que vous avez générée précédemment, dans l’inscription du client.

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

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

Les interactions client/ressource pour cet octroi sont très similaires à l’étape 2 de l’octroi de code d’autorisation. Consultez la section « Demander un jeton d’accès » dans Appels de service à service à l’aide des informations d’identification du client pour plus d’informations sur le format de la demande HTTPS POST adressée au /token point de terminaison, ainsi que des exemples de messages de demande/réponse.

Assembler le message de requête

Notez que la plupart des langages/frameworks de programmation et des 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/la mise en forme de la requête, ce qui facilite l’écriture du code client (par exemple, la classe HttpWebRequest dans le .NET Framework). Par souci de concision, nous aborderons uniquement les éléments importants de la demande, étant donné que la plupart de ces éléments seront gérés pour vous.

URI de demande

Toutes les requêtes REST sécurisées nécessitent le protocole HTTPS pour le schéma d’URI, ce qui fournit à la demande et à la réponse un canal sécurisé, en raison du fait que des informations sensibles sont transmises/reçues. Ces informations (c’est-à-dire le code d’autorisation Azure AD, le jeton d’accès/du porteur, 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 ressource et tous les paramètres de chaîne de requête requis) sera déterminé par la spécification d’API REST associée. Par exemple, les API de fournisseur Azure Resource Manager utilisent https://management.azure.com/, les API Azure Service Management classiques utilisent https://management.core.windows.net/, les deux nécessitent un paramètre de api-version chaîne de requête, etc.

En-tête de requête

L’URI de requête est regroupé dans l’en-tête du message de requête, ainsi que tous les champs supplémentaires déterminés par la spécification de l’API REST de votre service et la spécification HTTP. Voici quelques champs d’en-tête courants dont vous pourriez avoir besoin dans votre demande :

  • Authorization: contient le jeton du porteur OAuth2 pour sécuriser la demande, comme acquis précédemment auprès d’Azure AD
  • Content-Type: est 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: il s’agit du nom de domaine ou de l’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 demande est séparé de l’en-tête par une ligne vide. Il doit être mis en forme en fonction du 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/corps du message de requête associé, vous êtes prêt à envoyer la demande au point de terminaison du service REST.

Par exemple, une méthode de requête GET HTTPS pour un fournisseur Azure Resource Manager peut être envoyée à l’aide de champs d’en-tête de requête similaires à ce qui suit, mais 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>

Et une méthode de requête PUT HTTPS pour un fournisseur Azure Resource Manager peut être envoyée à l’aide de champs d’en-tête ET de corps de la requête similaires à ce qui suit :

PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/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

Nous allons maintenant terminer avec les 2 derniers des 5 composants.

Pour traiter la réponse, vous devez analyser 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 ci-dessus, nous avons 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, nous devons recevoir des champs d’en-tête de réponse similaires aux suivants :

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

et un corps de réponse, contenant la liste des abonnements Azure et leurs propriétés individuelles encodées au format JSON, comme :

{
    "value":[
        {
        "id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
        "subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
        "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, nous devons recevoir un en-tête de réponse similaire à ce qui suit, confirmant que notre opération PUT d’ajout de « ExampleResourceGroup » a réussi :

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

et un corps de réponse, confirmant le contenu de notre groupe de ressources nouvellement ajouté encodé au format JSON, semblable à :

{
    "id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

Comme pour la requête, la plupart des langages/frameworks de programmation 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 serez intéressé par la confirmation du code HTTP status dans l’en-tête de réponse et, si elle est réussie, l’analyse du 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).

Et voilà ! Une fois que votre application Azure AD est inscrite et que vous disposez d’une technique en composants pour acquérir un jeton d’accès et créer et traiter des requêtes HTTP, il est assez facile de répliquer votre code pour tirer parti des nouvelles API REST.

Contenu connexe

  • Consultez Plateforme d'identités Microsoft (Azure Active Directory pour les développeurs) pour plus d’informations sur l’inscription des applications et le modèle de programmation Azure AD, y compris un index complet des articles HowTo et Démarrage rapide, ainsi que des exemples de code.
  • Pour tester les requêtes/réponses HTTP, case activée
    • Fiddler. Fiddler est un proxy de débogage web gratuit qui peut intercepter vos requêtes REST, ce qui facilite le diagnostic des messages de requête et de réponse HTTP.
    • Décodeur et JWT.io JWT, qui permettent de vider rapidement et facilement les revendications dans votre jeton du porteur afin que vous puissiez valider leur contenu.

Utilisez la section Commentaires LiveFyre qui suit cet article pour fournir des commentaires et nous aider à affiner et à façonner notre contenu.