クロスドメイン ライブラリを使用してアドインから SharePoint のデータにアクセスする

SharePoint アドインを作成するときは通常、さまざまなソースからデータを取り込む必要があります。 ただし、セキュリティ上の理由から、ブロック メカニズムによって一度に複数のドメインとの通信は防止されます。 このようなセキュリティ メカニズムはほとんどのブラウザーに実装されており、ドメイン間のクライアント側の呼び出しが困難、または不可能になります。

ユーザーがアドイン ドメインからページを要求すると、クライアント側の通知はそのドメインにのみ限定されます。 アドインでは、そのページから同じドメイン内の別のリソースにのみ、クライアント側呼び出しを発行できます。 ただし、アドインでは通常、そのシナリオを実行するために、SharePoint ドメインなど他のドメインからのリソースを必要とします。 使用するページのコードでは、SharePoint ドメインへのリクエストを発行してもブラウザーでブロックされる場合があります。 通常は [アクセスが拒否されました] というエラーが表示されます。 エラーはリクエストしたリソースへのアクセス許可がないことを示すものではありませんが、大抵は、指定したリソースに対してリクエストを発行できません。

クロスドメイン ライブラリを使用する場合は、ドメイン内の Web ページからアドインのドメイン、および SharePoint ドメイン内のデータにアクセスできます。 クロスドメイン ライブラリは JavaScript ファイル (SP.RequestExecutor.js) 形式のクライアント側の代替手段です。このファイルは、リモート アドインで参照できる SharePoint Web サイトでホストされます。 クロスドメイン ライブラリを使用すると、プロキシ経由でリモート アドイン ページ内の複数のドメインとの対話型操作が可能になります。 これは、サーバーではなくクライアントでアドイン コードを実行する場合や、SharePoint とリモート インフラストラクチャの間にファイアウォールなどの接続の遮蔽物がある場合に適したオプションです。

ホスト Web 内のデータへのアクセスが可能です。たとえば、アドインに関係なく、エンド ユーザーが対話できるリストにアクセスできます。 あるいは、使用しているアドインに特定的にプロビジョニングされているリストなど、アドイン Web にあるデータにアクセスできます。 アドインでは、そのアドインにテナント スコープのアクセス許可があり、アドイン カタログを使用したバッチ インストールとして展開されていれば、その他のサイト コレクションや Web サイトにアクセスすることもできます。

注:

このトピックでは、アドイン ドメインとはアドイン ページをホストするドメインを意味します。 つまり、プロバイダー向けのホスト型アドインのリモート Web アプリケーションのドメインですが、アドイン ページはアドイン Web の SharePoint 内で、ホスト型 Web ドメインを呼び出すものでもかまいません。 後者の場合、アドイン ドメインはアドイン Web のドメインです。

この記事の主な例では、アドイン Web 上のデータを読み取り、それを Web ページに表示するアドインの作成方法を示します。 次の手順のセクションでは、主な例に基づいて作成されたシナリオについて説明します。

前提条件

この記事に示されている例を行うには、次のものが必要です。

クロスドメイン ライブラリを使用したアドイン Web 上のデータの読み取り

この例では、SharePoint の外部でホストされている単純なページがあり、Representational State Transfer (REST) エンドポイントを使用して SharePoint Web サイト (アドイン Web) 内のデータを読み取っています。 クロスドメイン ライブラリではアドイン Web が必要であるため、このシナリオで開始するのは良い方法です。

アドイン Web からデータを読み取るには、次のことを実行する必要があります。

  1. SharePoint アドインと Web プロジェクトを作成します。

  2. アドイン Web でリスト アイテムを作成します。 この手順により、アドインの展開時にアドイン Web が作成されるようになります。

  3. クロスドメイン ライブラリを使用してリスト アイテムを読み取るアドイン ページを作成します。

次の図に、アドイン Web 上のデータを表示する Web ページを示します。

クロス ドメイン読み取り項目のサンプル結果画面

SharePoint アドインと Web プロジェクトを作成する方法

  1. 管理者として Visual Studio を開きます (これを行うには、[スタート] メニューの [Visual Studio] アイコンを右クリックし、[管理者として実行] を選択します)。

  2. SharePoint 用アドイン テンプレートを使用して新しいプロジェクトを作成します。 Visual Studio の [SharePoint 用アドイン] テンプレートは、[テンプレート]>[Visual C#]>[Office SharePoint]>[アドイン] にあります。

  3. デバッグに使用する SharePoint Web サイトの URL を入力します。

  4. アドインのホスティング オプションとして [プロバイダー向けのホスト型] を選択します。

    注:

    SharePoint ホスト型アドインでクロスドメイン ライブラリを使用することもできます。 ただし、SharePoint ホスト型アドインでは、アドイン ページは既にアドイン Web にあり、その場合はリスト アイテムの読み込みにクロスドメイン ライブラリは必要ありません。 ホスト Web 上にあるデータを読み取る SharePoint でホストされているアドイン サンプルについては、「SharePoint ホスト型アドインでクロスドメイン ライブラリを使用する (REST) 」またはこの記事の後半の「ホスト Web からのデータ アクセス」を参照してください。

アドイン Web でリスト アイテムを作成するには

  1. ソリューション エクスプローラーで SharePoint アドイン プロジェクトを右クリックします。 [追加]>[新しいアイテム] を選択します。

  2. [Visual C# アイテム]>[Office/SharePoint]>[リスト] の順に選択します。 リストの名前を [お知らせ] に設定します。

  3. [お知らせ]>[Elements.xml] をダブルクリックします。 次の XML ノードを ListInstance 要素の子として貼り付けます。

    <Data>
        <Rows>
            <Row>
                <Field Name="Title">Lorem ipsum 1</Field>
                <Field Name="Body">Sed ut perspiciatis, unde omnis iste...</Field>
            </Row>
            <Row>
                <Field Name="Title">Lorem ipsum 2</Field>
                <Field Name="Body">Sed ut perspiciatis, unde omnis iste...</Field>
            </Row>
        </Rows>
    </Data>
    

クロスドメイン ライブラリを使用するアドイン ページを作成するには

  1. ソリューション エクスプローラーで Web プロジェクトの Default.aspx をダブルクリックします。

  2. 以下のコードをコピーし、Default.aspx ファイルに貼り付けます。 このコードは次のタスクを実行します。

    • Microsoft CDN から jQuery ライブラリを読み込みます。

    • 結果のプレースホルダーを提供します。

    • クエリ文字列からアドイン Web の URL を抽出します。

    • jQuery の getScript 関数を使用して、クロスドメイン ライブラリ JavaScript を読み込みます。

      関数によって必要なリソースが読み込まれ、指定された関数の実行が続行されます。これにより、クロスドメイン ライブラリが読み込まれ、後続のコードで利用できるようになります。

    • RequestExecutor オブジェクトのインスタンスを作成します。 既定では、RequestExecutor はアドイン Web をコンテキスト サイトとして使用します。

      注:

      (REST) またはオブジェクト (JSOM)。 AppContextSite の詳細については、この記事で後述する「ホスト Web からのデータ アクセス」を参照してください。

    • リスト アイテム エンドポイントへの REST 呼び出しを発行します。

    • 成功した実行を処理し、Web ページにリスト アイテムを表示します。

    • エラーを処理し、リモート Web ページにエラー メッセージを表示します。

  
<html>
    <head>
        <title>Cross-domain sample</title>
    </head>
    <body>
        <!-- This is the placeholder for the announcements -->
        <div id="renderAnnouncements"></div>
        <script 
            type="text/javascript" 
            src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
        </script>
        <script type="text/javascript">
          var hostweburl;
          var appweburl;

          // Load the required SharePoint libraries
          $(document).ready(function () {
            //Get the URI decoded URLs.
            hostweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPHostUrl")
            );
            appweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPAppWebUrl")
            );

            // resources are in URLs in the form:
            // web_url/_layouts/15/resource
            var scriptbase = hostweburl + "/_layouts/15/";

            // Load the js files and continue to the successHandler
            $.getScript(scriptbase + "SP.RequestExecutor.js", execCrossDomainRequest);
          });

          // Function to prepare and issue the request to get
          //  SharePoint data
          function execCrossDomainRequest() {
            // executor: The RequestExecutor object
            // Initialize the RequestExecutor with the add-in web URL.
            var executor = new SP.RequestExecutor(appweburl);

            // Issue the call against the add-in web.
            // To get the title using REST we can hit the endpoint:
            //      appweburl/_api/web/lists/getbytitle('listname')/items
            // The response formats the data in the JSON format.
            // The functions successHandler and errorHandler attend the
            //      sucess and error events respectively.
            executor.executeAsync(
                {
                  url:
                      appweburl +
                      "/_api/web/lists/getbytitle('Announcements')/items",
                  method: "GET",
                  headers: { "Accept": "application/json; odata=verbose" },
                  success: successHandler,
                  error: errorHandler
                }
            );
          }

          // Function to handle the success event.
          // Prints the data to the page.
          function successHandler(data) {
            var jsonObject = JSON.parse(data.body);
            var announcementsHTML = "";

            var results = jsonObject.d.results;
            for (var i = 0; i < results.length; i++) {
              announcementsHTML = announcementsHTML +
                  "<p><h1>" + results[i].Title +
                  "</h1>" + results[i].Body +
                  "</p><hr>";
            }

            document.getElementById("renderAnnouncements").innerHTML =
                announcementsHTML;
          }

          // Function to handle the error event.
          // Prints the error message to the page.
          function errorHandler(data, errorCode, errorMessage) {
            document.getElementById("renderAnnouncements").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>
    </body>
</html>

ソリューションをビルドして実行するには

  1. F5 キーを選択します。

    注:

    F5 キーを押すと、Visual Studio がソリューションをビルドして、アドインを展開し、アドインのアクセス許可ページを開きます。

  2. [信頼する] ボタンを選択します。

  3. [サイト コンテンツ] ページのアドイン アイコンを選択します。

ダウンロード可能なコード サンプルを使用する場合は、コード ギャラリーから次を取得できます。

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

このエラー メッセージが表示される場合… 次を試します…
「申し訳ございません。サイトへのアクセス中に問題が発生しました。エラーを修正するボタンもありますが、問題は解決されません。」 Internet Explorer のセキュリティ ゾーンに関する既知の問題に該当する可能性があります。「SharePoint アドインで Internet Explorer の異なるセキュリティ ゾーンを横断してクロスドメイン ライブラリを操作する」をご覧ください。
「必要な機能がお使いのブラウザーでサポートされていません。 IE 8 以上または他の最新ブラウザーを使用していることを確認してください。 'X-UA-Compatible' メタ タグが 'IE=8' 以上に設定されていることを確認してください。」 クロスドメイン ライブラリでドキュメント モードが IE8 以上である必要があります。 一部のシナリオでは、ドキュメント モードが既定で IE7 に設定されています。 Internet Explorer 開発者ツールを使用して、ページのドキュメント モードを判断し、変更することができます。 詳細については、「文書の互換性の定義」を参照してください。
「[種類] が定義されていません。 さらに、アドインで JavaScript Object Model (JSOM) を使用しています。」 JSOM は Microsoft Ajax ライブラリの Type.registerNamespace メソッドを使用して SP 名前空間を登録します。 次のコードを使用して、お使いのページから Microsoft Ajax ライブラリにリファレンスを追加してください。

HTML <script type="text/javascript" src="//ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"></script>

次の手順: その他のクロスドメイン ライブラリ シナリオ

この記事では、REST エンドポイントにクエリして、SharePoint でホストされていないアドイン ページを使用してアドイン Web からデータを読み取る方法を説明します。 次のシナリオを参照して、クロスドメイン ライブラリの詳細を確認することもできます。

JSOM を使用したアドイン Web からのデータの読み取り

設定によっては、REST ではなく JSOM を使用してアドイン Web からデータのクエリを実行することもできます。 JSOM でクロスドメイン ライブラリを使用するには、追加タスクを実行する必要があります。

  • アドイン ページで SharePoint JSOM を参照します。

  • ProxyWebRequestExecutorFactory オブジェクトを初期化し、コンテキスト オブジェクトのファクトリとして設定します。

  • SharePoint オブジェクトにアクセスして、リストからデータを読み取ります。

  • コンテキストでオブジェクトを読み込み、クエリを実行します。

タスクの実行方法を示すコード サンプルについては、SharePoint-Add-in-JSOM-CrossDomain をご覧ください。

JSOM の使用方法の詳細については、「SharePoint 用アドインでの JavaScript オブジェクト モデル (JSOM) の使用」を参照してください。

ホスト Web からのデータ アクセス

このページの例では、アドイン Web からデータを読み取る方法を示します。 クロスドメイン ライブラリではアドインが最初にコンテキスト サイトとして使用されるため、これが開始の例として適しています。 ただし、ホスト Web のデータへのアクセスが必要なシナリオも多数あります。 いくつかのタスクでは、ホスト Web 上のデータにアクセスする必要があります。

  • ホスト Web をクロスドメイン ライブラリのコンテキスト サイトとして設定します。

  • アドインに適切なアクセス許可を付与します。

AppContextSite エンドポイント (REST) またはオブジェクト (JSOM) を使用すると、コンテキスト サイトを変更できます。 次の例では、REST エンドポイントを使用してコンテキスト サイトを変更する方法を示します。

executor.executeAsync(
    {
        url:
            appweburl +
            "/_api/SP.AppContextSite(@target)/web/title?@target='" +
            hostweburl + "'",
        method: "GET",
        headers: { "Accept": "application/json; odata=verbose" },
        success: successHandler,
        error: errorHandler
    }
);

次のコード例では、JSOM を使用してコンテキスト サイトを変更する方法を示します。

context = new SP.ClientContext(appweburl);
factory = new SP.ProxyWebRequestExecutorFactory(appweburl);
context.set_webRequestExecutorFactory(factory);
appContextSite = new SP.AppContextSite(context, hostweburl);

this.web = appContextSite.get_web();
context.load(this.web);

既定では、アドインにはアクセス許可が付与されますが、ホスト Web にはアクセス許可が付与されません。 次の例は、ホスト Web からデータを読み取るためのアクセス許可要求を宣言するマニフェスト セクションを示しています。

<AppPermissionRequests>
    <AppPermissionRequest 
        Scope="http://sharepoint/content/sitecollection/web" 
        Right="Read" />
</AppPermissionRequests>

必ずアドイン Web で (空白のページまたはリストのような) リソースを作成して、クロスドメイン ライブラリを使用するために必要な、アドイン Web のプロビジョニングを行います。

サイト コレクション間でのデータ アクセス

クロスドメイン ライブラリでは、同じテナント内のサイト コレクション間でデータにアクセスできます。 サイト コレクション間でデータにアクセスするには、いくつかのタスクを実行する必要があります。

  • テナント内のデータにアクセスするためのアクセス許可要求を追加します。

  • コードで、クエリするサイト コレクションにコンテキスト サイトを切り替えます。

  • アドインをアドイン カタログに追加します。

  • テナント スコープ アドインとして Web サイトにアドインを展開します。 たとえば、テナント スコープ アドインとして展開する方法については、「テナント スコープ アドインでクロスドメイン ライブラリを使用する (REST)」のコード サンプルに関する説明をご覧ください。

アドインには、テナントからデータにアクセスするためのアクセス許可も必要です。 次の例は、テナントからデータを読み取るためのアクセス許可要求を宣言するマニフェスト セクションを示しています。

<AppPermissionRequests>
  <AppPermissionRequest 
    Scope="http://sharepoint/content/tenant" 
    Right="Read" />
</AppPermissionRequests>

コードでコンテキスト サイトに切り替えるには、「ホスト Web からのデータ アクセス」セクションと同様に、AppContextSite エンドポイント (REST) またはオブジェクト (JSOM) を使用します。

REST エンドポイント /_api/SP のリマインダーを次に示します。AppContextSite(@target)/web/title?@target='weburl'、および JSOM でオブジェクトをインスタンス化する方法の例: appContextSite = new SP.AppContextSite(context, weburl);

開発者は、テナント スコープ アドインをアドイン カタログからのみ展開できます。 アドイン カタログはオンプレミスまたは SharePoint Online 環境に対してプロビジョニングできます。 アドイン カタログへのアドインのアップロードは、ドキュメント ライブラリへのファイル アップロードと同じように簡単にできます。 詳細な手順については、「アプリ カタログを使ってカスタム ビジネス アプリを SharePoint Online 環境で利用できるようにする」を参照してください。

アドイン カタログからは、テナント内の 1 つ以上の Web サイトにアドインを展開することができます。 アドインはテナント内のデータへのアクセスが許可されているため、1 つの Web サイトに展開するだけで、テナント全体のデータにアクセスできます。 アドイン カタログからアドインを展開する方法については、「カスタム アドインを展開する」を参照してください。

サイト コレクション間でデータにアクセスする方法を示すコード サンプルをダウンロードするには、「テナント スコープ アドインでクロスドメイン ライブラリを使用する (REST)」をご覧ください。

異なるセキュリティ ゾーン間での呼び出しの発行

クロスドメイン ライブラリでは、アドイン ページの IFrame でホストされているプロキシ ページを使用して通信を可能にします。 アドイン ページと SharePoint Web サイトが別のセキュリティ ゾーンにある場合、認証 Cookie は送信されません。 認証 Cookie がなく、IFrame がプロキシ ページを読み取ろうとすると、SharePoint サインイン ページにリダイレクトされます。 SharePoint サインイン ページは、セキュリティ上の理由から IFrame には組み込めません。 これらのシナリオでは、ライブラリはプロキシ ページを読み込めず、SharePoint と通信することはできません。

ただし、これらのシナリオには解決策があります。 解決策は、アドイン ページをアドイン Web でホストされているページでラップする アプリホスト パターン です。 明らかなセキュリティ境界がない場合でも、クロスドメイン ライブラリを使用するアドインではアプリホスト パターンを使用することをお勧めします。 詳しくは、「 SharePoint アドインで Internet Explorer の異なるセキュリティ ゾーンを横断してクロスドメイン ライブラリを操作する」をご覧ください。

SharePoint ホスト型アドインのその他のリモート ホストからデータへのアクセス

既定では、適切なアクセス許可があれば、SharePoint ホスト型アドイン はホスト Web へのクロスドメイン呼び出しを発行できます。 ただし、SharePoint ホスト型アドイン は AppPrincipalAllowedRemoteHostUrl 属性でリモート ホストを指定することもできます。 これにより、アドイン Web やほかの場所にある別のホストからもクロスドメイン呼び出しを発行できます。

クロスドメイン ライブラリを使用する SharePoint ホスト型アドインのサンプルをダウンロードする場合は、「コード サンプル: SharePoint ホスト型アドイン (REST) でクロスドメイン ライブラリを使用する」をご覧ください。

関連項目