Query a remote service using the web proxy in SharePoint

When you are building SharePoint Add-ins, you usually have to incorporate data from various sources. For security reasons, there are blocking mechanisms that prevent cross-domain communication. When you use the web proxy, the webpages in your add-in can access data in your remote domain and the SharePoint domain.

As a developer, you can use the web proxy exposed in client APIs, such as the JavaScript and .NET client object models. When you use the web proxy, you issue the initial request to SharePoint. In turn, SharePoint requests the data to the specified endpoint and forwards the response back to your page.

Use the web proxy when you want the communication to occur at the server level. For more information, see Secure data access and client object models for SharePoint Add-ins.

SharePoint Web Proxy is middle man between your code and external data source

Prerequisites for using the examples in this article

To follow the steps in this example, you need the following:

• Visual Studio 2015 and the latest Microsoft Office Developer Tools

• A SharePoint development environment (add-in isolation required for on-premises scenarios)

Core concepts to know before using the web proxy

The following table lists some useful articles that can help you understand the concepts involved in a cross-domain scenario in SharePoint Add-ins.

Code example: Access data in a remote service using the web proxy

To read data from a remote service, you must do the following:

1. Create a SharePoint Add-in project.

2. Modify the Default.aspx page to use the web proxy to query the remote service.

3. Modify the add-in manifest to allow communication to the remote domain.

The following figure shows the browser window with data from the remote service on a SharePoint webpage.

SharePoint webpage with data from the remote service

To create the SharePoint Add-in project

1. Open 2015 as administrator. (To do this, right-click the 2015 icon in the Start menu, and select Run as administrator.)

2. Create a new project using the SharePoint Add-in template.

   The following figure shows the location of the SharePoint Add-in template in 2015, under Templates > Visual C# > Office/SharePoint > Office Add-ins.

   SharePoint Add-in Visual Studio template

   

   
   

3. Provide the URL of the SharePoint website that you want to use for debugging.

4. Select SharePoint-hosted as the hosting option for your add-in.

To modify the Default.aspx page to use the web proxy by using the JavaScript object model

1. Double-click the Default.aspx page in the Pages folder.

2. Copy the following markup and paste it in the PlaceHolderMain content tag of the page. The markup performs the following tasks:

   • Provides a placeholder for the remote data.

   • References the SharePoint JavaScript files.

   • Prepares the request with a WebRequestInfo object.

   • Prepares the request Accept header to specify the response in the JavaScript Object Notation (JSON) format.

   • Issues a call to the remote endpoint.

   • Handles successful completion, rendering the remote data in the SharePoint webpage.

   • Handles any errors, rendering the error message in the SharePoint webpage.

   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>
   

   
   

(Optional) To modify the Default.aspx page to use the web proxy by using the REST endpoint

1. Double-click the Default.aspx page in the Pages folder.

2. Copy the following markup and paste it in the PlaceHolderMain content tag of the page. The markup performs the following tasks:

   • Provides a placeholder for the remote data.

   • References the jQuery library.

   • Prepares the request to the SP.WebRequest.Invoke endpoint.

   • Prepares the body of the request with a SP.WebrequestInfo object. The object includes an Accept header to specify the response in the JavaScript Object Notation (JSON) format.

   • Issues a call to the remote endpoint.

   • Handles successful completion, rendering the remote data in the SharePoint webpage.

   • Handles any errors, rendering the error message in the SharePoint webpage.

   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>
   
   

To edit the add-in manifest file

1. In Solution Explorer, open the shortcut menu for the AppManifest.xml file, and select View code.

2. Copy the following RemoteEndPoints definition as a child of the App node.

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

The RemoteEndpoint element is used to specify the remote domain. The web proxy validates that the requests issued to remote domains are declared in the add-in manifest. You can create up to 20 entries in the RemoteEndpoints element. Only the authority part is considered; http://domain:port and http://domain:port/website are considered the same endpoint. You can issue calls to many different endpoints within the same domain with just one RemoteEndpoint definition.

To build and run the solution

1. Select the F5 key.

   Note

   When you select F5, Visual Studio builds the solution, deploys the add-in, and opens the permissions page for the add-in.

2. Select the Trust It button.

3. Click the add-in icon on the Site Contents page.

   The following figure shows the remote data in the SharePoint webpage.

   Remote data in the SharePoint webpage

   

Troubleshooting the solution

See also

• Code sample: Get data from a remote service using the web proxy
• Work with external data in SharePoint