Table of contents
TOC
Collapse the table of content
Expand the table of content
Última actualización: 20/06/2018

Crear aplicaciones web JavaScript usando CORS para acceder a las API de Office 365

Se aplica a: Office 365

Las API de Office 365 proporcionan acceso a correo, calendarios y contactos de Exchange Online; archivos y carpetas de SharePoint Online y OneDrive para la Empresa; usuarios y grupos de Azure AD.

Es posible acceder a todos estos datos desde una aplicación cliente JavaScript con prácticamente ningún código de servidor, o sin código de servidor, mediante el uso compartido de recursos entre orígenes (CORS). Los programadores ahora tienen la opción de utilizar CORS para enviar solicitudes a las API de Office 365 para acceder a datos de forma segura, crearlos o modificarlos.

Antes de comenzar a utilizar las solicitudes CORS para acceder a las API de Office 365, debe configurar su entorno de desarrollo de Office 365. A continuación, le guiaremos en la habilitación de su aplicación JavaScript para realizar solicitudes CORS a las API de Office 365 con las acciones siguientes: registrar su aplicación con Azure Active Directory, determinar el extremo del recurso, obtener un token de acceso y realizar una solicitud autenticada a una API de Office 365.

Nota Para que este ejemplo funcione, Internet Explorer debe utilizar Internet Explorer 11 con MS15-032: actualización de seguridad acumulativa para Internet Explorer (KB3038314) instalado

Registrar su aplicación con Azure AD

Lo primero que debe hacer es registrar su aplicación con Azure AD. Para empezar, inicie sesión en el Portal de administración de Azure. Una vez que haya iniciado sesión, siga estas instrucciones:

  1. Haga clic en el nodo Active Directory de la columna izquierda y seleccione el directorio vinculado a su suscripción de Office 365.

  2. Seleccione la pestaña Aplicaciones y a continuación Agregar al final de la página.

  3. En el elemento emergente, seleccione Agregar una aplicación que mi organización está desarrollando.

  4. Elija un nombre para su aplicación, como o365-cors-sample y seleccione Aplicación web y/o API web como su Tipo. A continuación, haga clic en la flecha para continuar.

  5. El valor de URL de inicio de sesión es la URL donde se alojará su aplicación.

  6. La URI de id. de aplicación es un identificador único que permite a Azure AD identifcar su aplicación. Puede utilizar http: // {su_subdominio} / o365-cors-sample, donde {su_subdominio} es el subdominio de .onmicrosoft que especificó al registrarse en su sitio para desarrolladores de Office 365. A continuación, haga clic en la marca de verificación para aprovisionar su aplicación.

  7. Ahora que su aplicación se ha aprovisionado, seleccione la pestaña Configurar.

  8. Desplácese hacia abajo hasta la sección Permisos para otras aplicaciones y haga clic en el botón Agregar aplicación.

  9. En este ejemplo, demostraremos cómo obtener los archivos de un usuario, así que agregue la aplicación Office 365 SharePoint Online. Haga clic en el signo más en la fila de la aplicación y a continuación haga clic en la marca de verificación en la parte superior derecha para agregarla. A continuación, para continuar haga clic en la marca de verificación en la parte inferior.

  10. En la fila Office 365 SharePoint Online, seleccione Permisos delegados y, en la lista de selección, elija Leer archivos de los usuarios.

  11. Haga clic en Guardar para guardar la configuración de la aplicación.

Configurar su aplicación para permitir el flujo de concesión implícita de OAuth 2.0.

Para obtener un token de acceso para las solicitudes de API de Office 365, su aplicación utilizará el flujo de concesión implícita de OAuth. Debe actualizar el manifiesto de la aplicación para permitir el flujo de concesión implícita de OAuth porque de forma predeterminada no está permitido.

  1. Seleccione la pestaña Configurar de la entrada de su aplicación en el Portal de administración de Azure.

  2. Mediante el botón Administrar manifiesto del cajón, descargue el archivo de manifiesto para la aplicación y guárdelo en su equipo.

  3. Abra el archivo de manifiesto con un editor de texto. Busque la propiedad oauth2AllowImplicitFlow. De forma predeterminada está establecida en false; cámbiela a true y guarde el archivo.

  4. Mediante el botón Administrar manifiesto, suba el archivo de manifiesto actualizado.

Ya ha registrado con éxito su aplicación con Azure AD.

Determinar el extremo del recurso

Para realizar cualquier solicitud de API, deberá determinar el extremo correcto del recurso que desea usar. El extremo que utilizará dependerá de la información que desee de Office 365. Consulte la documentación de referencia de la API para obtener el extremo que desee.

Le recomendamos que aproveche Microsoft Graph cuando sea posible para acceder a todas las API desde un único extremo, https://graph.microsoft.com. Consulte la Documentación de Microsoft Graph para explorar todos los extremos admitidos.

En este ejemplo, utilizaremos la API de archivos para obtener los archivos de un usuario. El extremo de esta operación es https://{your_subdomain}-my.sharepoint.com/_api/v1.0/me/files, dónde {your_subdomain} es el subdominio de .onmicrosoft que especificó al registrarse en su sitio para desarrolladores de Office 365.

Nota si está desarrollando una aplicación multiinquilino, puede utilizar el Servicio de detección para determinar los extremos que necesitará. Sin embargo, esto no es posible en las aplicaciones JavaScript del lado cliente y requerirá un código del lado servidor.

Obtener un token de acceso de Azure

Office 365 utiliza tokens OAuth 2.0 emitidos por Azure AD para autenticar clientes JavaScript. Los tokens se obtienen mediante el flujo de concesión implícita de OAuth 2.0. Con la concesión implícita, su aplicación solicita un token de acceso a Azure AD para el usuario que ha iniciado sesión enviando al usuario a una URL de autorización donde el usuario inicia sesión con sus credenciales de Office 365 y a continuación se le redirige a la aplicación con el token de acceso en la URL.

La siguiente función compila la URL de autorización y navega a ella para comenzar el proceso de autenticación.

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 el usuario decide otorgar a su aplicación acceso a sus datos de Office 365, se los redireccionará a su aplicación con el token de acceso en la URL. La siguiente función recibe una llamada cada vez que se carga la página, busca el token de acceso en la URL y lo extrae si esta lo contiene.

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']; 

Ahora tiene un token de acceso para autenticar sus solicitudes CORS a las API de Office 365.

Realizar una solicitud autenticada a una API de Office 365

En este punto, ha registrado su aplicación con Azure AD, ha determinado el punto final correcto para el recurso al que desea acceder y se le ha otorgado un token de acceso de Azure AD. Todo lo que queda por hacer es utilizar estos elementos para realizar una solicitud HTTP a la API. Para ello, enviará un XMLHttpRequest al extremo de la API de archivos con el token de acceso de OAuth adjunto al encabezado Autorización de la solicitud.

A continuación, la función realiza la solicitud y coloca el contenido de la respuesta en un elemento DOM con un Id. igual a resultados.

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; 
  } 
}  

El objeto de respuesta de XMLHttpRequest contiene los datos de Office 365. En este ejemplo, son los archivos del usuario que ha iniciado sesión o un error que explica por qué no se ha podido completar la solicitud.

Siguientes pasos

Ya ha visto cómo habilitar su aplicación cliente JavaScript para realizar solicitudes a las API de Office 365 con CORS. Tenga en cuenta que este es un ejemplo simple de cómo puede utilizar CORS en las aplicaciones de JavaScript del lado cliente y que debe tener en cuenta ADAL JS, la biblioteca de Azure Active Directory para JavaScript, y Crear una aplicación angular con las API de Office 365 si desea compilar aplicaciones de producción a mayor escala. Esta biblioteca controlará la autenticación de Azure AD en sus aplicaciones de una sola página.

A continuación, se muestra el código fuente de este ejemplo en su totalidad para que pueda ver con más claridad cómo funcionan los elementos juntos.

Nota si desea hospedar este código de ejemplo en alguna parte, no olvide configurar los valores clientId y replyUrl en la función getToken con los valores de su aplicación que se encuentran en el Portal de administración de Azure, así como también cambiar el elemento {your-subdomain} de la variable resource a su subdominio.

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

Recursos adicionales

Ejemplos de código

Referencia

© 2018 Microsoft