Table of contents
TOC
Réduire la table des matières
Développer la table des matières
Dernière mise à jour: 20/06/2018

Créer des applications web JavaScript à l’aide de CORS pour accéder aux API Office 365

Concerne : Office 365

Les API Office 365 fournissent un accès aux messages, calendriers et contacts d’Exchange Online ; aux fichiers et dossiers de SharePoint Online et OneDrive for Business ; aux utilisateurs et groupes d’Azure AD.

Il est possible d’accéder à toutes ces données à partir d’une application client JavaScript avec très peu de code serveur en utilisant le partage de ressources cross-origin (CORS). Les développeurs ont désormais la possibilité d’utiliser CORS pour envoyer des requêtes aux API Office 365 afin d’accéder, de modifier et de créer des données de manière fiable.

Avant de commencer à utiliser les requêtes CORS pour accéder aux API Office 365, vous devez configurer votre environnement de développement Office 365. Ensuite, nous vous invitons à permettre à votre application JavaScript d’envoyer des requêtes CORS aux API Office 365 : en enregistrant votre application auprès d’Azure Active Directory, en déterminant le point de terminaison de ressource, en obtenant un jeton d’accès et en envoyant une demande authentifiée à Office 365 API.

Remarque Internet Explorer doit utiliser Internet Explorer 11 avec la mise à jour MS15-032: Mise à jour de sécurité cumulative pour Internet Explorer (KB3038314) pour que cet exemple fonctionne.

Enregistrer votre application auprès de Azure AD

La première chose à faire est d’enregistrer votre application avec Azure AD. Connectez-vous au Portail de gestion Azure pour commencer. Une fois connecté, suivez ces instructions :

  1. Cliquez sur le nœud Active Directory dans la colonne de gauche et sélectionnez le répertoire lié à votre abonnement Office 365.

  2. Sélectionnez l’onglet Applications, puis Ajouter au bas de l'écran.

  3. Dans la fenêtre qui s’ouvre, sélectionnez Ajouter une application que mon organisation développe.

  4. Choisissez un nom pour votre application, par exemple o365-cors-sampleet sélectionnez Application Web et / ou API Web pour son type. Puis cliquez sur la flèche pour continuer.

  5. La valeur de URL de connexion est l’URL où votre application sera hébergée.

  6. La valeur de URI de l’ID de l’application est un identifiant unique pour Azure AD permettant d’identifier votre application. Vous pouvez utiliser http://{votre_sous-domaine}/o365-cors-sample, où {votre_sous-domaine} est le sous-domaine de .onmicrosoft que vous avez spécifié lors de l’inscription à votre site de développeur Office 365. Puis cochez la case pour provisionner votre application.

  7. Maintenant que votre application a été provisionnée, sélectionnez l’onglet Configurer.

  8. Faites défiler jusqu'à la section autorisations à d’autres applications et cliquez sur le bouton Ajouter une application.

  9. Dans cet exemple, nous allons montrer comment obtenir les fichiers d’un utilisateur, donc ajoutez l’application Office 365 SharePoint Online. Cliquez sur le signe plus dans la ligne de l’application, puis cochez la case en haut à droite pour l’ajouter. Cochez ensuite la case en bas à droite pour continuer.

  10. Dans la ligne Office 365 SharePoint Online, sélectionnez Autorisations déléguées, et dans la liste de sélection, choisissez Lire les fichiers des utilisateurs.

  11. Cliquez sur Enregistrer pour enregistrer la configuration de l’application.

Configurez votre application pour autoriser le flux d’octroi implicite OAuth 2.0

Afin d’obtenir un jeton d’accès pour les requêtes d’API Office 365, votre application utilisera le flux d’octroi implicite OAuth. Vous devez mettre à jour le manifeste de l’application pour autoriser le flux d’octroi implicite OAuth car il n’est pas autorisé par défaut.

  1. Sélectionnez l’onglet Configurer de votre application dans le Portail de gestion Azure.

  2. En utilisant le bouton Gérer le manifeste dans le tiroir, téléchargez le fichier manifeste pour l’application et enregistrez-le sur votre ordinateur.

  3. Ouvrez le fichier manifeste avec un éditeur de texte. Recherchez la propriété oauth2AllowImplicitFlow. Par défaut, elle est sur false ; changez-la en true et sauvegardez le fichier.

  4. En utilisant le bouton Gérer le manifeste, téléchargez le fichier manifeste mis à jour.

Vous avez maintenant enregistré votre application avec Azure AD.

Déterminer le point de terminaison de la ressource

Pour effectuer des requêtes d’API, vous devez déterminer le point de terminaison correct de la ressource que vous souhaitez utiliser. Le point de terminaison que vous utiliserez est déterminé par les informations que vous voulez obtenir d’Office 365. Reportez-vous à la documentation de référence de l’API pour obtenir le point de terminaison souhaité.

Nous vous recommandons de tirer parti de Microsoft Graph lorsque cela est possible pour accéder à toutes les API à partir d’un seul point de terminaison, https://graph.microsoft.com. Se référer à la Documentation Microsoft Graph pour parcourir tous les points de terminaison pris en charge.

Pour cet exemple, nous utiliserons l’API Fichiers pour obtenir les fichiers d’un utilisateur. Le point de terminaison pour cette opération est https://{your_subdomain}-my.sharepoint.com/_api/v1.0/me/files, où {your_subdomain} est le sous-domaine de .onmicrosoft que vous avez spécifié lors de l’inscription de votre site de développeur Office 365.

Remarque Si vous développez une application multi-clients, vous pouvez utiliser le Service de découverte pour déterminer les points de terminaison dont vous aurez besoin. Cependant, cela n’est pas possible dans les applications JavaScript côté client et nécessitera du code côté serveur.

Obtenir un jeton d’accès d’Azure

Office 365 utilise des jetons OAuth 2.0 émis par Azure AD pour authentifier les clients JavaScript. Les jetons sont obtenus en utilisant le flux de d’octroi implicite OAuth 2.0. En utilisant l’octroi implicite, votre application demande un jeton d’accès à Azure AD pour l’utilisateur actuellement connecté en envoyant l’utilisateur vers une URL d’autorisation où l’utilisateur se connecte avec ses informations d’identification Office 365 puis est redirigé vers l’application avec le jeton d’accès dans l’URL.

La fonction suivante crée l’URL d’autorisation et y accède pour commencer le processus d’authentification.

function requestToken() { 
  // Change clientId and replyUrl to reflect your app's values 
  // found on the Configure tab in the Azure Management Portal. 
  // Also change {your_subdomain} to your subdomain for both endpointUrl and resource. 
  var clientId    = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX';
  var replyUrl    = 'http://replyUrl/'; 
  var endpointUrl = 'https://{your_subdomain}-my.sharepoint.com/_api/v1.0/me/files';
  var resource = "https://{your_subdomain}-my.sharepoint.com"; 

  var authServer  = 'https://login.windows.net/common/oauth2/authorize?';  
  var responseType = 'token'; 

  var url = authServer + 
            "response_type=" + encodeURI(responseType) + "&" + 
            "client_id=" + encodeURI(clientId) + "&" + 
            "resource=" + encodeURI(resource) + "&" + 
            "redirect_uri=" + encodeURI(replyUrl); 

  window.location = url; 
}

Si l’utilisateur choisit d’accorder à votre application l’accès à ses données Office 365, celles-ci seront redirigées vers votre application avec le jeton d’accès dans l’URL. La fonction ci-dessous est appelée chaque fois que la page se charge et vérifie le jeton d’accès dans l'URL et l’extrait s’il est présent.

var urlParameterExtraction = new (function () { 
  function splitQueryString(queryStringFormattedString) { 
    var split = queryStringFormattedString.split('&'); 

    // If there are no parameters in URL, do nothing.
    if (split == "") {
      return {};
    } 

    var results = {}; 

    // If there are parameters in URL, extract key/value pairs. 
    for (var i = 0; i < split.length; ++i) { 
      var p = split[i].split('=', 2); 
      if (p.length == 1) 
        results[p[0]] = ""; 
      else 
        results[p[0]] = decodeURIComponent(p[1].replace(/\+/g, " ")); 
    } 

    return results; 
  } 

  // Split the query string (after removing preceding '#'). 
  this.queryStringParameters = splitQueryString(window.location.hash.substr(1)); 
})(); 

// Extract token from urlParameterExtraction object.
var token = urlParameterExtraction.queryStringParameters['access_token']; 

Vous disposez maintenant d’un jeton d’accès pour authentifier vos requêtes CORS auprès des API Office 365.

Effectuer une requête authentifiée auprès d’une API Office 365

À ce stade, vous avez enregistré votre application auprès d’Azure AD, déterminé le point de terminaison approprié pour la ressource à laquelle vous souhaitez accéder et vous avez obtenu un jeton d’accès par Azure AD. Tout ce qu’il reste à faire est d’utiliser ces éléments pour faire une requête HTTP à l’API. Vous le ferez en envoyant un XMLHttpRequest au point de terminaison de l’API Fichiers avec le jeton d’accès OAuth attaché à l’en-tête Authorization de la requête.

La fonction ci-dessous fait la requête et met le contenu de la réponse dans un élément DOM avec un ID égal aux résultats.

function getFilesFromO365() { 
  try 
  { 
    var endpointUrl = 'https://{your_subdomain}-my.sharepoint.com/_api/v1.0/me/files'; 
    var xhr = new XMLHttpRequest(); 
    xhr.open("GET", endpointUrl); 

    // The APIs require an OAuth access token in the Authorization header, formatted like this: 'Authorization: Bearer <token>'. 
    xhr.setRequestHeader("Authorization", "Bearer " + token); 

    // Process the response from the API.  
    xhr.onload = function () { 
      if (xhr.status == 200) { 
        var formattedResponse = JSON.stringify(JSON.parse(xhr.response), undefined, 2);
        document.getElementById("results").textContent = formattedResponse; 
      } else { 
        document.getElementById("results").textContent = "HTTP " + xhr.status + "<br>" + xhr.response; 
      } 
    } 

    // Make request.
    xhr.send(); 
  } 
  catch (err) 
  {  
    document.getElementById("results").textContent = "Exception: " + err.message; 
  } 
}  

L’objet de réponse du XMLHttpRequest contient les données Office 365. Dans cet exemple, il s’agit des fichiers de l’utilisateur connecté ou d’une erreur expliquant pourquoi la requête n’a pas pu aboutir.

Étapes suivantes

Vous avez maintenant vu comment activer votre application client JavaScript pour envoyer des requêtes aux API Office 365 à l’aide de CORS. Notez qu'il s'agit d'un exemple simple sur la façon dont vous pouvez utiliser CORS dans les applications JavaScript côté client et que vous devriez également vous renseigner sur ADAL JS, la bibliothèque Azure Active Directory pour JavaScript, et Créer une application Angular avec les API Office 365 si vous voulez construire des applications de production à plus grande échelle. Cette bibliothèque gérera pour vous l’authentification Azure AD dans vos applications d’une seule page.

Ci-dessous se trouve le code source de cet exemple dans son intégralité afin que vous puissiez avoir une idée plus claire sur la façon dont les éléments fonctionnent ensemble.

Remarque Si vous voulez héberger cet exemple de code quelque part, n’oubliez pas de configurer les valeurs clientId et replyUrl dans la fonction getToken en leur donnant les valeurs de votre application trouvées dans le Portail de gestion Azure, ainsi que donner à la partie {your-subdomain} de la variable resource le nom de votre sous-domaine.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <title>O365 CORS Sample</title>
    <style> 
      body { 
        font-family:'Segoe UI'; 
      } 

      .paddedElement {
        margin-top: 5px; 
      }

      .hidden {
        visibility: hidden; 
      }
    </style>
  </head>
  <body>
    <h2>O365 CORS Sample</h2>
    <label for="TxtOauthToken">OAuth Token: </label><input type="text" id="TxtOauthToken" size="80"/>
    <br />
    <label for="endpointUrl">Endpoint URL: </label><input type="text" id="endpoint" size="80" /> 
    <br />
    <input type="button" class="paddedElement" id="getToken" value="Get Token"> 
    <input type="button" class="paddedElement" id="doCors" value="Make CORS Request" visibility="hidden" />
    <br /> 
    <br />
    <label for="results" class="hidden paddedElement" id="resultHeading">Results: </label>
    <br />
    <label id="debugMessage"></label>
    <pre id="results"></pre>
    <script type="text/javascript"> 
      (function (window) { 
        var isCorsCompatible = function() {
          try
          {
              var xhr = new XMLHttpRequest();
              xhr.open("GET", getEndpointUrl());
              xhr.setRequestHeader("authorization", "Bearer " + token);
              xhr.setRequestHeader("accept", "application/json");
              xhr.onload = function () {
                 // CORS is working.
                 console.log("Browser is CORS compatible."); 
              }
              xhr.send();
          }
          catch (e)
          {
              if (e.number == -2147024891)
              {
                  console.log("Internet Explorer users must use Internet Explorer 11 with MS15-032: Cumulative security update for Internet Explorer (KB3038314) installed for this sample to work.");
              }
              else
              {
                  console.log("An unexpected error occurred. Please refresh the page."); 
              }

          }
        };

        var urlParameterExtraction = new (function () { 
          function splitQueryString(queryStringFormattedString) { 
            var split = queryStringFormattedString.split('&'); 

            // If there are no parameters in URL, do nothing.
            if (split == "") {
              return {};
            } 

            var results = {}; 

            // If there are parameters in URL, extract key/value pairs. 
            for (var i = 0; i < split.length; ++i) { 
              var p = split[i].split('=', 2); 
              if (p.length == 1) 
                results[p[0]] = ""; 
              else 
                results[p[0]] = decodeURIComponent(p[1].replace(/\+/g, " ")); 
            } 

            return results; 
          } 

          // Split the query string (after removing preceding '#'). 
          this.queryStringParameters = splitQueryString(window.location.hash.substr(1)); 
        })(); 

        var token = urlParameterExtraction.queryStringParameters['access_token']; 

        if (token == undefined) {
          document.getElementById("TxtOauthToken").value = "Click \"Get Token\" to trigger sign-in after entering the endpoint you want to use."; 

          document.getElementById("doCors").style.visibility = "hidden"; 
        }
        else {
          document.getElementById("TxtOauthToken").value = token;
          document.getElementById("doCors").style.visibility = "visible"; 
          document.getElementById("getToken").style.display = "none"; 
        }

        // Constructs the authentication URL and directs the user to it. 
        function requestToken() { 
          // Change clientId and replyUrl to reflect your app's values 
          // found on the Configure tab in the Azure Management Portal.
          var clientId    = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX';
          var replyUrl    = 'http://replyUrl/';
          var resource    = "https://{your_domain}-my.sharepoint.com";

          var authServer  = 'https://login.windows.net/common/oauth2/authorize?'; 
          var endpointUrl = getEndpointUrl();

          var responseType = 'token'; 

          var url = authServer + 
                    "response_type=" + encodeURI(responseType) + "&" + 
                    "client_id=" + encodeURI(clientId) + "&" + 
                    "resource=" + encodeURI(resource) + "&" + 
                    "redirect_uri=" + encodeURI(replyUrl); 

          window.location = url; 
        } 

        document.getElementById("getToken").onclick = requestToken; 

        function getEndpointUrl() { 
          return document.getElementById("endpoint").value; 
        } 

        function getFilesFromO365() { 
          document.getElementById("results").textContent = ""; 

          // Check browser compatbility. Check console output for details.
          isCorsCompatible(); 

          try 
          { 
            var xhr = new XMLHttpRequest(); 
            xhr.open("GET", getEndpointUrl()); 

            // The APIs require an OAuth access token in the Authorization header, formatted like this: 'Authorization: Bearer <token>'. 
            xhr.setRequestHeader("Authorization", "Bearer " + token); 

            // Process the response from the API.  
            xhr.onload = function () { 
              document.getElementById("resultHeading").style.visibility = "visible"; 

              if (xhr.status == 200) { 
                var formattedResponse = JSON.stringify(JSON.parse(xhr.response), undefined, 2);
                document.getElementById("results").textContent = formattedResponse; 
              } else { 
                document.getElementById("results").textContent = "HTTP " + xhr.status + "<br>" + xhr.response; 
              } 
            } 

            // Make request.
            xhr.send(); 
          } 
          catch (err) 
          { 
            document.getElementById("resultHeading").style.visibility = "visible"; 
            document.getElementById("results").textContent = "Exception: " + err.message; 
          } 
        } 

        document.getElementById("doCors").onclick = getFilesFromO365; 

      })(window); 
    </script> 
  </body>
</html>

Ressources supplémentaires

Exemples de code

Référence

© 2018 Microsoft