Interroger un service distant à l'aide du proxy web dans SharePoint

Article
04/08/2023

Lorsque vous créez des Compléments SharePoint, vous devez généralement incorporer des données en provenance de différentes sources. Pour des raisons de sécurité, des mécanismes de blocage empêchant la communication entre les domaines sont mis en place. Lorsque vous utilisez le proxy web, les pages web dans votre complément peuvent accéder aux données dans votre domaine à distance et dans le domaine SharePoint.

En tant que développeur, vous pouvez utiliser le proxy web exposé dans les API clientes (par exemple, les modèles objets clients JavaScript et .NET). Quand vous utilisez le proxy web, la première requête est destinée à SharePoint. À son tour, SharePoint demande les données au point de terminaison spécifié et transfère la réponse vers votre page.

Utilisez le proxy web pour établir la communication au niveau du serveur. Reportez-vous à la section Accès aux données sécurisé et modèles objets clients pour les compléments SharePoint.

Le proxy web SharePoint est l’intermédiaire entre votre code et la source de données externe

Symboles pour « votre code », « proxy web SharePoint » et « source de données » montrant que les demandes de données sont transmises via le proxy web.

Conditions préalables à l’utilisation des exemples de cet article

Pour suivre les étapes de cet exemple, vous avez besoin des éléments suivants :

Visual Studio 2015 et outils de développement Microsoft Office les plus récents
Un environnement de développement SharePoint (isolation de complément requise pour les scénarios sur site)

Concepts principaux avant d’utiliser le proxy web

Le tableau suivant contient des articles très utiles pour vous aider à comprendre les concepts impliqués dans un scénario inter-domaines dans des Compléments SharePoint.

Titre d’article	Description
Compléments	Découvrez le nouveau modèle de complément dans SharePoint qui vous permet de créer des compléments, c’est-à-dire de petites solutions simples d’utilisation pour les utilisateurs finaux.
Accès aux données sécurisé et modèles d’objet client pour les compléments SharePoint	Découvrez les options d'accès aux données des Compléments SharePoint. Cet article contient des informations sur les principales options parmi lesquelles vous devez effectuer un choix lors de l'utilisation de données dans votre complément.
Héberger des sites web, des sites web de complément et des composants SharePoint dans SharePoint	Découvrez la différence entre les sites web hôtes et les sites web de complément. Découvrez les composants SharePoint pouvant être inclus dans un Complément SharePoint, les composants déployés sur le site web hôte, les composants déployés sur le site web de complément et la façon dont le site web de complément est déployé dans un domaine isolé.
Sécurité inter-domaines côté client	Explorez les menaces multidomaine et les cas d’utilisation, les principes de sécurité pour les requêtes d’origine multiple, et pesez les risques pour les développeurs qui doivent améliorer l’accès multidomaine à partir d’applications web qui s’exécutent dans le navigateur.

Exemple de code : accédez aux données dans un service à distance à l’aide du proxy web

Pour lire les données à partir d’un service à distance, vous devez procéder comme suit :

Créez un projet de Complément SharePoint.
Modifiez la page Default.aspx pour utiliser le proxy web et interroger le service à distance.
Modifiez le manifeste du complément pour autoriser la communication au domaine à distance.

La figure suivante montre la fenêtre du navigateur affichant les données du service distant sur une page web SharePoint.

Page web SharePoint affichant les données du service distant

Page SharePoint avec des données du service distant

Création d’un projet de complément SharePoint

Ouvrez Visual Studio 2015 en tant qu’administrateur. (Cliquez avec le bouton droit de la souris sur l’icône Visual Studio 2015 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 SharePoint.

La figure suivante montre l’emplacement du modèle Complément SharePoint dans Visual Studio 2015, sous Modèles>Visual C#>Office/SharePoint>Compléments Office.

Modèle de complément SharePoint dans Visual Studio
Indiquez l’URL du site web SharePoint que vous souhaitez utiliser pour le débogage.
Sélectionnez Hébergé par SharePoint comme option d'hébergement pour votre complément.

Pour modifier la page Default.aspx et utiliser le proxy web à l’aide du modèle objet JavaScript

Double-cliquez sur la page Default.aspx dans le dossier Pages.

Copiez le balisage suivant dans la balise de contenu PlaceHolderMain de la page. Le balisage effectue les tâches suivantes :

Il fournit un espace réservé pour les données à distance.
Il référence les fichiers SharePoint JavaScript.
Il prépare la requête avec un objet WebRequestInfo.
Il prépare l'en-tête Accept de la requête pour fournir la réponse au format JavaScript Object Notation (JSON).
Il lance un appel au point terminal à distance.
Il gère l’opération de A à Z en reproduisant les données distantes dans la page web SharePoint.
Il gère les erreurs, en rendant le message d’erreur dans la page web SharePoint.

Categories from the Northwind database exposed as an OData service: 

<!-- Placeholder for the remote content -->
<span id="categories"></span>

<!-- Add references to the JavaScript libraries. -->
<script 
    type="text/javascript" 
    src="../_layouts/15/SP.Runtime.js">
</script>
<script 
    type="text/javascript" 
    src="../_layouts/15/SP.js">
</script>
<script type="text/javascript">
(function () {
    "use strict";

    // Prepare the request to an OData source
    // using the GET verb.
    var context = SP.ClientContext.get_current();
    var request = new SP.WebRequestInfo();
    request.set_url(
        "http://services.odata.org/Northwind/Northwind.svc/Categories"
        );
    request.set_method("GET");

    // We need the response formatted as JSON.
    request.set_headers({ "Accept": "application/json;odata=verbose" });
    var response = SP.WebProxy.invoke(context, request);

    // Let users know that there is some
    // processing going on.
    document.getElementById("categories").innerHTML =
                "<P>Loading categories...</P>";

    // Set the event handlers and invoke the request.
    context.executeQueryAsync(successHandler, errorHandler);

    // Event handler for the success event.
    // Get the totalResults node in the response.
    // Render the value in the placeholder.
    function successHandler() {

        // Check for status code == 200
        // Some other status codes, such as 302 redirect
        // do not trigger the errorHandler. 
        if (response.get_statusCode() == 200) {
            var categories;
            var output;

            // Load the OData source from the response.
            categories = JSON.parse(response.get_body());

            // Extract the CategoryName and Description
            // from each result in the response.
            // Build the output as a list.
            output = "<UL>";
            for (var i = 0; i < categories.d.results.length; i++) {
                var categoryName;
                var description;
                categoryName = categories.d.results[i].CategoryName;
                description = categories.d.results[i].Description;
                output += "<LI>" + categoryName + ":&amp;nbsp;" +
                    description + "</LI>";
            }
            output += "</UL>";

            document.getElementById("categories").innerHTML = output;
        }
        else {
            var errordesc;

            errordesc = "<P>Status code: " +
                response.get_statusCode() + "<br/>";
            errordesc += response.get_body();
            document.getElementById("categories").innerHTML = errordesc;
        }
    }

    // Event handler for the error event.
    // Render the response body in the placeholder.
    // The body includes the error message.
    function errorHandler() {
        document.getElementById("categories").innerHTML =
            response.get_body();
    }
})();
</script>

(Facultatif) Pour modifier la page Default.aspx et utiliser le proxy web à l’aide du point de terminaison REST

Double-cliquez sur la page Default.aspx dans le dossier Pages.

Copiez le balisage suivant dans la balise de contenu PlaceHolderMain de la page. Le balisage effectue les tâches suivantes :

Il fournit un espace réservé pour les données à distance.
Il fait référence à la bibliothèque jQuery.
Il prépare la requête au point de terminaison SP.WebRequest.Invoke.
Il prépare le corps de la requête avec un objet SP.WebrequestInfo. L'objet comprend un en-tête Accept qui fournit la réponse au format JavaScript Object Notation (JSON).
Il lance un appel au point de terminaison distant.
Il gère l’opération de A à Z en reproduisant les données distantes dans la page web SharePoint.
Il gère toutes les erreurs avec un rendu du message d’erreur dans la page web SharePoint.

Categories from the Northwind database exposed as an OData service: 

<!-- Placeholder for the remote content -->
<span id="categories"></span>

<script 
    type="text/javascript" 
    src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.8.0.min.js">
</script>

<script type="text/javascript">
(function () {
    "use strict";

    // The Northwind categories endpoint.
    var url =
        "http://services.odata.org/Northwind/Northwind.svc/Categories";

    // Let users know that there is some
    // processing going on.
    document.getElementById("categories").innerHTML =
                "<P>Loading categories...</P>";

    // Issue a POST request to the SP.WebProxy.Invoke endpoint.
    // The body has the information to issue a GET request
    // to the Northwind service.
    $.ajax({
        url: "../_api/SP.WebProxy.invoke",
        type: "POST",
        data: JSON.stringify(
            {
                "requestInfo": {
                    "__metadata": { "type": "SP.WebRequestInfo" },
                    "Url": url,
                    "Method": "GET",
                    "Headers": {
                        "results": [{
                            "__metadata": { "type": "SP.KeyValue" },
                            "Key": "Accept",
                            "Value": "application/json;odata=verbose",
                            "ValueType": "Edm.String"
                        }]
                    }
                }
            }),
        headers: {
            "Accept": "application/json;odata=verbose",
            "Content-Type": "application/json;odata=verbose",
            "X-RequestDigest": $("#__REQUESTDIGEST").val()
        },
        success: successHandler,
        error: errorHandler
    });

    // Event handler for the success event.
    // Get the totalResults node in the response.
    // Render the value in the placeholder.
    function successHandler(data) {
        // Check for status code == 200
        // Some other status codes, such as 302 redirect,
        // do not trigger the errorHandler. 
        if (data.d.Invoke.StatusCode == 200) {
            var categories;
            var output;

            // Load the OData source from the response.
            categories = JSON.parse(data.d.Invoke.Body);

            // Extract the CategoryName and Description
            // from each result in the response.
            // Build the output as a list
            output = "<UL>";
            for (var i = 0; i < categories.d.results.length; i++) {
                var categoryName;
                var description;
                categoryName = categories.d.results[i].CategoryName;
                description = categories.d.results[i].Description;
                output += "<LI>" + categoryName + ":&amp;nbsp;" +
                    description + "</LI>";
            }
            output += "</UL>";

            document.getElementById("categories").innerHTML = output;
        }
        else {
            var errordesc;

            errordesc = "<P>Status code: " +
                data.d.Invoke.StatusCode + "<br/>";
            errordesc += response.get_body();
            document.getElementById("categories").innerHTML = errordesc;
        }
    }

    // Event handler for the error event.
    // Render the response body in the placeholder.
    // The 2nd argument includes the error message.
    function errorHandler() {
        document.getElementById("categories").innerHTML =
            arguments[2];
    }
})();
</script>

Pour modifier le fichier manifeste du complément

Dans l’Explorateur de solutions, ouvrez le menu contextuel du fichier AppManifest.xml et sélectionnez Afficher le code.

Copiez la définition RemoteEndPoints suivante comme enfant du nœud App.

<RemoteEndpoints>
    <RemoteEndpoint Url=" http://services.odata.org" />
</RemoteEndpoints>

L’élément RemoteEndpoint est utilisé pour spécifier le domaine à distance. Le proxy web s’assure que les demandes envoyées aux domaines à distance sont déclarées dans le manifeste du complément. Vous pouvez créer jusqu’à 20 entrées dans l’élément RemoteEndpoints. Seule la partie autorité est prise en compte ; http://domain:port et http://domain:port/website sont considérés comme le même point de terminaison. Vous pouvez envoyer des appels à différents points de terminaison dans un même domaine avec une seule définition RemoteEndpoint.

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.
Cliquez sur l’icône du complément sur la page Contenu du site.

La figure suivante montre les données distantes affichées sur la page web SharePoint.

Données distantes affichées sur la page web SharePoint

Dépannage de la solution

Problème	Solution
Visual Studio n’ouvre pas le navigateur lorsque vous sélectionnez la touche F5.	Définissez le projet de Complément SharePoint en tant que projet de démarrage.
Exception non gérée SP n'est pas défini.	Assurez-vous que vous pouvez accéder au fichier SP.RequestExecutor.js dans une fenêtre de navigateur. Si vous utilisez votre serveur local comme environnement de développement, vous devez désactiver le contrôle de bouclage d’IIS. À partir de l’invite de commandes Windows PowerShell, exécutez la commande suivante : `New-ItemProperty HKLM:\System\CurrentControlSet\Control\Lsa -Name "DisableLoopbackCheck" -value "1" -PropertyType dword` Attention : la désactivation de la case activée de bouclage IIS n’est pas recommandée dans un environnement de production.
La taille de la réponse du point de terminaison distant va au-delà de la limite configurée.	La taille de la réponse des requêtes du proxy web ne doit pas dépasser 200 Ko.
La combinaison modèle-port n’est pas prise en charge.	La combinaison d’appel modèle-port doit remplir les critères suivants : Modèle - Port http - 80 https - 443 http ou https - 7000-10000 Important : les ports de sortie dépendent de la disponibilité du pare-feu du site web hôte. Seuls les ports http-80 et https-443 sont disponibles sur SharePoint Online.

Share via