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

[アーティクル]
04/08/2023

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

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

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

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

注:

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

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

前提条件

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

リモートでインストールされているか、SharePoint のインストール先コンピューターにインストールされている Visual Studio。
Visual Studio には、Microsoft Office Developer Tools for Visual Studio が含まれています。 Visual Studio の更新間に、このツールのバージョンがリリースされることがあります。このツールの最新バージョンを確実に入手するために、Office Developer Tools for Visual Studio 2013 用インストーラー、または Office Developer Tools for Visual Studio 2015 用インストーラーを実行してください。
オンプレミスの SharePoint 開発環境。「SharePoint アドインのオンプレミスの開発環境をセットアップする」を参照してください。

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

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

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

SharePoint アドインと Web プロジェクトを作成します。
アドイン Web でリストアイテムを作成します。この手順により、アドインの展開時にアドイン Web が作成されるようになります。
クロスドメインライブラリを使用してリストアイテムを読み取るアドインページを作成します。

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

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

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

管理者として Visual Studio を開きます (これを行うには、[スタート] メニューの [Visual Studio] アイコンを右クリックし、[管理者として実行] を選択します)。
SharePoint 用アドイン テンプレートを使用して新しいプロジェクトを作成します。 Visual Studio の [SharePoint 用アドイン] テンプレートは、[テンプレート]>[Visual C#]>[Office SharePoint]>[アドイン] にあります。
デバッグに使用する SharePoint Web サイトの URL を入力します。
アドインのホスティングオプションとして [プロバイダー向けのホスト型] を選択します。

注:

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

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

ソリューションエクスプローラーで SharePoint アドインプロジェクトを右クリックします。 [追加]>[新しいアイテム] を選択します。
[Visual C# アイテム]>[Office/SharePoint]>[リスト] の順に選択します。リストの名前を [お知らせ] に設定します。

[お知らせ]>[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>

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

ソリューションエクスプローラーで Web プロジェクトの Default.aspx をダブルクリックします。
以下のコードをコピーし、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>

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

F5 キーを選択します。

注:

F5 キーを押すと、Visual Studio がソリューションをビルドして、アドインを展開し、アドインのアクセス許可ページを開きます。
[信頼する] ボタンを選択します。
[サイトコンテンツ] ページのアドインアイコンを選択します。

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

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

このエラーメッセージが表示される場合…	次を試します…
「申し訳ございません。サイトへのアクセス中に問題が発生しました。エラーを修正するボタンもありますが、問題は解決されません。」	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 ホスト型アドインは AppPrincipal の AllowedRemoteHostUrl 属性でリモートホストを指定することもできます。これにより、アドイン Web やほかの場所にある別のホストからもクロスドメイン呼び出しを発行できます。

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

次の方法で共有

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

前提条件

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

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

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

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

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

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

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

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

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

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

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

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

関連項目

その他のリソース

次の方法で共有

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

前提条件

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

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

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

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

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

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

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

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

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

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

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

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

関連項目

その他のリソース

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

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

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

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

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

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

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

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

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