SharePoint のクロスドメイン ライブラリのカスタム プロキシ ページを作成するCreate a custom proxy page for the cross-domain library in SharePoint

SharePoint アドインを構築するときは、通常、さまざまなソースからのデータを組み込む必要があります。ただし、セキュリティのために、一度に複数のドメインと通信することを防ぐブロック メカニズムがあります。When you are building SharePoint Add-ins, you usually have to incorporate data from various sources. However, for security reasons, there are blocking mechanisms that prevent communication with more than one domain at a time.

リモート アドイン インフラストラクチャにホストされるカスタム プロキシ ページを提供する場合は、クロスドメイン ライブラリを使用して、リモート アドインのデータにアクセスできます。開発者は、カスタム プロキシ ページを実装し、リモート アドインに対する認証のメカニズムなどのカスタム ロジックを扱う必要があります。クライアント レベルで通信する場合は、クロスドメイン ライブラリとカスタム プロキシ ページを使用します。You can use the cross-domain library to access data in your remote add-in if you provide a custom proxy page that is hosted in the remote add-in infrastructure. As the developer, you are responsible for implementing the custom proxy page, and have to deal with custom logic, such as the authentication mechanism to the remote add-in. Use the cross-domain library with a custom proxy page if you want the communication to occur at the client level.

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

プロバイダー向けのホスト型 SharePoint アドインの作成を始める」で説明されている開発環境が必要です。You need a development environment as explained in Get started creating provider-hosted SharePoint Add-ins.

SharePoint アドインでカスタム プロキシ ページを使用する前に知っておく必要のある主要な概念Core concepts to know before using a custom proxy page with SharePoint Add-ins

次の表に、SharePoint アドインのクロスドメイン シナリオに関連する概念の理解に役立ついくつかの有用な記事を示します。The following table lists some useful articles that can help you understand the concepts involved in a cross-domain scenario for 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 topic 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 クロスドメインの脅威とユース ケース、および cross-origin 要求のセキュリティ原則について説明し、ブラウザーで実行する Web アプリケーションからのクロスドメイン アクセスを強化する場合の開発者にとってのリスクを評価します。Explore cross-domain threats and use cases, and 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.

コード例: クロスドメイン ライブラリのカスタム プロキシ ページを使用してリモート データにアクセスするCode example: Access remote data using a custom proxy page for the cross-domain library

リモート サービスからデータを読み取るには、次の操作を実行する必要があります。To read data from the remote service, you must do the following:

  1. SharePoint アドイン 用プロジェクトを作成します。Create a SharePoint Add-in project.

  2. アドイン マニフェストを変更して、リモート アドインからの通信を許可します。Modify the add-in manifest to allow communication from the remote add-in.

  3. Web プロジェクトでカスタム プロキシ ページとコンテンツ ページを作成します。Create the custom proxy page and a content page in the web project.

  4. SharePoint アドイン プロジェクトのクロスドメイン ライブラリを使用するページを作成します。Create a page that uses the cross-domain library in the SharePoint Add-in project.

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

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

  2. プロバイダー向けのホスト型 SharePoint アドインの作成を始める」で説明されているように、プロバイダー向けのホスト型 SharePoint アドインを作成して、ProxyPageApp という名前を付けます。Create the provider-hosted SharePoint Add-in as explained in Get started creating provider-hosted SharePoint Add-ins and name itProxyPageApp.

アドイン マニフェスト ファイルを編集するにはTo edit the add-in manifest file

  1. ソリューション エクスプローラーで、AppManifest.xml ファイルを右クリックし、[コードの表示] を選択します。In Solution Explorer, right-click the AppManifest.xml file, and choose View code.

  2. AppPrincipal 要素全体を次で置き換えます。Replace the entire AppPrincipal element with the following.

    <AppPrincipal>
        <Internal AllowedRemoteHostUrl="~remoteAppUrl"/>
    </AppPrincipal>
    

注意

AllowedRemoteHostUrl 属性を使用して、リモート ドメインを指定します。The AllowedRemoteHostUrl attribute is used to specify the remote domain. ~remoteAppUrl は、リモート アドインの URL に解決されます。The ~remoteAppUrl resolves to the remote add-in URL. トークンの詳細については、「SharePoint アドインのアプリ マニフェスト構造およびパッケージについて調べる」を参照してください。For more information, see Explore the app manifest structure and the package of a SharePoint Add-in.

カスタム プロキシ ページを作成するにはTo create a custom proxy page

  1. Visual Studio ソリューションの作成後、Web アプリケーション プロジェクト (SharePoint アドイン プロジェクトではない) を右クリックし、[追加] > [新しい項目] > [Web] > [Web フォーム] を選択して、新しい Web フォームを追加します。After the Visual Studio solution has been created, right-click the web application project (not the SharePoint Add-in project) and add a new Web Form by choosing Add > New Item > Web > Web Form. Name the form Proxy.aspx. フォームに Proxy.aspx という名前を付けます。Name the form Proxy.aspx.

  2. Proxy.aspx ファイルで、HTML 要素全体とその子を、以下の HTML コードに置き換えます。In the Proxy.aspx file, replace the entire HTML element and its children with the following HTML code. HTML 要素の上のマークアップは、すべてそのままにします。Leave all the markup above the HTML element as it is. HTML コードには、次のタスクを実行する JavaScript とマークアップが含まれています。The HTML code contains markup and JavaScript that performs the following tasks:

    • クロスドメイン ライブラリ JavaScript ファイルのプレースホルダーを提供します。Provides a placeholder for the cross-domain library JavaScript file.

    • 参照元からアドイン Web URL を抽出します。Extracts the add-in web URL from the referrer.

    • クロスドメイン ライブラリ JavaScript ファイルをプレースホルダーに動的に読み込みます。Dynamically loads the cross-domain library JavaScript file into the placeholder.

    • RequestExecutorMessageProcessor オブジェクトの設定を指定します。Provides settings for the RequestExecutorMessageProcessor object.

    • RequestExecutorMessageProcessor オブジェクトを初期化します。Initializes the RequestExecutorMessageProcessor object.

      <html xmlns="http://www.w3.org/1999/xhtml">
      <head runat="server">
        <meta http-equiv="X-UA-Compatible" content="IE=8" /> 
        <title>Custom Proxy Host Page</title>
        <script 
            src="http://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js" 
            type="text/javascript">
        </script>
        <script 
            type="text/javascript" 
            src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
        </script>
      
        <!-- Script to load the cross-domain library js file -->
        <script type="text/javascript">
            var hostweburl;
      
            $(document).ready(function(){
                //Get the URI decoded host web URL.
                hostweburl =
                    decodeURIComponent(
                        getQueryStringParameter("SPHostUrl")
                );
      
                // The cross-domain js file is in a URL in the form:
                // host_web_url/_layouts/15/SP.RequestExecutor.js
                var scriptbase = hostweburl + "/_layouts/15/";
      
                // Load the js file 
                $.getScript(scriptbase + "SP.RequestExecutor.js", initCustomProxy);
            });
      
            //Function to initialize the custom proxy page
            //  must set the appropriate settings and implement
            //  proper authentication mechanism
            function initCustomProxy() {
                var settings =
                {
                    originAuthorityValidator: function (messageOriginAuthority) {
                        // This page must implement the authentication for the
                        //   remote add-in.
                        // You should validate if messageOriginAuthority is
                        //  an approved domain to receive calls from.
                        return true;
                    }
                };
                SP.RequestExecutorMessageProcessor.init(settings);
            }
      
            // 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>
      </head>
      <body>
      
      </body>
      </html>
      


重要

運用 SharePoint アドインでは、承認ロジックを指定し、設定の originAuthorityValidator オブジェクトで、適切な値を返す必要があります。Important In a production SharePoint Add-in, you must provide the authorization logic and return the appropriate value in the originAuthorityValidator object in settings.

コンテンツ ページを作成するにはTo create a content page

  1. ソリューション エクスプローラーで Web アプリケーション プロジェクトを右クリックし、[追加] > [新しい項目] > [Web] > [Web フォーム] を選択して、新しい Web フォームを追加します。フォームに Content.aspx という名前を付けます。Right-click the web application project in Solution Explorer and add a new Web Form by choosing Add New Item Web Web Form. Name the form Content.aspx..

  2. 次のコードをコピーして分離コード ファイルの Page_Load メソッドに貼り付けます。コードは以下のタスクを実行します。Copy the following code and paste it in the Page_Load method in the code-behind file. The code performs the following tasks:

    • 出力 content-typetext/plain に設定します。Sets the output content-type to text/plain.

    • コンテンツを出力バッファーに書き込みます。Writes the content to the output buffer.

    • 接続を終了します。Ends the connection.

      string content;
      content = "Just some text.";
      Response.ContentType="text/plain";
      Response.Write(content);
      Response.End();
      


クロスドメイン ライブラリを使用する SharePoint Web ページを作成するにはTo create a SharePoint webpage that uses the cross-domain library

  1. SharePoint アドイン プロジェクトを右クリックして、[追加] > [新しい項目] > [Office/SharePoint] > [モジュール] を選択します。Right-click the SharePoint Add-in project, and choose Add > New Item > Office/SharePoint > Module.

  2. モジュールに Pages という名前を付けて、[追加] を選択します。Name the module Pages, and then choose Add.

  3. [Pages] フォルダーを右クリックして、[追加] > [新しい項目] > [Office/SharePoint] > [ページ] の順に選択します。Right-click the Pages folder and choose Add New Item Office/SharePoint Page.

  4. ページに Home.aspx という名前を付け、[追加] を選択します。Name the page Home.aspx and then choose Add.

  5. Home.aspx ページが自動的に開かない場合は開きます。Open the Home.aspx page if it isn't opened automatically.

  6. 次のコードをコピーして PlaceHolderMain コンテンツ タグに貼り付けます。Copy the following code and paste it in the PlaceHolderMain content tag.

    <!-- The page dynamically loads the cross-domain library's
        js file, rescript acts as the placeholder. -->
    <script 
        type="text/javascript"
        id="rescript"
        src="../_layouts/15/SP.RequestExecutor.js">
    </script>
        Data from the remote domain: <span id="TextData"></span>
    
        <!-- Main script to retrieve the host web's title -->
        <script type="text/javascript">
        (function () {
            var executor;
            var hostweburl;
            var remotedomain;
    
            remotedomain = "<your_remote_add-in_domain>";
    
            //Get the URI decoded host web URL.
            hostweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPHostUrl")
            );
    
            // Initialize the RequestExecutor with the custom proxy URL.
            executor = new SP.RequestExecutor(remotedomain);
            executor.iFrameSourceUrl = "Proxy.aspx?SPHostUrl=" + hostweburl;
    
            // Issue the call against the remote endpoint.
            // The response formats the data in plain text.
            // The functions successHandler and errorHandler attend the
            //      sucess and error events respectively.
            executor.executeAsync(
                {
                    url:
                        remotedomain + "Content.aspx",
                    method: "GET",
                    headers: { "Accept": "text/plain" },
                    success: successHandler,
                    error: errorHandler
                }
            );
        })();
    
        // Function to handle the success event.
        // Prints the data to the placeholder.
        function successHandler(data) {
            document.getElementById("TextData").innerText =
                data.body;
        }
    
        // Function to handle the error event.
        // Prints the error message to the page.
        function errorHandler(data, errorCode, errorMessage) {
            document.getElementById("TextData").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>
    


  7. 先に貼り付けたコードで、remotedomain = "<your_remote_add-in_domain>"; という行を探して、プレースホルダー <your_remote_add-in_domain> を、Visual Studio で F5 を押してアドインを実行するときに Web アプリケーションが使用する "localhost" の URL に置き換えます。この値を見つけるには、ソリューション エクスプローラーで Web アプリケーション プロジェクトを選択します。URL プロパティは [プロパティ] ペインにあります。http://localhost:45072 のように、プロトコル、ポート、終了のスラッシュを含む値全体を使用します。In the preceding code that you pasted, find the line , and replace the placeholder <your_remote_add-in_domain> with the "localhost" URL that your web application uses when you are running the add-in with F5 in Visual Studio. To find this value, select the web application project in Solution Explorer. The URL property will be in the Properties pane. Use the entire value, including the protocol, the port, and the closing slash; for example "http://localhost:45072".

  8. ファイルを保存して閉じます。Save and close the file.

  9. appmanifest.xml ファイルを開き、[ スタート ページ] の値を ProxyPageApp/Pages/Home.aspx に設定します。Open the appmanifest.xml file, and set the Start page value to ProxyPageApp/Pages/Home.aspx.

ソリューションを構築して実行するにはTo build and run the solution

  1. SharePoint アドイン プロジェクトがスタートアップ プロジェクトとして設定されていることを確認します。Make sure that the SharePoint Add-in project is set as the startup project.

  2. F5 キーを選択します。Select the F5 key.

    注意

    F5 キーを押すと、Visual Studio がソリューションをビルドして、アドインを展開し、アドインのアクセス許可ページを開きます。When you press F5, Visual Studio builds the solution, deploys the add-in, and opens the permissions page for the add-in.

  3. [信頼する] ボタンを選択します。Select the Trust It button.

    ホーム ページが開き、次のようになります。語句 "Just some text" が表示されるまで数秒かかる場合がありますが、これはリモート ドメインの Content.aspx ページからフェッチされるためです。The Home page will open and it should look like the following. It may take a few seconds for the phrase "Just some text" to appear because it is being fetched from the remote domain's Content.aspx page.

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

ソリューションのトラブルシューティングTable 2. 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 that you can access the SP.RequestExecutor.js file in a browser window.

関連項目See also