最新の SharePoint 開発については SharePoint Framework を参照してください。(この開発手法は、古い情報です。)
SharePoint Add-ins 開発
- 概要
- .NET CSOM を使ったプログラミングと認証
- Cross-domain library を使ったプログラミング
- App Part の開発
- List Definition の開発と Client Side Rendering (CSR)
- Remote Event Receiver の開発と Debug
- UI Custom Action の開発 (Ribbon のカスタマイズ)
- Workflow の開発
- On-Premises (SharePoint Server) で動く SharePoint Add-ins の作成 (Authentication)
- クラウド ビジネス アプリ (Cloud Business App)
- Patterns and Practices (PnP) による CSOM 拡張ライブラリー
こんにちは。
ここでは、SharePoint 2013 が使用可能な新しい開発手法 SharePoint Add-ins (SharePoint アドイン, 旧 App for SharePoint) を整理して解説します。
Hosting 方法
SharePoint Add-ins (SharePoint アドイン, 旧 App for SharePoint) では、SharePoint と連携して動作する Web アプリケーション本体と xml のアプリケーション定義情報があり、SharePoint にはこの定義情報がインストールされます。
一方、Web アプリケーション本体は、SharePoint 上ではなく、別の場所にホストします。この SharePoint Add-ins の Web のホスト方法として、下記の 3 通りの展開方法が使用できます。(後述しますが、それぞれは排他的ではありません。兼ねることができます。)
なお、SharePoint Add-ins では、以下で説明するように、Host Web、App Web、Remote App の 3 つのサイト (ドメインの異なるサイト) を使用します。(これらのドメインは、ブラウザーのアドレスなどで確認できます。もちろん、エンドユーザーは、普段 意識しません。)
2014/06 追記 : 下記の Autohosted (自動ホスト型) は、今後サポートされません。リモート実行の際は、後述する Provider-hosted を使用してください。
Autohosted (自動ホスト型)
Autohosted で構築されたアプリケーション (SharePoint Add-ins) では、デモでお見せした通り、利用者が Add-ins を追加 (インストール) すると、そのタイミングで Web アプリケーションが Azure にホストされます。(アプリケーションは、Azure Web Sites としてホストされます。Office 365 では、*.o365apps.net のドメインに展開されます。) このように、SharePoint とは異なる独自のホスティング環境 (Azure, AWS, On-Premise 上のサーバー, など) に配置される Web アプリケーションを Remote App と呼び、Full Page の Add-ins や、後述する App Part、Remote Event Receiver などの Add-ins で使用されます。
補足 : ただし、Autohosted の Add-ins のデバッグ実行をおこなうと、Web アプリケーションは localhost (IIS Express 上) で動作します。
Remote App の場合、SharePoint とは独立した環境のため、サーバー コードの実行など、一般の Web アプリケーションと同様のスタイルで (制約なく) 開発をおこなうことができます。また、認証をおこなう際には、Azure Active Directrory などクレームベースの認証基盤を活用することで、SharePoint サイトとの Web SSO の構成も容易に実装できます。この Hosting 方法では、例えば、サイト 1 とサイト 2 で、同じアプリケーションの追加をおこなった場合、Web ページやサーバー サイド ロジックも、異なる Azure Web Sites に展開されます。即ち、Multi-tenant (マルチテナント) にも自動的に対応できています。(SharePoint 上から Add-ins を削除すると、この Web Site も削除されます。)
補足 : セッションで紹介した通り、Autohosted では、Azure SQL Database のテーブルも同時に追加可能です。DACPAC を作成し、SharePoint Add-ins プロジェクトのプロパティの [SQL Package] (下図) に この DACPAC を設定します。(DACPAC は、Visual Studio の SQL Server Database Project で作成できます。)
また、Web プロジェクトでは、この配置されたデータベースを参照する専用の Connection String (SqlAzureConnectionString) も使用できます。
ここでは、構築手順の詳細は省略します。
Provider-hosted (プロバイダー向けのホスト型)
Provider-hosted は、Web アプリケーション側をあらかじめ開発者がホストしておき、定義情報に この Web アプリケーションの URL (参照) を記述します (この定義情報を SharePoint に Deploy します)。このように SharePoint とは異なる独自のホスティング環境 (例えば、Azure, AWS, On-Premise 上のサーバー, など) に配置される Web アプリケーションを Remote App と呼び、Full Page (Web ページそのもの) や、後述する App Part、Remote Event Receiver など、それぞれ独自の形態で配置されます。(上述の Autohosted と Provider-hosted をあわせて、Cloud-hosted と呼びます。)
SharePoint に配置される定義情報は .app の拡張子を持った zip ファイルとして作成されますが、この .app パッケージには、Web アプリケーションそのものは含まれていません。(URL のみが設定されています。)
Remote App は、このように SharePoint とは独立した環境のため、サーバー コードの実行など、一般の Web アプリケーションと同様のスタイルで (制約なく) 開発をおこなうことができます。また、認証をおこなう際には、Azure Active Directory の Access Control Service (ACS) を使った OAuth 認証をおこない、SharePoint サイトと 連携や Web SSO の構成も容易に実装できます。
補足 : Office 365 API で使用されている Azure AD の OAuth ではなく、Azure AD の ACS を使った OAuth になりますので注意してください。(使用する token はお互いに互換はありません。)
この Provider-hosted では、Multi-tenant の Add-ins として配布する場合、Remote App 側の Tenant 管理をアプリケーション側で制御したり、チューニングしたりする必要があるので注意してください。
また、後述しますが、この Hosting 方法は、Office 365 (SharePoint Online) だけではなく、On-Premise (SharePoint Server) でも使用できます。
SharePoint-hosted (SharePoint ホスト型)
この Hosting 方法では、サーバー上に配置されるコンポーネント (例えば、ホストする HTML や JavaScript、イメージファイルなど) は、すべて利用者の SharePoint 環境 (Office 365 の場合は、利用者の tenant) に配置されます。
Add-ins の追加と同時に、App Web と呼ばれる Add-ins 独自の SharePoint サイトが作成され、Artifacts (Page など) は、すべて、この App web のサイトに配置されます。(例えば、contoso-ba39d711d8040c.sharepoint.com など、一意の Id を含む独自のドメインが割り当てられ、App Web が作成されます。) これに対し、アプリケーションのインストール元となった SharePoint サイト (contoso.sharepoint.com) のほうは、Host Web と呼びます。
コンセプトは従来の (SharePoint 2010 の) サンドボックス ソリューションと似ていますが、上述の通り、サンドボックス ソリューションとはまったく異なります。
重要な点として、この SharePoint-hosted (App Web) で動作する artifacts で、サーバー側のコードは実行できません。このため、後述するように、宣言型のマークアップか、JavaScript などクライアント側のコードのみを使用してアプリケーションを構築します。(artifacts は、.wsp として配置されます。)
なお、前述の Autohosted、Provider-hosted の Add-ins でも、挿入する artifacts によっては App Web を併用できます。例えば、Page は Provider-hosted を使って Remote App (Azure) に展開し、カスタムのリスト定義を App Web 上で動かして連携できます。
このため、Sharepoint-hosted のアプリケーションは、Cloud-hosted (Remote App) を使用しないアプリケーションと考えておいたほうがすっきりするでしょう。
配布先
SharePoint Add-ins の配布をおこなう場所として、以下の 2 つが使用できます。
- SharePoint Store への配置
: ISV が構築したアプリケーション製品を配布する場合には、この配布方法が向いています。開発者 (アプリケーションの提供元) は、Windows 8 store app などと同様、専用の Seller Dashboard に提出 (Submit) をおこない、審査の結果、承認された Add-ins が一般の利用者から追加可能になります。
利用者が Add-ins を追加する場合は、SharePoint の左ナビゲーションから [Site Contents] をクリックして、表示される画面で [add an app] をクリックして、ナビゲーションの [SharePoint Store] をクリックすることで、 SharePoint Store 上の Add-ins の一覧を表示して、必要な Add-ins を追加できます。(Rating の高い Add-ins が、上に表示されます。)
この方法では、Package 作成で必要になる Client id, Client Secret は Seller Dashboard から取得します。(SharePoint Online を使用している全テナントでアプリが使えるようになります。) - App Catalog への配置
: もちろん、企業 (Enterprise) 向けの配布も可能です。
Office 365 のテナントや SharePoint Server (On-Premise) のファームを立てて、全体管理 (Central Administration) の画面から App catalog というサイト コレクションを作成します。この App catalog に Add-ins (Office Add-ins、SharePoint Add-ins) を配置することで、組織 (自社) 内だけにアプリケーションを配布することができます。(Office クライアント側なども、この App catalog を参照するように設定しておきます。なお、運用管理者が設定を自動配布することも可能です。)
この方法では、Package 作成で必要になる Client id, Client Secret は {サイトの URL}/_layouts/15/appregnew.aspx から取得します。(そのテナントでのみアプリが使えるようになります。)
なお、開発・Debug 時は、Visual Studio で F5 キー (Debug 実行) を押すことで、Visual Studio により、作成したアプリが localhost で実行され、デバッグ対象の SharePoint サイト上にアプリが登録されます。(あらかじめ、デバッグ用に、SharePoint 上に Developer Site (開発者向けサイト) を作成しておいてください。)
Remote App を Azure など現実の環境に配置をおこなってデバッグしたい場合には、開発用に Developer Site (開発者向けサイト) を作成し、アプリをクラウド上 (Azure など) に配置して、サイトの [Apps in Testing] (テスト中のアプリ) ライブラリーに .app ファイルの追加をおこないます。(この際、Remote Debug を使用すると良いでしょう。) なお、この方法でアップロードされたファイル (.app パッケージ) は、App Packages ライブラリー (https://<site url>/Lists/AppPackages) に保存されます。
Developer Site (開発者向けサイト) のサイト テンプレートでは、Sideloading が有効になっているため、こうした配置が既定で可能になっています。
アプリケーションの形態 (Application Type)
SharePoint Add-ins では、下記の 3 つタイプのアプリケーションが作成できます。
- Full Page
Web ページ (HTML, ASP.NET など) のアプリケーションです。アプリケーション実行時はページ全体が遷移しますが、JavaScript やサーバー サイドのコードを使って SharePoint と連携させることで、SharePoint 上の 1 機能のように実装できます。 - Parts
いわゆる、従来の Web パーツ (WebPart) のような Part も、SharePoint Add-ins で扱えます。SharePoint 2013 で新たに導入された ClientWebPart クラスを使うことで、リモートにホストされたページを Part として利用者に提供できます。(内部では、iframe が使用されています。従来通り、EditorPart (Tool Part) のような独自のプロパティも使用可能です。)
なお、このような Part (部品) を app part と呼び、挿入時も従来の Web Part とは区別されています。(下図)
- Extensions
SharePoint のカスタム リスト定義、リボン カスタマイズなど、既存の SharePoint の機能 (UI など) を拡張するタイプのアプリケーションも構築できます。
開発者は、Visual Studio で SharePoint Add-ins のプロジェクトを作成して、作成された Add-ins のプロジェクトを右クリックして [Add] – [New Item] を選択することで、これらのさまざまなコンポーネントを挿入できます。(下図)
なお、こうして挿入したコンポーネントは、.app パッケージ (zip ファイル) 内に .wsp としてパッケージ化されます。
SharePoint Add-ins ではリモート実行のモデルとなっている点に注意してください。(前述の通り、サーバー側で動くプログラムは、必ず、Remote App、App web などの別ドメインで動作させる必要があります。)
このため、Client Web Part、Remote Event Receiver など、SharePoint 2013 からの新しい artifacts も多く存在します。また、Workflow も、SharePoint 2013 に含まれるワークフロー エンジン (Workflow Manager 1.0) を使って、今回から Remote 呼び出しが可能になっています。(現在、この実行エンジンの Beta 版も単体で提供されています。てすとぶろぐ さんが素早く紹介してくれていますので、是非参考にしてみてください。)
なお、Artifacts としては、以下が使用可能です。
- カスタム Feature (Web スコープのみ)
- カスタム アクション
- イベント レシーバー (Remote event receiver)
- .aspx などのマークアップ ページ (サンドボックス ソリューションの頃のように、app part などを入れておくことも可能)、カスタムの css ファイル、カスタムの JavaScript ファイル などのモジュール
- カスタムのリスト定義 / リスト インスタンス / リスト フォームなど
- カスタム Content-Types
- カスタム Field
- Business Connectivity Services (BCS) モデル (Web スコープのみ)、モデルを使用した External Content-Types、外部リスト
- ワークフロー
- Property bags
- Web テンプレート
逆に、従来 (SharePoint 2010) のファーム ソリューションで使用できていた、サイト定義、カスタム テーマ、ユーザー コントロール (及び、Delegate コントロール) などは使用できないので注意してください。
補足 (2015/11 追記) : サイト定義については、同様の処理を PnP (Patterns and Practices) Provisioning Engineのライブラリーで実装できます。PnP Provisioning Engine を使用すると、既存のサイトの設定 (マスター、テーマ、カスタムのリストやコンテンツ タイプ など) を元に (その設定情報を抽出して)、同じ構成で新しいサイトを作成します。(SharePoint Add-ins を使用しています。)
SharePoint へのアクセス
Add-ins では SharePoint (Host web) との連携が必要になると思いますが、上記のアーキテクチャからご想像いただける通り、SharePoint へのアクセス方法は、Cloud hosted (Autohosted、Provider-hosted) と SharePoint-hosted の場合で大きく異なります。(認証方法などの考え方が大きくことなってきます。)
SharePoint-hosted の場合
まず、SharePoint-hosted のアプリケーションの場合 (Module の Page から SharePoint に接続する場合など) について解説します。
上述の通り、SharePoint-hosted ではサーバー コードの実行はできないため、SharePoint の JavaScript OM (JSOM)、または REST API を使用して SharePoint にアクセスします。
補足 : CSOM や JSOM のエッセンスについては、「リモートからの SharePoint 接続 - オブジェクト モデル (Client Object Model) の使用」 を参照してください。SharePoint 2013 では、後述するように、この Object Model がさらに拡張されています。
ここで、一点、注意すべき点があります。
JSOM (JavaScript OM) から接続する場合、普通に接続すると、取得される Web は App web です。例えば、Web の title を取得するコードの場合、普通に書くと、App web のタイトルが返ってきます。
Host Web に接続するには クロス ドメイン接続 が必要ですが、SharePoint 2013 の JSOM では、プログラマーがクロス ドメイン接続を意識せずに、App Web から Host Web のデータにアクセスできるようになっています。(ライブラリーがクロス ドメインと認証の課題を処理してくれます。)
例えば、Host Web にアクセスするには、Permission の付与を適切におこなって、下記コードの通り、SP.AppContextSite を使用した独自の context を使います。(Permission については後述します。下記のコードの場合、web の Read 権限を付与する必要があります。)
var hostweburl = getParameterByName('SPHostUrl');context = new SP.ClientContext.get_current();var appctx = new SP.AppContextSite(context, hostweburl);web = appctx.get_web();function getParameterByName(name) { name = name.replace(/[[]/, "\[").replace(/[]]/, "\]"); var regexS = "[\?&]" + name + "=([^&#]*)"; var regex = new RegExp(regexS); var results = regex.exec(window.location.search); if (results == null)return ""; elsereturn decodeURIComponent(results[1].replace(/+/g, " "));}また、REST を使用して Host web と連携する場合も、cross-domain 接続をおこなう必要はありません。例えば、Host web の Web の情報 (名前など) を取得する場合は、App Web から下記の URI でアクセスできます。
https://{app web url}/_api/SP.AppContextSite(@target)/web?@target='{host web url}'補足 : SharePoint 2013 では、CSOM (JSOM 含む) と、その中で使用されている client.svc が大きく機能拡張されています。SharePoint 2013 用の API 追加 (例えば、Social API の追加など) けでなく、今回から client.svc は REST 対応になっており、上記の URL (/_api) で接続できるようになっており、CRUD 以外のほとんどの処理が、この REST エンドポイントを使って可能になっています。(CSOM 自体も、内部で、この REST API を呼び出しています。)
もちろん、以前の REST (listdata.svc) も、そのまま使用できます。
Cloud-hosted の場合
Cloud hosted (Autohosted、Provider-hosted) の場合には、サーバー側のコードが記述できるため、サーバー側から接続する方法と、クライアント側から接続する方法の 2 通りがあります。
まず、前者ですが、サーバー側から .NET の CSOM (Client Side Object Model) や REST API を呼び出すことで、SharePoint にアクセスできます。
この方法では、プログラマーによる認証処理が必要です。Office 365 では、この認証として、OAuth 2 を使用します。
2012/10/05 追記 : このサーバー側の認証フローの詳細は「.NET CSOM を使ったプログラミングと認証 (Authentication)」に掲載しましたので参照してください。
また、Cloud-hosted の場合には、上述のサーバー側からのアクセス方法以外に、クライアント側 (ブラウザー上) の JavaScript から SharePoint にアクセスすることもできます。この場合、クロス ドメインの問題 を解決する必要があります。
実は、SharePoint 2013 では、こうした場合に使用可能な専用のライブラリー (Cross-domain libray) が提供されていて、これを使用して、認証の問題とクロス ドメインの問題を同時に解決できます。
2012/10/05 追記 : Cross-domain library については、「SharePoint の Cross-domain library」に掲載しました。
Permission (アクセス許可) の考え方
SharePoint Add-ins における Permission では、Delegation の考え方を採用しています。
まず、Add-ins の開発者は、例えば、「サイト コレクションのデータの読み込み」、「サイトへの書き込み」など、そのアプリケーションで必要となる Permission を要求します。下図の通り、Add-ins プロジェクトのマニフェスト (XML の定義情報) に、Permission 要求の設定をおこないます。
利用者がこの Add-ins を追加する際、Add-ins は上記の権限を利用者に要求します。具体的には、要求している Permission の内容が記載された確認画面が表示されます。
利用者が この Add-ins を信頼 (Trust) すると、利用者が持っている権限を Add-ins に委譲します。例えば、利用者が「サイト コレクションのデータの読み込み」の権限を持っている場合、この利用者が持つ権限が Add-ins に付与され、以降、この Add-ins は、この付与された権限を使って動作します。
なお、もし利用者が、そもそも Add-ins が要求している権限を持っていなかった場合には、下図の通り、エラーが表示されます。
この Permission のモデルは、一見、危険なように思われるかもしれません。例えば、サイトの投稿権限を持っているユーザーが、不用意に Add-ins を信頼 (Trust) してしまうと、閲覧権限しか持たない利用者に投稿の手段を与えてしまうことになりかねません。しかし、そもそも Add-ins を追加できるユーザーはサイト管理者の権限が必要であるため、ユーザーに権限付与が可能なサイト管理者の判断が必ず必要です。(もちろん、サイト管理者は、不用意に、信頼できない Add-ins を追加しないようにしてください。)
補足 : Full trust (Full Control) の Add-in は Office Store を使用できないので注意してください。ただし、Full trust の Add-in と連携して動作する Add-in は Office Store からインストールできます。(利用組織では、Full trust の Add-in を別途 Provider から入手して manual install をおこなった後で、この Add-in を使用できます。)
開発者の方は、是非、おもしろい Add-ins の作成と Submit をしてみてください。
関連ナンバー
- SharePoint 2013 開発 (SharePoint Add-ins)
※ 変更履歴 :
2014/06/01 Autohosted の廃止に伴って記述を削除
2015/05/05 App for SharePoint (SharePoint 用アプリ) を SharePoint Add-ins (SharePoint アドイン) に名称変更
Categories: Uncategorized
tsmatz
24 replies»