Référence de l'API REST Azure

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 create/retrieve/update/delete aux ressources du service. Les sections ci-dessous vous guident dans les étapes suivantes :

  • Composants de base d’une paire de requêtes/réponses d’API REST
  • Comment inscrire votre application cliente avec 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

Notes

La plupart des API REST du 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 de demandes/réponses 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 nécessitent que vous transmettiez cela séparément du message de requête, mais qu’il est en fait inclus dans l’en-tête du message de requête.
    • Schéma d’URI : indique le protocole utilisé pour transmettre la requête. Par exemple, http ou https.
    • Hôte d’URI : nom de domaine ou adresse IP du serveur où le point de terminaison de service REST est hébergé, tel que graph.microsoft.com
    • Chemin d’accès aux ressources : 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 dans 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 quel type d’opération 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 de porteur contenant des informations d’autorisation 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 MIME passés sous forme de 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 vous obligent à utiliser un type MIME spécifique, tel que application/json.
  4. Champs d’en-tête de message de réponse HTTP
    • Code d’état HTTP, 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 comme requis pour prendre en charge la réponse de la demande, comme un Content-type en-tête de réponse.
  5. Champs de corps du message de réponse HTTP facultatifs
    • Les objets de réponse codé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, ces éléments sont retournés dans un format structuré en tant que JSON ou XML, comme indiqué par l’en-tête Content-type de réponse. Par exemple, lors de la demande d’un jeton d’accès à partir de Azure AD, il est retourné dans le access_token corps de la réponse en tant qu’élément, l’un de plusieurs objets appairés nom/valeur dans une collection de données. Dans cet exemple, un en-tête de réponse est Content-Type: application/json également inclus.

Inscrire votre application cliente avec 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 d’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 intégrée Azure AD ou que 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. Voici une liste d’éléments à prendre en compte avant d’inscrire votre client avec Azure AD :

  • Si vous n’avez pas encore de locataire Azure AD, consultez Comment obtenir un locataire Azure Active Directory.
  • Par OAuth2 Authorization Framework, Azure AD prend en charge 2 types de clients. Comprendre chacun 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é (par exemple: 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 maintenir 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, à l’aide de 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 sur la façon dont ils sont utilisés au moment de l’exécution, consultez les objets Application et principal de service dans Azure Active Directory.

Maintenant, nous sommes prêts à inscrire votre application cliente avec 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 pour obtenir des instructions d’inscription pas à pas. Cet article (également disponible dans les versions PowerShell et CLI pour automatiser l’inscription) vous montre comment :

  • inscrire l’application cliente avec Azure AD
  • définir des demandes d’autorisation pour permettre au client d’accéder à l’API Azure Resource Manager
  • configurer les paramètres de Access Control (RBAC) d’Azure Resource Manager pour autoriser le client

Pour tous les autres clients, reportez-vous à l’intégration d’applications à Azure Active Directory. Cette article vous explique comment :

  • inscrire l’application cliente avec 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 selon les besoins de 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 décrit les 3 premiers composants que nous avons abordés précédemment. Tout d’abord, nous devons acquérir le jeton d’accès à partir de 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 cliente valide, il existe essentiellement 2 façons d’intégrer à Azure AD pour acquérir un jeton d’accès :

  • Azure AD les points de terminaison de service OAuth2 neutres en langage/plateforme, c’est-à-dire ce que nous utiliserons. Tout comme les points de terminaison d’API REST Azure que vous utilisez, les instructions fournies dans cette section ne font aucune hypothèse sur 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/depuis Azure AD et analyser le message de réponse.
  • Bibliothèques d’authentification Microsoft spécifiques à la plateforme/langage (MSAL). 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èques et les exemples de code, consultez les 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. La façon dont vous les utilisez 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 supposons que votre client utilise l’un des flux d’octroi d’autorisation suivants : code d’autorisation ou informations d’identification du client. Suivez les instructions de celle 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)

Cette octroi peut être utilisée par des 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 /authorize point de terminaison pour obtenir un code d’autorisation (en réponse à la connexion/consentement de l’utilisateur), suivi du /token point de terminaison pour échanger le code d’autorisation pour un jeton d’accès.

  1. Tout d’abord, votre client doit demander un code d’autorisation à partir de Azure AD. Consultez Demander un code d’autorisation pour plus d’informations sur le format de la requête HTTPS GET sur le /authorize point de terminaison, ainsi que des exemples de messages de requête/réponse. L’URI contient des paramètres de chaîne de requête, notamment les éléments suivants spécifiques à votre application cliente :

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

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

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

      • Les API du 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 ressource dans le Portail Azure. Pour plus d’informations, consultez également la identifierUris propriété de l’objet application Azure AD.

    La demande adressée au /authorize point de terminaison déclenche d’abord une invite de connexion pour authentifier l’utilisateur final. La réponse que vous récupérez 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 utiliser le code d’autorisation pour 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 requête HTTPS POST sur le /token point de terminaison, ainsi que des exemples de messages de requête/réponse. Étant donné qu’il s’agit d’une requête POST, cette fois, vous allez empaqueter vos paramètres spécifiques à l’application dans le corps de la requête. En plus de certains des éléments mentionnés ci-dessus (ainsi que d’autres nouveaux), 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 secrète/clé que celle que vous avez générée précédemment dans l’inscription du client.

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

Cette octroi ne peut être utilisée 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, fournies au moment de l’inscription. Il est généralement utilisé par des clients non interactifs (aucune interface utilisateur) s’exécutant en tant que démon/service, et nécessite uniquement le /token point de terminaison pour acquérir un jeton d’accès.

Les interactions client/ressource pour cette 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 Service to service calls using client credentials for details on the format of the HTTPS POST request to the /token endpoint, and example request/response messages.

Assembler le message de demande

Notez que la plupart des langages/frameworks de programmation et des environnements de script facilitent l’assemblage et l’envoi du message de requête. Ils fournissent généralement une classe web/HTTP ou une API 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 la .NET Framework). Pour la concision, nous ne couvrirons que les éléments importants de la demande, étant donné que la plupart de ces éléments seront traité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, en fournissant la demande et la réponse avec un canal sécurisé, en raison du fait que les informations sensibles sont transmises/reçues. Ces informations (par exemple, le code d’autorisation Azure AD, le jeton d’accès/porteur, les données de requête/réponse sensibles) sont chiffrées par une couche de transport inférieure, ce qui garantit la confidentialité des messages.

Le reste de l’URI de requête de votre service (l’hôte, le chemin d’accès aux ressources et les paramètres de chaîne de requête requis) sera déterminé par sa spécification d’API REST associée. Par exemple, les API de fournisseur Azure Resource Manager utilisenthttps://management.azure.com/, les API de gestion des services Azure classiques utilisenthttps://management.core.windows.net/, les deux nécessitent un api-version paramètre de 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 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 avez besoin dans votre demande :

  • Authorization: contient le jeton du porteur OAuth2 pour sécuriser la requête, comme acquis précédemment à partir de 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: il s’agit du nom de domaine ou de l’adresse IP du serveur où 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, selon l’opération spécifique que vous demandez et ses exigences de paramètre. S’il est 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 requête est séparé de l’en-tête par une ligne vide, doit être mis en forme par champ Content-Type d’en-tête. Un exemple de corps mis en forme « 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 HTTPS GET 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 HTTPS PUT pour un fournisseur d’Resource Manager Azure peut être envoyée à l’aide de champs d’en-tête et de corps de 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

Maintenant, nous allons terminer avec les 2 derniers composants de 5.

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 pour un utilisateur. En supposant que la réponse a réussi, nous devons recevoir des champs d’en-tête de réponse similaires à ce qui suit :

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 suit :

{
    "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 pour ajouter « 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, comme suit :

{
    "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 en suivant la demande, ce qui vous permet de le traiter dans un format typé/structuré. Principalement, vous serez intéressé à confirmer le code d’état HTTP dans l’en-tête de réponse, et s’il est réussi, analysez 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).Content-Length

Et voilà ! Une fois votre application Azure AD inscrite et une technique composantée 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.

  • 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 QuickStart et des exemples de code.
  • Pour tester les requêtes/réponses HTTP, consultez
    • 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 JWT et JWT.io, ce qui facilite le vidage des revendications dans votre jeton du porteur afin de pouvoir valider leur contenu.

Utilisez la section commentaires LiveFyre qui suit cet article pour fournir des commentaires et nous aider à affiner et à mettre en forme notre contenu.