クロス ドメイン ライブラリを使用する SharePoint アドインを作成するCreating SharePoint Add-ins that use the cross-domain library

低信頼承認システムと高信頼承認システムのいずれも SharePoint アドインで使用できないか、アドインが SharePoint リソースへの承認を得る唯一の手段としてふさわしい選択ではないシナリオがいくつかあります。たとえば、次のような場合です。There are some scenarios in which neither the low-trust nor the high-trust authorization systems can be used by a SharePoint Add-in, or they are not a good choice as the only means for the add-in to gain authorization to SharePoint resources. Examples:

例:Examples:

  • SharePoint アドインのリモート コンポーネントがオンプレミスではなく、企業のファイアウォールが SharePoint と ACS のサーバー間通信をブロックしているため、低信頼システムを使用することができない。The remote components of the SharePoint Add-in are not on-premise, but a corporate firewall blocks server-to-server communication between SharePoint and ACS, thereby preventing the use of the low-trust system.

  • SharePoint アドインが、SharePoint でのデータ処理にクライアント側の JavaScript に依存する単一ページの Web アプリケーションとして設計されている。The SharePoint Add-in is designed as a single-page web application that relies on client-side JavaScript for data operations with SharePoint.

  • SharePoint アドインは、主にサーバー間の呼び出しに依存して、SharePoint のデータにアクセスします (また、低信頼システムまたは高信頼システムによって承認されます) が、いくつかの JavaScript 呼び出しによって補足する必要があります。たとえば、グラフィックの負荷が高いページで表示されるデータに小さな更新を行うには、JavaScript を使用することにより、ページ全体の再読み込みなしで行うことができます。The SharePoint Add-in relies mainly on server-to-server calls to access SharePoint data (and is authorized by either the low-trust or high-trust systems), but it needs to be supplemented with some JavaScript calls. For example, a graphics-heavy page can use JavaScript to make minor updates to displayed data without having to reload the entire page.

しかしながら、 セキュリティのためにブラウザは、あるドメインでホストされているJavaScriptが別のドメインのリソースにアクセスすることを許可していないため、リモートJavaScriptがSharePointリソースにアクセスできるようにする特別な技術が必要です。However, for security, browsers do not allow JavaScript that is hosted on one domain to access resources on another domain, so a special technique is required to allow the remote JavaScript to access SharePoint resources. The SharePoint cross-domain JavaScript library makes it easy for your remote web application to use the technique. SharePointのクロスドメインJavaScriptライブラリを使用すると、リモートWebアプリケーションでこのテクニックを簡単に使用できます。The SharePoint cross-domain JavaScript library makes it easy for your remote web application to use the technique.

注意

メモ: クロス ドメイン ライブラリは、データを逆方向でアクセスできるようにする場合にも使用されます。つまり、SharePoint ページの JavaScript がリモート ドメインのデータにアクセスできるようにします。詳細については、「SharePoint ページからのリモート データへのアクセス」を参照してください。Note The cross-domain library is also used to allow access to data in the reverse direction; that is, to allow JavaScript on a SharePoint page to access data in a remote domain. See Access remote data from a SharePoint page for more information. 詳細は、次を参照してください。 SharePointページからリモートデータにアクセスするFor more information, see Access remote data from a SharePoint page.

クロス ドメイン ライブラリのアーキテクチャを理解するUnderstand the architecture of the cross-domain library

SharePointクロスドメインライブラリは、すべてのSharePoint Webサイトの/ _layouts / 15 / virtualフォルダにあるSP.RequestExecutor.jsファイルに含まれています。The SharePoint cross-domain library is contained in the file SP.RequestExecutor.js, which is located in the /_layouts/15/ virtual folder of every SharePoint website. このファイルのスクリプトは、クロスドメインスクリプティングに関するブラウザの制限を克服するためのセキュアな既知の手法をカプセル化しています.iFrameは、 window.postMessage() iFrameのページが別のドメインにある場合でも、その機能によりペアレントページとコミュニケーション出来ます。The SharePoint cross-domain library is contained in the file SP.RequestExecutor.js which is located in the /_layouts/15/ virtual folder of every SharePoint website. The scripts in this file encapsulate a secure well-known technique for overcoming the browser's restriction on cross-domain scripting: An iFrame can communicate with its parent page by means of the window.postMessage() function, even if the page in the iFrame is in a different domain. So data requests and responses are passed over the domain boundary by using calls to . したがって、データリクエストとレスポンスは、次の呼び出しを使用してドメイン境界を超えて渡されます。 postMessage()So data requests and responses are passed over the domain boundary by using calls to postMessage().

警告

注意: postMessage() 関数は HTML 5 をサポートするブラウザーでのみ動作するため、クロス ドメイン ライブラリを使用する SharePoint アドインは、より古いブラウザーでは動作しません。Caution The postMessage() function works only on browsers that support HTML 5, so SharePoint Add-ins that use the cross-domain library will not work on older browsers.

SharePointの場合、クロスドメインライブラリはリモートWebアプリケーションのページにロードされ、SharePointドメインから特別なプロキシページをホストする非表示のiFrameを作成します。For SharePoint, the cross-domain library is loaded on a page of the remote web application where it creates a hidden iFrame that hosts a special proxy page from the SharePoint domain. プロキシページは、すべてのSharePoint Webサイトに既に存在しています。The proxy page already exists on every SharePoint website.

ライブラリは、SharePointのREST APIへのCRUD呼び出しを行うために必要なすべての情報を含むJavaScript Object Notation(JSON)オブジェクトを作成するために使用されます。 JSONオブジェクトは、以下を使用してプロキシページに渡されます。 postMessage()。ライブラリがロードされているプロキシページでは、JSONオブジェクトが解析され、SharePointへのREST呼び出しとして再構築されます。プロキシページはSharePointドメインにあるため、ブラウザは呼び出しを許可します。For SharePoint, the cross-domain library is loaded on a page of the remote web application where it creates a hidden iFrame that hosts a special proxy page from the SharePoint domain. The proxy page already exists on every SharePoint website. The library is used to create a JavaScript Object Notation (JSON) object which contains all the information needed to make a CRUD call to the REST APIs of SharePoint. The JSON object is passed to the proxy page by using postMessage(). On the proxy page, where the library is also loaded, the JSON object is parsed and reconstructed as a REST call to SharePoint. Since the proxy page is in the SharePoint domain, the browser allows the call.

もちろんそれでも、SharePoint アドインのリモート コンポーネントには、SharePoint リソースに対して承認されたアクセス権が必要です。そのためには、次の 2 つの方法があります。Of course, the remote components of the SharePoint Add-in still have to have authorized access to the SharePoint resources. There are two ways to do this:

  • アドインプリンシパルタイプを次に設定します。 RemoteWebApplication (プロバイダがホストするアプリケーションのデフォルト)をアドインマニフェストに追加します。Set the add-in principal type to RemoteWebApplication (the default for provider-hosted apps) in the add-in manifest. アドインがACSに登録されるとき、登録にはリモートWebアプリケーションのドメインが含まれます。When the add-in is registered with ACS, the registration includes the domain of the remote web application. このシナリオでは、たとえサーバーサイドの低信頼システムの一部であるどのトークンパッシングフローを使用してなくても、SharePointはACSに登録されているドメインを信頼します。SharePoint trusts domains that are registered with ACS, even though it is not, in this scenario, using any of the token passing flows that are part of the server-side low-trust system. アドインの登録の詳細については、以下を参照 SharePointアドインの登録For detailed information about registering add-ins, see Register SharePoint Add-ins.

  • SharePointでホストされるアドインでは、アドインプリンシパルタイプをデフォルトのままにしておくことができます。 内部In a SharePoint-hosted add-in, you can leave the add-in principal type set to its default, which is Internal. Then set the AllowedRemoteHostUrl attribute of the Internal element to the URL of the remote web application, as in the following example. その後、 AllowedRemoteHostUrl の属性 内部 要素を 次の例のように、リモートWebアプリケーションのURLに設定できます。In a SharePoint-hosted add-in, you can leave the add-in principal type set to its default, which is Internal. Then set the AllowedRemoteHostUrl attribute of the Internal element to the URL of the remote web application, as in the following example.

  <AppPrincipal>
    <Internal AllowedRemoteHostUrl="https://example.com/Home.html" />
  </AppPrincipal>

注意

2番目のオプション( 内部 アドインプリンシパル)では、JavaScriptとクロスドメインライブラリのみを使用してSharePointにアクセスできます。If you use the second option (an Internal add-in principal), you can use only JavaScript and the cross-domain library to access SharePoint. SharePointクライアントオブジェクトモデルがブロックされています 内部 SharePointアドインを使用すると、クロスドメインライブラリと低信頼システムまたは高信頼システムの両方を使用する二重認証システムを使用することはできません。Note If you use the second option (an Internal add-in principal), then you can use only JavaScript and the cross-domain library to access SharePoint. The SharePoint client object model is blocked for InternalSharePoint Add-ins, so you cannot have a dual authorization system that uses both the cross-domain library and either the low-trust or high-trust systems.

ライブラリを使用する方法の詳細については「クロス ドメイン ライブラリを使用してアドインから SharePoint のデータにアクセスする 」を参照してください。For details on how to use the library, see Access SharePoint data from add-ins using the cross-domain library.

SharePoint ページからリモート データにアクセスするAccess remote data from a SharePoint page

SharePointのクロスドメインライブラリは、逆方向でも使用できます。つまり、SharePointページ上のJavaScriptは、ライブラリを使用してアドインのリモートコンポーネントからデータを取得できます。The SharePoint cross-domain library can also be used in the reverse direction; that is, JavaScript on a SharePoint page can use the library to get data from the remote components of the add-in. これを行うには、クロスドメインアーキテクチャを元に戻します。つまり、リモートWebアプリケーションでプロキシページを作成します。To do this, you reverse the cross-domain architecture: you create a proxy page in the remote web application. ライブラリは、プロキシページをホストするiFrameを作成するSharePointページから呼び出されます。The library is called from a SharePoint page where it creates an iFrame to host the proxy page.

この方法でライブラリを使用する方法の詳細については、「SharePoint でクロスドメイン ライブラリ用のカスタム プロキシ ページを作成する」を参照してください。For details about how to use the library in this way, see Create a custom proxy page for the cross-domain library in SharePoint.

関連項目See also