SharePoint アドインのセキュリティで保護されたデータ アクセスとクライアント オブジェクト モデルSecure data access and client object models for SharePoint Add-ins

SharePoint アドインのデータ アクセス オプションを評価する際は、アドインの環境を評価し、クライアントとサーバー間の通信、必要なタスクをアドインが実行するために必要なアクセス許可レベルなどのいくつかの要素を考慮する必要があります。また、SharePoint アドイン用のモデルで使用可能な API についても評価する必要があります。In evaluating your data access options for SharePoint Add-ins, you have to assess your add-in environment and consider several factors, such as communication between the client and server, and the permission level that is required for your add-in to perform the required tasks. You also have to evaluate the APIs that are available in the model for SharePoint Add-ins.

SharePoint アドイン内のデータの概要High-level overview of data in SharePoint Add-ins

データの照会、格納、または操作を必要としない SharePoint アドインを想像することは簡単ではありません (これは、どのようなアドインにも当てはまります)。It is difficult to imagine a SharePoint Add-in (or any add-in for that matter) that does not need to query, store, or manipulate data. アドインでは、多くの場合、ドキュメント ライブラリやリストに含まれるアイテム、メタデータ、ユーザー プロファイルなどの SharePoint データを取得して操作することが必要になります。In your add-in, you will frequently have to retrieve and manipulate SharePoint data, such as items in document libraries and lists, metadata, or user profiles. 同様に、アドインで外部データにアクセスする必要があるシナリオも考えられます。Similarly, you might have scenarios where you need to access external data in your add-in. SharePoint アドインのモデルには、SharePoint および外部システムに存在するデータとサービスにアクセスするために使用できる複数の接続オプションと豊富な API のセットがあります。The model for SharePoint Add-ins provides multiple connectivity options and a rich set of APIs for accessing the data and services that reside on SharePoint and on external systems.

アドインを設計しているときにデータ アクセスの計画を立てる際には、次の 2 つの重要な決定を下す必要があります。As you design your add-in and plan for data access, you have to make two key decisions:

  1. どの接続オプションを使用すべきか。Which connectivity option should I use?
  2. 必要なデータへのアクセスにどの API を使用すべきか。What APIs should I use for accessing the data I need?

以下の図では、SharePoint アドイン用のモデル で提供されているさまざまなオプションをまとめています。以降のセクションで、各オプションの詳細と、どのような場合にそれらを使用するかを示します。The following figures summarize the different options that are provided by the model for SharePoint Add-ins. In the sections that follow, you will examine each option in detail and learn when to use them.

図 1 は、アドインから SharePoint データにアクセスする場合のオプションを示しています。Figure 1 illustrates the options you have for accessing SharePoint data in your add-in. このようなシナリオを扱うときには、SharePoint に対する認証と通信に、(1) OAuth と (2) クロスドメイン ライブラリのどちらを使用するかを決定する必要があります。When you are dealing with these scenarios, you have to decide whether you want to authenticate and communicate to SharePoint by using (1) OAuth or (2) the cross-domain library. データ アクセス API については、(3) クライアント オブジェクト モデル (JavaScript/.NET クライアント オブジェクト モデル) と (4) Representational State Transfer (REST) のどちらにするかを決定する必要があります。For the data access API, you must decide between (3) the client object model (JavaScript/.NET client object models) or (4) Representational State Transfer (REST).

特定のデータにアクセスするために (5) リモート イベント レシーバーを使用することもできますが、リモート イベント レシーバーの主なシナリオはリモートのコードの実行であることに注意してください。Keep in mind that you can also access certain data using (5) remote event receivers; however, the main scenario for remote event receivers is remote code execution.

図 1. アドインで SharePoint データを使用するためのオプションFigure 1. Options for using SharePoint data in your add-in

アドインで SharePoint データを使用するためのオプション

図 2 は、アドインで外部データにアクセスする場合のオプションを示しています。Figure 2 shows the options that you have for accessing external data on your add-in. このようなシナリオを扱うときには、外部サービスまたはシステムとの認証と通信に、(1) Web プロキシ、(2) 外部コンテンツ タイプ、または (3) クロスドメイン ライブラリとカスタム プロキシ ページのうち、どれを使用するかを決定する必要があります。When you are working with these scenarios, you have to decide whether you want to use (1) the web proxy, (2) external content types, or (3) the cross-domain library with a custom proxy page to authenticate and communicate with external services or systems. さらに、(4) クライアント オブジェクト モデル (JavaScript/.NET クライアント オブジェクト モデル) または (5) Representational State Transfer (REST) も使用できます。You can also use (4) the client object model (JavaScript/.NET client object models) or (5) Representational State Transfer (REST).

図 2. アドインで外部データを使用するためのオプションFigure 2. Options for using external data in your add-in

アドインで外部データを使用するためのオプション

SharePoint アドインのデータ接続オプションData connectivity options for SharePoint Add-ins

アドインでデータを操作するときには、いくつかの側面を考慮する必要があります。You have to consider several aspects when you work with data in your add-in. たとえば、データはどのルートを使用するのか、For example, what route is the data using? サーバーから到着するのか、サーバーを経由するのか、Is it coming from or going through the server? クライアントを経由するのか、Is it going through the client? サインインしているユーザーとして認証しても問題ないのか、Is it okay to authenticate as the signed-in user? アドインには昇格された権限が必要なのか、について考慮する必要があります。Does the add-in need elevated privileges? 次からの各セクションでは、このような疑問点の解決に役立つ説明を示します。The following sections can help you with these and other questions you may have.

SharePoint データの場合の接続SharePoint data connectivity

SharePoint データにアクセスするときには、次の接続オプションを使用できます (図 1 を参照)。The following connectivity options are available when accessing SharePoint data (see Figure 1):

  • OAuth: 単純で標準的な方法で安全な承認が可能になるオープン プロトコルです。OAuth: An open protocol that enables secure authorization in a simple and standard way. OAuth を使用することで、ユーザーは自分のユーザー名とパスワードを共有することなく、アプリケーションがユーザーの代わりに動作することを承認できます。OAuth enables users to approve an application to act on their behalf without sharing their user name and password. OAuth はサーバー側コードと併用できます。You can use OAuth with server-side code. これは、非対話型のプロセスを実行する必要がある場合や、サインインしているユーザーの権限よりも高い権限に昇格する必要がある場合に適したオプションです。It is a good option if you need to run a non-interactive process, or if you need to elevate privileges to other than those of the signed-in user. OAuth の詳細については、「SharePoint アドインの承認と認証」を参照してください。For information about OAuth, see Authorization and authentication of SharePoint Add-ins.

  • Cross-domain library: JavaScript ファイル (SP.RequestExecutor.js) 形式のクライアント側の代替手段です。このファイルは、リモート アドインで参照できる SharePoint Web サイトでホストされます。Cross-domain library: A client-side alternative in the form of a JavaScript file (SP.RequestExecutor.js) hosted in the SharePoint website that you can reference in your remote add-in. クロスドメイン ライブラリを使用すると、プロキシ経由でリモート アドイン ページ内の複数のドメインとの対話型操作が可能になります。The cross-domain library allows you to interact with more than one domain in your remote add-in page through a proxy. これは、サーバーではなくクライアントでアドイン コードを実行する場合や、SharePoint とリモート インフラストラクチャの間にファイアウォールなどの接続の遮蔽物がある場合に適したオプションです。This is a good option if you prefer your add-in code to run in the client rather than in the server, or if there are connectivity barriers, such as firewalls, between SharePoint and your remote infrastructure. 詳細については、「クロスドメイン ライブラリを使用してアドインから SharePoint のデータにアクセスする」を参照してください。For more information, see Access SharePoint data from add-ins using the cross-domain library.

  • リモート イベント レシーバー: リモート イベント レシーバーを使用すると、アドイン内のアイテム (リスト、リスト アイテム、Web など) に対して発生するイベントを処理できます。Remote event receivers: You can use remote event receivers to handle events that occur to an item in the add-in, such as a list, a list item, or a web. こうしたイベントは、従来の SharePoint ソリューションのイベントに似ていますが、SharePoint アドインのリモート コンポーネントで処理できる点が異なります。These events resemble those in a traditional SharePoint solution, except that they can work with the remote components of the SharePoint Add-in. アイテムの一部のプロパティは、リモート イベント レシーバーで利用できる点に注目してください。Note that some properties of the item are available to the remote event receiver. 詳細については、「SharePoint アドインでリモート イベント レシーバーを作成する」を参照してください。同様に、アドインのイベント レシーバーを使用すると、アドインのインストール、更新、およびアンインストールの方法をカスタマイズできます。For more information, see Create a remote event receiver in SharePoint Add-ins. In a similar way, you can use add-in event receivers to customize how your add-in is installed, updated, and uninstalled. 詳細については、「SharePoint アドインでアドイン イベント レシーバーを作成する」を参照してください。For more information, see Create an add-in event receiver in SharePoint Add-ins.

SharePoint データ接続オプション: どれを使うべきかSharePoint data connectivity options: Which one should I use?

以下の表は、アドインの作成中に発生する可能性のある一般的な要件とシナリオを示しています。列内の は、各ケースで使用できるオプションを示しています。The following table lists the common requirements and scenarios you might encounter when you are building add-ins. An x in the column indicates which option you can use in each case.

表 1. SharePoint データ接続オプションTable 1. SharePoint data connectivity options

要件/シナリオRequirement/Scenario OAuthOAuth クロスドメイン ライブラリCross-domain library
クライアント側の技術 (HTML + JavaScript) を使用します。I use client-side technologies (HTML + JavaScript). xx
REST インターフェイスを使用する。I want to use REST interfaces. xx xx
SharePoint とリモート アドインの間にファイアウォールがあり、There is a firewall between SharePoint and my remote add-in,
ブラウザー経由で呼び出しを発行する必要がある。and I need to issue the calls through the browser.
xx
アドインでサインインしているユーザーとしてリソースにアクセスする必要がある。My add-in needs to access resources as the signed-in user. xx xx
アドインで現在サインインしているユーザーの権限レベルとはMy add-in needs to elevate privileges to other than
異なるレベルに権限を昇格する必要がある。those of the current signed-in user.
xx
サインインしているユーザーとは異なるユーザーの代わりにアドインが動作する必要がある。My add-in needs to act on behalf of a user other than the one who is signed in. xx
ユーザーがサインインしている間のみアドインが処理を実行する必要がある。My add-in needs to perform operations only while the user is signed in. xx xx
ユーザーがサインインしていないときにもアドインが処理を実行する必要がある。My add-in needs to perform operations even when the user is not signed in. xx
リモート コードを SharePoint のイベントに対する応答としてアドインが実行する必要がある。My add-in needs to execute remote code as a response to an event in SharePoint.

リモート イベント レシーバーは OAuth の上に構築されているため、この表の比較によって使用するかどうかを決定することは最適な方法ではありません。Because Remote Event Receivers are built on top of OAuth, a comparison in this table is not the best way to decide whether you should use them or not. リモート イベント レシーバーは、データ交換だけでなくリモート コードの実行も必要になる場合に使用します。Use Remote Event Receivers when you need to execute remote code in addition to data exchange.

外部データの場合の接続External data connectivity

外部データにアクセスするときに次の接続オプションが使用できます (図 2 を参照)。The following connectivity options are available when accessing external data (see Figure 2):

  • Web プロキシ: 開発者は、JSOM などのクライアント API で公開されている Web プロキシを使用できます。Web プロキシを使用する場合は、SharePoint に最初の要求を発行します。そうすると、指定されたエンドポイントに対して SharePoint がデータを要求し、応答をページに転送します。サーバー レベルで通信を行う場合は、Web プロキシを使用します。Web プロキシは認証を必要としない非構造化データへのアクセスを目的として設計されています。詳しくは、「 SharePoint で Web プロキシを使用してリモート サービスのクエリを実行する」をご覧ください。Web proxy: As a developer, you can use the web proxy exposed in client APIs such as the JSOM. When you use the web proxy, you issue the initial request to SharePoint. In turn, SharePoint requests the data to the specified endpoint and forwards the response back to your page. Use the web proxy when you want the communication to occur at the server level. The web proxy is designed to access unstructured data that doesn't require authentication. For more information, see Query a remote service using the web proxy in SharePoint.

  • 外部コンテンツ タイプ: テナント管理者の関与なしに SAP、Netflix からの外部データ、および独自仕様やその他の種類のデータにアクセスするアドインを作成できます。External content types: You can create add-ins that access external data from SAP, Netflix, and proprietary and other types of data without involving the tenant administrator. 外部アプリケーションへのアクセスは Business Connectivity Services (BCS) によって管理され、他の SharePoint アプリケーションから使用できる統一された一貫性のあるインターフェイスが提供されます。Access to external applications is maintained through Business Connectivity Services (BCS), which provides a consistent and uniform interface that can be used by other SharePoint applications. アプリを対象範囲とする ECT は、BCS モデルを使用しているときに、認証が必要なデータにアクセスする際に適切なオプションです。App-scoped ECTs are a good option when you are using a BCS model and access to the data requires authentication. 詳細については、「アドイン スコープの外部コンテンツ タイプ (SharePoint)」を参照してください。For more information, see Add-in-scoped external content types in SharePoint.

  • クロスドメイン ライブラリ用のカスタム プロキシ ページ: リモート アドイン インフラストラクチャでホストされるカスタム プロキシ ページを提供すると、クロスドメイン ライブラリを使用してリモート アドイン上のデータにアクセスできます。開発者は、カスタム プロキシ ページを実装する責任を負い、リモート アドインに対する認証メカニズムなどのカスタム ロジックを提供する必要があります。クライアント レベルで通信を行う場合は、クロスドメイン ライブラリとカスタム プロキシ ページを使用します。詳細については、「 SharePoint のクロスドメイン ライブラリのカスタム プロキシ ページを作成する」をご覧ください。Custom proxy page for the cross-domain library: 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 the custom proxy page implementation and must provide 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. For more information, see Create a custom proxy page for the cross-domain library in SharePoint.

外部データ接続オプション: どれを使うべきか。External data connectivity options: Which one should I use?

以下の表は、アドインの作成中に発生する可能性のある一般的な要件とシナリオを示しています。列内の は、各ケースで使用できるオプションを示しています。The following table lists the common requirements and scenarios you might encounter when you are building add-ins. An x in the column indicates which option you can use in each case.

表 2. 外部データ接続オプションTable 2. External data connectivity options

要件/シナリオRequirement/Scenario Web プロキシWeb proxy 外部コンテンツ タイプExternal content types カスタム プロキシ ページを含むクロスドメイン ライブラリCross-domain library with custom proxy page
クライアント側の技術 (HTML + JavaScript) を使用します。I use client-side technologies (HTML + JavaScript). xx xx xx
リモート アドインまたはサービスにページまたはコンポーネントを追加できない。I cannot add pages or components to the remote add-in or service. xx xx
REST インターフェイスを使用する。I want to use REST interfaces. xx xx xx
JavaScript CSOM を使用する。I want to use the JavaScript CSOM. xx xx xx
.NET CSOM を使用する。I want to use the .NET CSOM. xx xx
SharePoint インフラストラクチャとアドインとの間に直接接続がない。ブラウザーを介して呼び出しを発行する必要がある。There is no direct connectivity between the SharePoint infrastructure and my add-in. I need to issue calls through the browser. xx xx
アドインでサインインしているユーザーとしてリソースにアクセスする必要がある。My add-in needs to access resources as the signed-in user. xx xx xx

SharePoint アドインに使用可能なデータ アクセス APIAvailable data access APIs for SharePoint Add-ins

アドインから SharePoint データにアクセスするときには、次の API からの選択が可能です。The following API choices are available when you want to access SharePoint data from your add-in:

  • Representational State Transfer (REST): JavaScript を使用せず, .NET Framework プラットフォーム上に構築されていないクライアント環境から SharePoint エンティティにアクセスする必要があるシナリオでは、SharePoint は、 Open Data (OData) protocolを使用して SharePoint データに対して CRUDQ (作成、読み取り、更新、削除、クエリ) 操作を実行する REST Web サービスの実装を提供します。さらに、クライアント オブジェクト モデルのほとんどすべての API には、対応する REST エンドポイントがあります。これにより、ユーザーのコードは、標準の REST 機能をサポートする技術を使用することで SharePoint と直接やり取りできます。SharePoint に組み込まれている REST 機能を使用するには、目的の SharePoint オブジェクトに対応するエンドポイントに対しての REST 対応の HTTP 要求をコードに記述して作成します。REST サービスは HTTP 要求を処理し、Atom 形式か JavaScript Object Notation (JSON) 形式で応答をします。SharePoint における REST の詳細については、「 SharePoint REST 要求で OData クエリ操作を使用する」をご覧ください。Representational State Transfer (REST): For scenarios in which you need to access SharePoint entities from client technologies that do not use JavaScript and are not built on the .NET Framework platform, SharePoint provides an implementation of a REST web service that uses the Open Data (OData) protocol to perform CRUDQ (Create, Read, Update, Delete, and Query) operations on SharePoint data. In addition, nearly every API in the client object models has a corresponding REST endpoint. This enables your code to interact directly with SharePoint by using any technology that supports standard REST capabilities. To use the REST capabilities that are built into SharePoint, your code constructs a RESTful HTTP request to an endpoint that corresponds to the desired SharePoint object. The REST service handles the HTTP request and serves a response in either Atom or JavaScript Object Notation (JSON) format. To learn more about REST in SharePoint, see Use OData query operations in SharePoint REST requests.

  • .NET Framework クライアント オブジェクト モデル (.NET クライアント OM): サーバー側オブジェクト モデルの主要なサイトやリストのほとんどすべてのクラスには, .NET Framework クライアント オブジェクト モデルに該当するクラスがあります。さらに, .NET Framework クライアント オブジェクト モデルでは、ECM、分類、ユーザー プロファイル、詳細検索、分析、BCS などの SharePoint レベルの機能を拡張するための API のフル セットも公開されています。クライアント側オブジェクト モデルの詳細については、「 SharePoint での適切な API セットの選択」をご覧ください。.NET Framework client object model (.NET client OM): Almost every class in the core site and list server-side object model has a corresponding class in the .NET Framework client object model. In addition, the .NET Framework client object model also exposes a full set of APIs for extending other features, including some SharePoint-level features such as ECM, taxonomy, user profiles, advanced search, analytics, BCS, and others. To learn more about client-side object models, see Choose the right API set in SharePoint.

  • JavaScript クライアント オブジェクト モデル (JSOM): SharePoint は、インライン スクリプトや別途作成した .js ファイルで使用するための JavaScript オブジェクト モデルを提供します。このモデルには, .NET Framework クライアント オブジェクト モデルと同じ機能がすべて含まれます。カスタム サーバー側コードを使用できない SharePoint ホスト型アドイン では特に、JSOM は、アドインにカスタム SharePoint コードを追加するための有用な方法になります。また、Web 開発者は、既存の JavaScript のスキルを使用し、あまり学習に時間をかけずに SharePoint アドイン を作成できます。クライアント側オブジェクト モデルの詳細については、「 SharePoint での適切な API セットの選択」をご覧ください。JavaScript client object model (JSOM): SharePoint provides a JavaScript object model for use in either inline script or separate .js files. It includes all the same functionality as the .NET Framework client object model. The JSOM is a useful way of including custom SharePoint code in an add-in, especially in a SharePoint-hosted add-in, where custom server-side code is not allowed. It also enables web developers to use their existing JavaScript skills to create SharePoint Add-ins with a minimal learning curve. To learn more about client-side object models, see Choose the right API set in SharePoint.

外部データへのアクセス時に SharePoint アドインで使用できる API は他にも存在し、それは外部サービスおよびシステムで提供するインターフェイスに依存します。設計時には、これらのインターフェイスについても考慮する必要があります。There might be additional APIs that you can use in your SharePoint Add-in when accessing external data. It depends on what interfaces the external services and systems have to offer. You should also consider these interfaces in your design.

関連項目See also