Accéder à des données SharePoint à partir de compléments à l’aide de la bibliothèque inter-domaines

Article
04/08/2023

Lorsque vous créez des compléments SharePoint, vous devez généralement incorporer des données provenant de diverses sources. Cependant, pour des raisons de sécurité, des mécanismes de blocage empêchent la communication avec plusieurs domaines à la fois. Ces mécanismes de sécurité sont implémentés dans la plupart des navigateurs, ce qui rend difficile, voire impossible, d’effectuer des appels côté client sur domaines.

Lorsqu’un utilisateur demande une page du domaine de votre complément, la communication côté client est liée à ce domaine uniquement. Votre complément peut émettre des appels côté client à partir de la page, mais seulement vers d’autres ressources appartenant au même domaine. Toutefois, les compléments nécessitent généralement des ressources provenant d’autres domaines, comme le domaine SharePoint, afin de réaliser leurs scénarios. Dans le code de votre page, vous pouvez essayer d’envoyer une requête au domaine SharePoint, bloqué par le navigateur. Généralement, une erreur accès refusé s’affiche. Le message d’erreur ne signifie pas que vous n’avez pas les autorisations d’accès aux ressources demandées mais, le plus souvent, vous ne pouvez pas envoyer de requête aux ressources en question.

Lorsque vous utilisez la bibliothèque inter-domaines, les pages web de votre complément peuvent accéder aux données du domaine de votre complément et du domaine SharePoint. La bibliothèque inter-domaines est une alternative côté client sous la forme d’un fichier JavaScript (SP.RequestExecutor.js) hébergé sur le site web SharePoint que vous pouvez référencer dans votre complément distant. La bibliothèque inter-domaines vous permet d’interagir avec plusieurs domaines sur votre page de complément distant par le biais d’un proxy. C’est une bonne solution si vous préférez que votre code de complément s’exécute sur le client plutôt que sur le serveur, et en cas de barrières de connectivité (des pare-feu, par exemple) entre SharePoint et votre infrastructure distante.

Vous pouvez accéder aux données dans le site web hôte (par exemple, vous pouvez accéder à des listes avec lesquelles interagissent les utilisateurs finaux indépendamment de votre complément). Vous pouvez également accéder à des données dans le site web du complément (par exemple, des listes spécifiquement configurés pour votre complément). Les compléments peuvent aussi accéder à d’autres sites web et collections de sites, tant que le complément dispose d’autorisations d’étendue client et a été déployé en tant qu’installation par lots à l’aide du catalogue de compléments.

Remarque

Dans cette rubrique, domaine de complément fait référence au domaine qui héberge les pages du complément. Il peut s’agir du domaine d’une application web à distance dans un complément hébergé par un fournisseur, mais les pages du complément peuvent également se trouver sur SharePoint dans le site web du complément et effectuer des appels vers le domaine du site web hôte. Dans ce dernier scénario, le domaine de complément est le domaine du site web du complément.

L’exemple principal de cet article explique comment générer un complément capable de lire les données sur le site web du complément et de l’afficher dans une page web. La section Étapes suivantes présente d’autres scénarios qui s’ajoutent à l’exemple principal.

Conditions préalables

Pour suivre les exemples de cet article, vous devez disposer des éléments suivants :

Visual Studio installé à distance ou sur l’ordinateur sur lequel est installé SharePoint.
Visual Studio comprend les outils de développement Microsoft Office pour Visual Studio. Parfois, une version des outils est publiée entre les mises à jour de Visual Studio. Pour être sûr que vous avez la dernière version des outils, exécutez le programme d’installation pour les outils de développement Office pour Visual Studio 2013 ou le programme d’installation pour les outils de développement Office pour Visual Studio 2015.
Un environnement de développement SharePoint en local. Reportez-vous à la rubrique Configurer un environnement de développement local pour les compléments SharePoint.

Lire des données sur le site web de complément à l’aide de la bibliothèque inter-domaines

Dans cet exemple, on utilise une page simple hébergée à l’extérieur de SharePoint, qui se sert d’un point de terminaison Representational State Transfer (REST) pour lire des données dans un site web SharePoint (le site web du complément). Puisque la bibliothèque inter-domaines nécessite un site web de complément, il est logique de commencer par ce scénario.

Pour lire les données à partir du site web du complément, vous devez effectuer les opérations suivantes :

Créer un complément SharePoint et des projets web.
Créer des éléments de liste sur le site web du complément. Cette étape garantit également qu’un site web de complément est créé lorsque les utilisateurs déploient le complément.
Créer une page de complément qui utilise la bibliothèque inter-domaines pour lire les éléments de liste.

La figure suivante illustre une page web qui affiche les données sur le site web du complément.

Exemple d’écran de résultats d’éléments en lecture inter-domaines

Pour créer un Complément SharePoint et des projets web

Ouvrez Visual Studio en tant qu’administrateur. (Pour cela, cliquez avec le bouton droit de la souris sur l’icône Visual Studio dans le menu Démarrer, puis sélectionnez Exécuter en tant qu’administrateur.)
Créez un projet à l’aide du modèle Complément pour SharePoint. Le modèle Complément pour SharePoint dans Visual Studio se trouve sous Modèles>Visual C#>Office SharePoint>Compléments.
Fournissez l’URL du site web SharePoint que vous souhaitez utiliser pour le débogage.
Sélectionnez Hébergement par le fournisseur comme option d’hébergement pour votre complément.

Remarque

Vous pouvez également utiliser la bibliothèque inter-domaines dans un complément hébergé par SharePoint. Toutefois, dans un complément hébergé par SharePoint, la page du complément se trouve déjà sur le site web du complément et n’a donc pas besoin de la bibliothèque inter-domaines pour lire les éléments de la liste. Pour un exemple de complément hébergé par SharePoint qui lit des données sur le site web hôte, consultez la rubrique Utiliser la bibliothèque inter-domaines dans un complément hébergé par SharePoint (REST) ou la rubrique Accéder aux données du site web hôte plus loin dans cet article.

Pour créer des éléments de liste sur le site web du complément

Cliquez avec le bouton droit de la souris sur le projet de complément SharePoint dans l’ Explorateur de solutions. Cliquez sur Ajouter>Nouvel élément.
Sélectionnez Éléments Visual C#>Office/SharePoint>Liste. Définissez le nom de votre liste sur Annonces.

Double-cliquez sur Annonces>Elements.xml. Coller les nœuds XML suivants en tant qu’enfants de l’élément 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>

Pour créer une page de complément qui utilise la bibliothèque inter-domaines

Double-cliquez sur le fichier Default.aspx dans le projet web dans l’ Explorateur de solutions.
Copiez le code ci-dessous et collez-le dans le fichier Default.aspx. Ce code effectue les tâches suivantes :
- Charge la bibliothèque jQuery à partir du réseau de distribution de contenu Microsoft.
- Fournit un espace réservé pour le résultat.
- Extrait l’URL du site web du complément de la chaîne de requête.
- Charge le code JavaScript de la bibliothèque inter-domaines à l’aide de la fonction getScript dans jQuery.
  
  Cette fonction charge les ressources nécessaires, puis continue vers la fonction spécifiée, en veillant à ce que la bibliothèque inter-domaines soit chargée et disponible pour être utilisée par le code suivant.
- Instancie l'objet RequestExecutor. Par défaut, RequestExecutor utilise le site web du complément comme site de contexte.
  
  Remarque
  
  (REST) ou objet (JSOM). Pour en savoir plus sur AppContextSite, consultez la rubrique Accéder aux données à partir du site web hôte plus loin dans cet article.
- Émet un appel REST à destination du point de terminaison des éléments de liste.
- Gère la réussite de l’opération, en affichant les éléments de liste sur la page web.
- Gère les erreurs, en affichant le message d’erreur sur la page 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>

Pour créer et exécuter la solution

Sélectionnez la touche F5.

Remarque

Lorsque vous sélectionnez F5, Visual Studio génère la solution, déploie le complément et ouvre la page des autorisations pour le complément.
Sélectionnez le bouton Approuver.
Sélectionnez l’icône de complément de la page de Contenu du site.

Si vous préférez exemples de code téléchargeables, vous pouvez obtenir les exemples suivants dans la galerie de code :

Dépannage de la solution

Si vous voyez le message d’erreur suivant...	Essayez...
« Désolé, nous rencontrons des difficultés lors de l’accès à votre site. Il existe également un bouton permettant de corriger l’erreur, mais il ne résout pas le problème. »	Le problème que vous rencontrez est peut-être connu et lié aux zones de sécurité dans Internet Explorer. Consultez Utiliser la bibliothèque inter-domaines dans différentes zones de sécurité Internet Explorer dans les compléments pour SharePoint.
« Les fonctionnalités requises ne sont pas prises en charge par votre navigateur. Vérifiez que vous utilisez Internet Explorer 8 ou version ultérieure, ou tout autre navigateur moderne. Vérifiez que la balise META 4X-UA-Compatible’ est définie sur ’IE=8’ ou version ultérieure. »	La bibliothèque inter-domaines nécessite un mode de document IE8 ou version ultérieure. Dans certains cas, le mode de document est défini par défaut sur IE7. Vous pouvez utiliser les outils de développement Internet Explorer pour déterminer et modifier le mode de document de votre page. Pour plus d’informations, consultez la rubrique Définition de la compatibilité des documents.
« ’Type’ n’est pas défini. De plus, votre complément utilise le modèle objet JavaScript (JSOM). »	Le JSOM utilise la méthode Type.registerNamespace dans la bibliothèque Microsoft Ajax pour enregistrer l'espace de noms SP. Utilisez le code suivant pour ajouter une référence à la bibliothèque Microsoft Ajax à partir de votre page : `HTML <script type="text/javascript" src="//ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"></script>`

Étapes suivantes : scénarios de bibliothèque inter-domaines supplémentaires

Cet article indique comment demander à un point de terminaison REST de lire les données à partir du site web du complément en utilisant une page du complément qui n'est pas hébergée sur SharePoint. Vous pouvez également explorer les scénarios et les détails suivants à propos de la bibliothèque inter-domaines.

Utiliser le JSOM pour lire des données à partir du site web du complément

Selon vos préférences, vous pouvez utiliser le JSOM au lieu de REST pour interroger les données à partir du site web du complément. Vous devez effectuer des tâches supplémentaires pour utiliser la bibliothèque inter-domaines avec JSOM :

Référencer le JSOM SharePoint dans la page de votre complément.
Initialiser l'objet ProxyWebRequestExecutorFactory et le définir en tant que fabrique de l'objet de contexte.
Accéder aux objets SharePoint pour lire les données de la liste.
Charger les objets dans le contexte et exécuter la requête.

Pour voir un exemple de code qui explique comment effectuer les tâches, consultez SharePoint-Add-in-JSOM-CrossDomain.

Pour plus d’informations sur l’utilisation du JSOM, consultez la rubrique Utilisation du modèle objet JavaScript (JSOM) dans les compléments SharePoint.

Accéder aux données à partir du site web hôte

L’exemple de cette page indique comment lire les données sur le site web du complément. Il s’agit d’un bon premier exemple, car la bibliothèque inter-domaines utilise initialement le complément en tant que le site de contexte. Toutefois, il existe de nombreux scénarios pour lesquels vous souhaiterez accéder aux données du site web hôte. Quelques tâches sont nécessaires pour accéder aux données sur le site web hôte :

Définir le site web hôte en tant que site de contexte pour la bibliothèque inter-domaines.
Fournir les autorisations appropriées pour accéder au complément.

Vous pouvez modifier le site de contexte en utilisant le point de terminaison (REST) ou l’objet (JSOM) AppContextSite. L’exemple suivant montre comment modifier le site de contexte en utilisant le point de terminaison 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
    }
);

L’exemple de code suivant montre comment modifier le site de contexte à l’aide du 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);

Par défaut, votre complément dispose des autorisations pour accéder au site web du complément, mais pas au site web hôte. L'exemple suivant montre une section de manifeste déclarant une demande d'autorisation pour lire les données du site web hôte :

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

Veillez à créer une ressource sur le site web du complément (comme une page ou une liste vide) pour forcer la mise à disposition du site web du complément, laquelle est nécessaire pour utiliser la bibliothèque inter-domaines.

Accéder aux données sur plusieurs collections de sites

Avec la bibliothèque inter-domaines, vous pouvez accéder aux données de plusieurs collections de sites dans le même client. Vous devez effectuer certaines tâches pour accéder aux données de plusieurs collections de sites :

Ajouter une demande d'autorisation pour accéder aux données dans le client.
Dans votre code, basculez le site de contexte sur les collections de sites que vous souhaitez interroger.
Ajouter le complément au catalogue de compléments.
Déployer le complément en tant que complément d’étendue client sur un site web. Pour obtenir un exemple de déploiement de complément d’étendue client, consultez la description de l’exemple de code sur la page relative à l’utilisation de la bibliothèque inter-domaines dans une application d’étendue client (REST).

Votre complément doit également disposer d'autorisations pour accéder aux données du client. L'exemple suivant montre une section de manifeste déclarant une demande d'autorisation pour lire les données du client :

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

Pour basculer le site de contexte dans votre code, utilisez le point de terminaison (REST) ou l’objet (JSOM) AppContextSite, comme dans la section Accéder aux données à partir du site web hôte.

Voici un rappel du point de terminaison REST : /_api/SP. AppContextSite(@target)/web/title ?@target=' weburl', et un exemple sur la façon d’instancier l’objet dans JSOM : appContextSite = new SP.AppContextSite(context, weburl);.

En tant que développeur, vous ne pouvez déployer que des compléments d’étendue client à partir du catalogue de compléments. Vous pouvez configurer un catalogue de compléments dans votre environnement local ou sur SharePoint Online. Télécharger votre complément dans le catalogue de compléments est aussi simple que télécharger un fichier dans une bibliothèque de documents. Pour des instructions détaillées, consultez la rubrique Utiliser le catalogue d’applications pour mettre à disposition des applications d’entreprise personnalisées pour votre environnement SharePoint Online.

À partir du catalogue de compléments, vous pouvez déployer le complément sur un ou plusieurs sites web dans le client. Étant donné que votre complément dispose des autorisations pour accéder aux données dans le client, il suffit de le déployer sur un seul un site web pour accéder aux données dans l’ensemble du client. Pour des instructions sur la façon de déployer un complément à partir du catalogue de compléments, consultez la rubrique Déployer un complément personnalisé.

Pour télécharger un exemple de code qui montre comment accéder aux données dans plusieurs collections de sites, reportez-vous à la page relative à l’Utilisation de la bibliothèque inter-domaines dans un complément d’étendue client (REST).

Émettre des appels dans plusieurs zones de sécurité

La bibliothèque inter-domaines utilise une page proxy hébergée dans un IFrame sur la page du complément pour permettre la communication. Lorsque la page du complément et le site web SharePoint se trouvent dans des zones de sécurité différentes, les cookies d’autorisation ne peuvent pas être envoyés. En l’absence de cookies d’autorisation, si l’IFrame essaye de charger la page proxy, il est redirigé vers la page de connexion SharePoint. La page de connexion SharePoint ne peut pas se trouver dans un IFrame pour des raisons de sécurité. Dans ces scénarios, la bibliothèque ne peut pas charger la page proxy et la communication avec SharePoint n'est pas possible.

Cependant, il existe une solution pour ces scénarios. La solution est le modèle apphost, qui consiste à insérer les pages du complément dans une page hébergée dans le site web du complément. L'utilisation du modèle apphost est recommandée dans les compléments qui utilisent la bibliothèque inter-domaines, même s'il n'existe aucune frontière de sécurité évidente. Pour plus d'informations, voir Utiliser la bibliothèque inter-domaines dans différentes zones de sécurité Internet Explorer dans les compléments pour SharePoint.

Accéder aux données à partir d’un hôte distant supplémentaire dans un complément hébergé par SharePoint

Par défaut, une Application hébergée par SharePoint est autorisée à émettre des appels inter-domaines vers le site web hôte, à condition qu'elle dispose des autorisations appropriées. Cependant, une Application hébergée par SharePoint peut également spécifier un hôte distant dans l'attribut AllowedRemoteHostUrl de son AppPrincipal. Cela vous permet effectivement d'émettre des appels inter-domaines à partir du site web du complément et d'un autre hôte, où qu'il soit.

Pour télécharger un exemple d’Application hébergée par SharePoint qui utilise la bibliothèque inter-domaines, suivez le lien Exemple de code : utiliser la bibliothèque inter-domaines dans un complément hébergé par SharePoint (REST).