SharePoint で Web プロキシを使用してリモート サービスに問い合わせるQuery a remote service using the web proxy in SharePoint

SharePoint アドインを作成する場合、通常は、さまざまなソースのデータを組み込む必要があります。セキュリティ上の理由から、クロスドメイン通信を防止するブロック メカニズムが存在します。Web プロキシを使用すると、アドインに含まれる Web ページから、リモート ドメインおよび 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.

開発者として、JavaScript と .NET クライアント オブジェクト モデルなど、クライアント API に公開されている Web プロキシを使用できます。As a developer, you can use the web proxy exposed in client APIs, such as the JavaScript and .NET client object models. Webプロキシを使用する場合は、SharePoint への最初の要求を発行します。When you use the web proxy, you issue the initial request to SharePoint. 次に、SharePoint はデータを指定されたエンドポイントに要求し、応答をページに転送します。In turn, SharePoint requests the data to the specified endpoint and forwards the response back to your page.

サーバー レベルでの通信を行いたい場合は、Web プロキシを使用します。Use the web proxy when you want the communication between the remote data source and the SharePoint page to occur at the server level. 詳細については、「SharePoint アドインのデータ アクセスとクライアント オブジェクト モデルをセキュリティで保護する」を参照してください。For more information, see Secure data access and client object models for SharePoint Add-ins.

SharePoint Web プロキシがコードと外部データ ソースの仲介役となるSharePoint Web Proxy is middle man between your code and external data source

「your code (コード)」、「SharePoint Web Proxy (SharePoint Web プロキシ)」「Data source (データ ソース)」のシンボルは、データ要求が Web プロキシを経由することを表しています。

この記事の例を使用するための前提条件Prerequisites for using the examples in this article

この例の手順を実行するには、以下が必要です。To follow the steps in this example, you need the following:

Web プロキシを使用する前に理解しておくべき主要概念Core concepts to know before using the web proxy

次の表に、SharePoint アドインにおけるクロスドメイン シナリオに関連する概念の理解に役立ついくつかの有用な記事を一覧表示します。The following table lists some useful articles that can help you understand the concepts involved in a cross-domain scenario in SharePoint Add-ins.

記事のタイトルArticle title 説明Description
SharePoint アドインSharePoint Add-ins エンドユーザー向けの小型で使いやすいソリューションであるアドインを作成できる、SharePoint の新しいアドイン モデルについて説明します。Learn about the new add-in model in SharePoint that enables you to create add-ins, which are small, easy-to-use solutions for end users.
SharePoint アドインのセキュリティで保護されたデータ アクセスとクライアント オブジェクト モデルSecure data access and client object models for SharePoint Add-ins SharePoint アドインにおけるデータ アクセス オプションについて説明しています。この記事では、アドインでデータを操作する際に選択する必要がある代替手段の概要についてのガイダンスを示しています。Learn about data access options in SharePoint Add-ins. This article provides guidance on the high-level alternatives you have to choose from when working with data in your add-in.
SharePoint のホスト Web、アドイン Web、および SharePoint コンポーネントHost webs, add-in webs, and SharePoint components in SharePoint ホスト Web とアドイン Web の違いについて説明します。SharePoint アドイン に含めることのできる SharePoint コンポーネント、ホスト Web に展開するコンポーネント、アドイン Web に展開するコンポーネント、およびアドイン Web を分離ドメインに展開する方法について説明します。Learn about the difference between host webs and add-in webs. Find out which SharePoint components can be included in a SharePoint Add-in, which components are deployed to the host web, which components are deployed to the add-in web, and how the add-in web is deployed in an isolated domain.
クライアント側のクロスドメイン セキュリティClient-side Cross-domain Security クロスドメインにおける脅威とユース ケース、クロスオリジン要求でのセキュリティ原則を示し、開発者がブラウザーで動作する Web アプリケーションからのクロスドメイン アクセスを拡張する場合のリスクについて詳しく説明しています。Explore cross-domain threats and use cases, security principles for cross-origin requests, and weigh the risks for developers to enhance cross-domain access from web applications that run in the browser.

コード例: Web プロキシを使用してリモート サービスのデータにアクセスする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. SharePoint アドイン プロジェクトを作成します。Create a SharePoint Add-in project.

  2. Web プロキシを使用してリモート サービスにクエリを実行するように Default.aspx ページを変更します。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.

以下の図は、SharePoint Web ページからのデータが表示されたブラウザ ウィンドウを示しています。Figure 1 shows the browser window with data from the remote service in a SharePoint webpage.

リモート サービスからのデータが表示された SharePoint Web ページFigure 1. SharePoint webpage with data from the remote service

リモート サービスからのデータが表示された SharePoint ページ

SharePoint アドイン プロジェクトを作成するにはTo create the SharePoint Add-in project

  1. 管理者として 2015 を開きます。Open 2015 as administrator. (これを行うには、 [スタート] メニューで 2015 のアイコンを右クリックし、[管理者として実行] を選択します。)Open 2015 as administrator. (To do this, right-click the 2015 icon in the Start menu, and choose Run as administrator.)

  2. SharePoint アドイン テンプレートを使用して、新しいプロジェクトを作成します。Create a new project using the SharePoint Add-in template.

    次の図は、[テンプレート] > [Visual C#] > [Office/SharePoint] > [Office アドイン] の下にある 、2015 の SharePoint アドイン テンプレートの場所を示しています。Figure 2 shows the location of the SharePoint Add-in template in Visual Studio 2015, under Templates > Visual C# > Office/SharePoint > Office Add-ins.

    SharePoint アドイン Visual Studio のテンプレートFigure 2. SharePoint Add-in Visual Studio template

    SharePoint Visual Studio 用アプリのテンプレート


  3. デバッグに使用する SharePoint Web サイトの URL を入力します。Provide the URL of the SharePoint website that you want to use for debugging.

  4. アドインのホスティング オプションとして、[ SharePoint ホスト型] を選択します。Select SharePoint-hosted as the hosting option for your add-in.

JavaScript オブジェクト モデルを使用して、Web プロキシを使用するように Default.aspx ページを変更するにはTo modify the Default.aspx page to use the web proxy by using the JavaScript object model

  1. [ ページ] フォルダー内の [ Default.aspx] ページをダブルクリックします。Double-click the Default.aspx page in the Pages folder.

  2. 以下のマークアップをコピーし、ページの PlaceHolderMain コンテンツ タグに貼り付けます。このマークアップは、次のタスクを実行します。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.

    • SharePoint JavaScript ファイルを参照する。References the SharePoint JavaScript files.

    • WebRequestInfo オブジェクトを使用した要求を準備する。Prepares the request with a WebRequestInfo object.

    • JavaScript Object Notation (JSON) 形式の応答を指定する Accept 要求ヘッダーを準備する。Prepares the request Accept header to specify the response in the JavaScript Object Notation (JSON) format.

    • リモート エンドポイントに対する呼び出しを発行する。Issues a call to the remote endpoint.

    • 成功した実行を処理し、SharePoint Web ページにリモート データを表示する。Handles successful completion, rendering the remote data in the SharePoint webpage.

    • エラーを処理し、SharePoint Web ページにエラー メッセージを表示する。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>
      


(オプション) REST エンドポイントを使用して、Web プロキシを使用するように Default.aspx ページを変更するには(Optional) To modify the Default.aspx page to use the web proxy by using the REST endpoint

  1. [ ページ] フォルダー内の [ Default.aspx] ページをダブルクリックします。Double-click the Default.aspx page in the Pages folder.

  2. 以下のマークアップをコピーし、ページの PlaceHolderMain コンテンツ タグに貼り付けます。このマークアップは、次のタスクを実行します。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.

    • jQuery ライブラリを参照する。References the jQuery library.

    • SP.WebRequest.Invoke エンドポイントに対する要求を準備する。Prepares the request to the SP.WebRequest.Invoke endpoint.

    • SP.WebrequestInfo オブジェクトを使用した要求の本文を準備する。オブジェクトには、JavaScript Object Notation (JSON) 形式の応答を指定する Accept ヘッダーが含まれます。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.

    • 成功した実行を処理し、SharePoint Web ページにリモート データを表示する。Handles successful completion, rendering the remote data in the SharePoint webpage.

    • エラーを処理し、SharePoint Web ページにエラー メッセージを表示する。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. ソリューション エクスプローラで、[AppManifest.xml] ファイルのショートカット メニューを開き、[ビュー コード] を選択します。In Solution Explorer, open the shortcut menu for the AppManifest.xml file, and choose View code.

  2. 以下の RemoteEndPoints 定義を App ノードの子としてコピーします。Copy the following RemoteEndPoints definition as a child of the App node.

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

RemoteEndpoint 要素は、リモート ドメインを指定するために使用されます。Web プロキシによって、リモート ドメインに対して発行された要求がアドイン マニフェストで宣言されていることが検証されます。 RemoteEndpoints 要素では、最大 20 のエントリを作成できます。権限に関する部分のみが考慮されます。 http://domain:porthttp://domain:port/website は同じエンドポイントと見なされます。1 つの RemoteEndpoint 定義だけで、同じドメイン内のさまざまなエンドポイントに対し呼び出しを発行できます。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. F5 キーを選択します。Select the F5 key.

    注意

    F5 キーを押すと、Visual Studio がソリューションを構築して、アドインを展開し、アドインのアクセス許可ページを開きます。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 in the Site Contents page.

    以下の図は、SharePoint Web ページのリモート データを示しています。Figure 3 shows the remote data in the SharePoint webpage.

    SharePoint Web ページのリモート データFigure 3. Remote data in the SharePoint webpage

    リモート サービスからのデータが表示された SharePoint ページ

ソリューションのトラブルシューティングTroubleshooting the solution

問題Problem 解決方法Solution
Visual Studio で F5 キーを押してもブラウザが開かない。Visual Studio does not open the browser after you press the F5 key. SharePoint アドイン プロジェクトをスタートアップ プロジェクトとして設定してください。Set the SharePoint Add-in project as the startup project.
SPが定義されていませんというハンドルされていない例外が発生する。Unhandled exception SP is undefined. ブラウザー ウィンドウで SP.RequestExecutor.js ファイルにアクセスできることを確認してください。Make sure you can access the SP.RequestExecutor.js file in a browser window. 開発環境として、ローカル サーバーを使用している場合は、IIS のループバック チェックを無効にする必要があります。If you are using your local server as your development environment, you must disable IIS loopback check. Run the following command from a powershellnv command prompt.

Windows PowerShell コマンド プロンプトから次のコマンドを実行します。 New-ItemProperty HKLM:\System\CurrentControlSet\Control\Lsa -Name "DisableLoopbackCheck" -value "1" -PropertyType dwordRun the following commands from a Windows PowerShell command prompt.New-ItemProperty HKLM:\System\CurrentControlSet\Control\Lsa -Name "DisableLoopbackCheck" -value "1" -PropertyType dword

注意: 運用環境では、IIS のループバック チェックを無効にすることは推奨しません。Disabling the IIS loopback check is not recommended in a production environment.
リモート エンドポイントからの応答のサイズが、構成された制限を超えている。The size of the response from the remote endpoint exceeds the configured limit. Web プロキシ要求の応答のサイズは 200 KB 未満でなければなりません。The response’s size of web proxy requests must not be larger than 200 KB.
スキーマとポートの組み合わせがサポートされない。The scheme-port combination is not supported. 呼び出しのスキーマとポートの組み合わせは、以下の条件に当てはまっている必要があります。The call schema-port combination must fall within the following criteria:

スキーマ - ポートScheme - Port
http - 80http - 80
https - 443https - 443
http または https - 7000-10000http or https - 7000-10000

重要: 送信ポートは、ファイアウォールの可用性をホストするためのものです。Important The outbound ports are subject to host firewall availability. In particular, only http-80 and https-443 are available on SharePoint Online. 特に、http 80 と https 443 だけが、SharePoint Online で利用可能です。Important The outbound ports are subject to host firewall availability. In particular, only http-80 and https-443 are available on SharePoint Online.

関連項目See also