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

Get started creating provider-hosted SharePoint Add-ins で説明してあるとおり、開発環境が必要です。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 アイコンを右クリックし、管理者として実行 を選択します。)(To do this, right-click the Visual Studio icon on the Start menu, and select Run as administrator.)

  2. プロバイダーホスト型 SharePoint アドインの作成を始めるで説明されているように、プロバイダーホスト型 SharePoint アドインの作成を開始して、 StylesheetAdd-inという名前を付けます。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 ソリューションの作成後、(SharePoint アドイン プロジェクトではなく) Web アプリケーション プロジェクトを右クリックして、追加 > 新しい項目 > [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. AppPartContent.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 フォームを追加します。フォーム 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. モジュール ページに名前を付け、次に 追加を選択します。Name the module Pages, and then choose Add.

  3. ページ フォルダを右クリックし、追加 > 新商品 > オフィス/ 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 select 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 Web ページ

ソリューションのトラブルシューティング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