Cómo obtener acceso a los datos de SharePoint desde complementos con la biblioteca entre dominios

Al compilar complementos de SharePoint, normalmente tiene que incorporar datos de orígenes diferentes. En cambio, por motivos de seguridad, hay mecanismos de bloqueo que impiden la comunicación con más de un dominio a la vez. Estos mecanismos de seguridad se implementan en la mayoría de los exploradores, lo que dificulta o imposibilita realizar llamadas del lado cliente entre dominios.

Cuando un usuario solicita una página de su dominio de complemento, la comunicación del lado cliente se enlaza solo a ese dominio. El complemento puede emitir llamadas del lado cliente desde la página solo a otros recursos en el mismo dominio. Sin embargo, los complementos suelen requerir recursos de otros dominios, como el dominio de SharePoint, para completar sus escenarios. En el código de la página, puede intentar enviar una solicitud al dominio de SharePoint, que bloquea el explorador. Normalmente ve el error Acceso denegado. El error no implica que no tenga permisos a los recursos solicitados, sino que lo más probable es que ni pueda enviar una solicitud a los recursos mencionados.

Al usar la biblioteca entre dominios, las páginas web del complemento pueden tener acceso a datos de su dominio de complemento y del dominio de SharePoint. La biblioteca entre dominios es una alternativa del lado cliente en forma de archivo JavaScript (SP.RequestExecutor.js) que se hospeda en el sitio web de SharePoint al que puede hacer referencia en el complemento remoto. La biblioteca entre dominios le permite interactuar con más de un dominio en la página de complemento remoto mediante un proxy. Es una buena opción si quiere que el código del complemento se ejecute en el cliente en lugar de en el servidor, y si existen barreras de conectividad, como firewalls, entre SharePoint y su infraestructura remota.

Puede tener acceso a datos en la web de host, por ejemplo, puede tener acceso a las listas con las que interactúan los usuarios finales independientemente del complemento. O bien, puede tener acceso a datos en la web de complemento, como listas aprovisionadas específicamente para el complemento. Los complementos pueden obtener acceso a otros sitios web y colecciones de sitios siempre que el complemento tenga permisos con ámbito de espacio empresarial y que se haya implementado como una instalación por lotes mediante el catálogo de complementos.

El ejemplo principal de este artículo muestra cómo compilar un complemento que lee datos en la web de complemento y los muestra en una página web. La sección Pasos siguientes muestra más escenarios que se basan en el ejemplo principal.

Requisitos previos

Para seguir los ejemplos de este artículo, necesita lo siguiente:

• Visual Studio instalado de forma remota o en el equipo donde se instaló SharePoint.

• Visual Studio incluye Microsoft Office Developer Tools para Visual Studio. A veces, se lanza una versión de las herramientas entre las actualizaciones de Visual Studio. Para asegurarse de que tiene la última versión de las herramientas, ejecute el instalador de Office Developer Tools para Visual Studio 2013 o el instalador de Office Developer Tools para Visual Studio 2015.

• Un entorno de desarrollo de SharePoint local. Vea Configurar un entorno de desarrollo local para complementos de SharePoint.

Leer datos en la web de complemento con la biblioteca entre dominios

En este ejemplo, hay una página sencilla hospedada fuera de SharePoint que usa un punto de conexión de transferencia de estado presencial (REST) para leer datos en un sitio web de SharePoint (la web de complemento). Dado que la biblioteca entre dominios necesita una web de complemento, tiene sentido empezar con este escenario.

Para leer datos de la web de complemento, debe hacer lo siguiente:

1. Crear un complemento de SharePoint y proyectos web.

2. Crear elementos de lista en la web de complemento Este paso también garantiza que se cree una web de complemento cuando los usuarios implementen el complemento.

3. Crear una página de complemento que use la biblioteca entre dominios para leer los elementos de lista.

En la siguiente ilustración se muestra una página web con los datos en la web de complemento.

Para crear un complemento de SharePoint y proyectos web

1. Abra Visual Studio como administrador. (Para ello, haga clic con el botón derecho en el icono de Visual Studio del menú Inicio y seleccione Ejecutar como administrador).

2. Cree un proyecto con la plantilla Complemento para SharePoint. La plantilla Complemento para SharePoint en Visual Studio está ubicada en Plantillas>Visual C#>Office SharePoint>Complementos.

3. Especifique la dirección URL del sitio web de SharePoint que quiere usar para la depuración.

4. Seleccione Hospedado por el proveedor como la opción de hospedaje del complemento.

   Nota:

   Puede usar la biblioteca entre dominios en un complemento hospedado en SharePoint. Sin embargo, en un complemento hospedado en SharePoint, la página de complemento ya está en la web de complemento y, en este caso, no necesita que la biblioteca entre dominios lea los elementos de lista. Para ver un ejemplo de complemento hospedado en SharePoint que lea los datos en la web de host, consulte Usar la biblioteca entre dominios en un complemento hospedado en SharePoint (REST) o vea Obtener acceso a datos desde la web de host más adelante en este artículo.

Para crear elementos de lista en la web de complemento

1. Haga clic con el botón derecho en el proyecto de complemento de SharePoint en el Explorador de soluciones. Seleccione Agregar>Nuevo elemento.

2. Seleccione Elementos de Visual C#>Office/SharePoint>Lista. Asigne a la lista el nombre Anuncios.

3. Haga doble clic en Anuncios>Elements.xml. Pegue los siguientes nodos XML como elementos secundarios del elemento ListInstance.

   <Data>
       <Rows>
           <Row>
               <Field Name="Title">Lorem ipsum 1</Field>
               <Field Name="Body">Sed ut perspiciatis, unde omnis iste...</Field>
           </Row>
           <Row>
               <Field Name="Title">Lorem ipsum 2</Field>
               <Field Name="Body">Sed ut perspiciatis, unde omnis iste...</Field>
           </Row>
       </Rows>
   </Data>
   

Para crear una página de complemento que use la biblioteca entre dominios

1. Haga doble clic en Default.aspx en el proyecto web en el Explorador de soluciones.

2. Copie el siguiente código en el archivo Default.aspx. El código realiza las siguientes tareas:

   • Carga la biblioteca jQuery desde la CDN de Microsoft.

   • Proporciona un marcador de posición para el resultado.

   • Extrae la dirección URL de la web de complemento de la cadena de consulta.

   • Carga la biblioteca entre dominios JavaScript con la función getScript de jQuery.

     La función carga los recursos necesarios y luego continúa en la función especificada, garantizando que la biblioteca entre dominios se cargue y esté disponible para que la use el código subsiguiente.

   • Crea una instancia del objeto RequestExecutor. De manera predeterminada, RequestExecutor usa la web de complemento como el sitio de contexto.

     Nota:

     (REST) o el objeto (JSOM). Para obtener más información sobre AppContextSite, consulte Obtener acceso a datos desde la web de host más adelante en este artículo.

   • Emite una llamada REST al punto de conexión de los elementos de lista.

   • Controla la finalización correcta y muestra los elementos de lista en la página web.

   • Controla los errores y muestra los mensajes de error en la página web.

  
<html>
    <head>
        <title>Cross-domain sample</title>
    </head>
    <body>
        <!-- This is the placeholder for the announcements -->
        <div id="renderAnnouncements"></div>
        <script 
            type="text/javascript" 
            src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
        </script>
        <script type="text/javascript">
          var hostweburl;
          var appweburl;

          // Load the required SharePoint libraries
          $(document).ready(function () {
            //Get the URI decoded URLs.
            hostweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPHostUrl")
            );
            appweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPAppWebUrl")
            );

            // resources are in URLs in the form:
            // web_url/_layouts/15/resource
            var scriptbase = hostweburl + "/_layouts/15/";

            // Load the js files and continue to the successHandler
            $.getScript(scriptbase + "SP.RequestExecutor.js", execCrossDomainRequest);
          });

          // Function to prepare and issue the request to get
          //  SharePoint data
          function execCrossDomainRequest() {
            // executor: The RequestExecutor object
            // Initialize the RequestExecutor with the add-in web URL.
            var executor = new SP.RequestExecutor(appweburl);

            // Issue the call against the add-in web.
            // To get the title using REST we can hit the endpoint:
            //      appweburl/_api/web/lists/getbytitle('listname')/items
            // The response formats the data in the JSON format.
            // The functions successHandler and errorHandler attend the
            //      sucess and error events respectively.
            executor.executeAsync(
                {
                  url:
                      appweburl +
                      "/_api/web/lists/getbytitle('Announcements')/items",
                  method: "GET",
                  headers: { "Accept": "application/json; odata=verbose" },
                  success: successHandler,
                  error: errorHandler
                }
            );
          }

          // Function to handle the success event.
          // Prints the data to the page.
          function successHandler(data) {
            var jsonObject = JSON.parse(data.body);
            var announcementsHTML = "";

            var results = jsonObject.d.results;
            for (var i = 0; i < results.length; i++) {
              announcementsHTML = announcementsHTML +
                  "<p><h1>" + results[i].Title +
                  "</h1>" + results[i].Body +
                  "</p><hr>";
            }

            document.getElementById("renderAnnouncements").innerHTML =
                announcementsHTML;
          }

          // Function to handle the error event.
          // Prints the error message to the page.
          function errorHandler(data, errorCode, errorMessage) {
            document.getElementById("renderAnnouncements").innerText =
                "Could not complete cross-domain call: " + errorMessage;
          }

          // Function to retrieve a query string value.
          // For production purposes you may want to use
          //  a library to handle the query string.
          function getQueryStringParameter(paramToRetrieve) {
            var params =
                document.URL.split("?")[1].split("&amp;");
            var strParams = "";
            for (var i = 0; i < params.length; i = i + 1) {
              var singleParam = params[i].split("=");
              if (singleParam[0] == paramToRetrieve)
                return singleParam[1];
            }
          }
        </script>
    </body>
</html>

Para compilar y ejecutar la solución

1. Seleccione la tecla F5.

   Nota:

   Al seleccionar F5, Visual Studio compila la solución, implementa el complemento y abre la página de permisos del complemento.

2. Seleccione el botón Confiar.

3. Seleccione el icono del complemento en la página Contenidos del sitio.

Si prefiere ejemplos de código descargables, puede obtener lo siguiente de la galería de código:

• SharePoint-Add-in-REST-OData-CrossDomain
• SharePoint-Add-in-JSOM-CrossDomain.

Solución de problemas

Pasos siguientes: más escenarios de la biblioteca entre dominios

En este artículo se muestra cómo consultar un extremo de REST para leer datos de la web de complemento mediante una página de complementos que no esté hospedada en SharePoint. También puede explorar los siguientes escenarios y detalles sobre la biblioteca entre dominios.

Use JSOM para leer datos de la web de complemento

Según su preferencia, tal vez quiera usar el JSOM en lugar de REST para consultar datos de la web de complemento. Debe completar tareas adicionales para usar la biblioteca entre dominios con JSOM:

• Haga referencia a SharePoint JSOM en la página del complemento.

• Inicialice el objeto ProxyWebRequestExecutorFactory y establézcalo como la fábrica del objeto de contexto.

• Obtenga acceso a objetos de SharePoint para leer los datos de la lista.

• Cargue los objetos en el contexto y ejecute la consulta.

Para ver el ejemplo de código que muestra cómo realizar las tareas, vea SharePoint-Add-in-JSOM-CrossDomain.

Para obtener más información sobre cómo usar el JSOM, consulte Usar el modelo de objetos de JavaScript (JSOM) en complementos de SharePoint.

Obtener acceso a datos desde la web de host

En el ejemplo de esta página se muestra cómo leer datos desde la web de complemento. Esto sirve como ejemplo inicial porque la biblioteca entre dominios usa inicialmente el complemento como el sitio de contexto. Sin embargo, hay muchos escenarios en los que quiere tener acceso a datos en la web de host. Es necesario realizar algunas tareas para tener acceso a datos en la web de host:

• Establezca la web de host como el sitio de contexto para la biblioteca entre dominios.

• Proporcione permisos adecuados al complemento.

Puede cambiar el sitio de contexto mediante el punto de conexión AppContextSite (REST) o el objeto (JSOM). En el ejemplo siguiente se muestra cómo cambiar el sitio de contexto con el punto de conexión de REST:

executor.executeAsync(
    {
        url:
            appweburl +
            "/_api/SP.AppContextSite(@target)/web/title?@target='" +
            hostweburl + "'",
        method: "GET",
        headers: { "Accept": "application/json; odata=verbose" },
        success: successHandler,
        error: errorHandler
    }
);

En el ejemplo de código siguiente se muestra cómo cambiar el sitio de contexto con JSOM:

context = new SP.ClientContext(appweburl);
factory = new SP.ProxyWebRequestExecutorFactory(appweburl);
context.set_webRequestExecutorFactory(factory);
appContextSite = new SP.AppContextSite(context, hostweburl);

this.web = appContextSite.get_web();
context.load(this.web);

De manera predeterminada, el complemento tiene permisos para la web de complemento, pero no para la web de host. El siguiente ejemplo muestra una sección de manifiesto que declara una solicitud de permiso para leer datos de la web de host:

<AppPermissionRequests>
    <AppPermissionRequest 
        Scope="http://sharepoint/content/sitecollection/web" 
        Right="Read" />
</AppPermissionRequests>

Asegúrese de que crea un recurso en la web de complemento (como una lista o página vacía) para forzar el aprovisionamiento de la web de complemento, que es necesario para usar la biblioteca entre dominios.

Obtener acceso a datos en colecciones de sitios

Con la biblioteca entre dominios, puede acceder a datos en colecciones de sitios en el mismo inquilino. Hay algunas tareas que necesita completar para acceder a datos en las colecciones de sitios:

• Agregue una solicitud de permiso para acceder a datos en el inquilino.

• En el código, cambie el sitio de contexto a las colecciones de sitios que quiera consultar.

• Agregue el complemento al catálogo de complementos.

• Implemente el complemento como un complemento con ámbito de espacio empresarial en un sitio web. Para ver un ejemplo de cómo implementar un complemento con ámbito de espacio empresarial, consulte la descripción del ejemplo de código Usar la biblioteca entre dominios en un complemento con ámbito de espacio empresarial (REST).

El complemento también necesita permiso para acceder a datos del inquilino. El siguiente ejemplo muestra una sección de manifiesto que declara una solicitud de permiso para leer datos del inquilino:

<AppPermissionRequests>
  <AppPermissionRequest 
    Scope="http://sharepoint/content/tenant" 
    Right="Read" />
</AppPermissionRequests>

Para cambiar el sitio de contexto en el código, use el punto de conexión AppContextSite (REST) o el objeto (JSOM), del mismo modo que en la sección Obtener acceso a datos desde la web de host.

Este es un recordatorio del punto de conexión REST: /_api/SP. AppContextSite(@target)/web/title?@target=' weburl', y un ejemplo sobre cómo crear una instancia del objeto en JSOM: appContextSite = new SP.AppContextSite(context, weburl);.

Como desarrollador, solo puede implementar complementos con ámbito de espacio empresarial del catálogo de complementos. Puede aprovisionar un catálogo de complementos en los entornos de SharePoint Online o locales. Cargar el complemento en el catálogo de complementos es tan sencillo como cargar un archivo en una biblioteca de documentos. Para obtener instrucciones detalladas, consulte Usar el catálogo de aplicaciones para que las aplicaciones empresariales personalizadas estén disponibles en su entorno de SharePoint Online.

Desde el catálogo de complementos, puede implementar el complemento en uno o varios sitios web del espacio empresarial. Dado que el complemento tiene permisos para obtener acceso a los datos del espacio empresarial, solo tiene que implementarlo en un sitio web para obtener acceso a los datos de todo el espacio empresarial. Para obtener instrucciones sobre cómo implementar un complemento desde el catálogo de complementos, vea Implementar un complemento personalizado.

Para descargar un ejemplo de código que muestre cómo obtener acceso a datos en colecciones de sitios, vea Usar la biblioteca entre dominios en un complemento con ámbito de espacio empresarial (REST).

Emitir llamadas entre diferentes zonas de seguridad

La biblioteca entre dominios usa una página de proxy hospedada en un IFrame en la página de complemento para habilitar la comunicación. Cuando la página de complemento y el sitio web de SharePoint están en diferentes zonas de seguridad, no se pueden enviar cookies de autorización. Si no hay ninguna cookie de autorización e IFrame intenta cargar la página de proxy, se redirige a la página de inicio de sesión de SharePoint. La página de inicio de sesión de SharePoint no puede contener ningún IFrame por motivos de seguridad. En estos escenarios, la biblioteca no puede cargar la página de proxy y no es posible la comunicación con SharePoint.

Sin embargo, hay una solución para estos escenarios. La solución es el patrón apphost, que consiste en ajustar las páginas de complementos en una página hospedada en la web de complemento. Es una buena idea usar el patrón apphost en complementos que usan la biblioteca entre dominios, aun cuando no haya límites de seguridad evidentes. Para obtener más información, vea Trabajar con la biblioteca entre dominios en diferentes zonas de seguridad de Internet Explorer en los complementos para SharePoint.

Obtener acceso a datos desde un host remoto adicional en un complemento hospedado en SharePoint

De manera predeterminada, Complementos hospedados en SharePoint tiene permitido emitir llamadas entre dominios a la web de host, siempre y cuando tenga permisos adecuados. Sin embargo, una Complementos hospedados en SharePoint también puede especificar un host remoto en el atributo AllowedRemoteHostUrl de su AppPrincipal. Esto efectivamente permite emitir llamadas entre dominios de la web de complemento y de otro host en otro sitio.

Para descargar un ejemplo de un complemento hospedado en SharePoint que use la biblioteca entre dominios, vea Ejemplo de código: usar la biblioteca entre dominios en un complemento hospedado en SharePoint (REST).

Consulte también

• Ejemplo de código: Obtener el título de la web de host con la biblioteca entre dominios (REST)
• Ejemplo de código: Obtener el título de la web de host con la biblioteca entre dominios (JSOM)
• Ejemplo de código: Usar el control de cromo y la biblioteca entre dominios (REST)
• Ejemplo de código: Usar el control de cromo y la biblioteca entre dominios (JSOM)
• Ejemplo de código: Usar acciones personalizadas y la biblioteca entre dominios para solicitar libros
• Acceso a datos seguro y modelos de objetos de cliente para complementos de SharePoint
• Crear una página de proxy personalizada para la biblioteca entre dominios en SharePoint
• Consultar un servicio remoto con el proxy web en SharePoint
• Crear complementos de SharePoint que usen la biblioteca entre dominios
• Autorización y autenticación de complementos de SharePoint