SharePoint アドインのアプリ マニフェスト構造およびパッケージについて調べる

  • [アーティクル]

SharePoint 用アドインのパッケージ構造

SharePoint アドイン パッケージは拡張子 ".app" を持つファイルで、Open Packaging Conventions (OPC) に準拠しています。 パッケージには、次のアイテムが含まれます。

  • アドイン マニフェスト: これは appmanifest.xml という名前の必須ファイルです。 このファイルは、アドインの重要なプロパティ (タイトルや実行するために必要なアクセス許可など) を SharePoint に通知します。 このファイルの詳細については、「SharePoint 用アドインのマニフェスト ファイル」を参照してください。

  • SharePoint ソリューション パッケージ: オプションとして、アドイン Web のコンポーネントを含む SharePoint ソリューション パッケージ (.wsp ファイル) をアドインに含めることができます。 これらのコンポーネントには、ページ、リスト インスタンス、ビュー、ドキュメント、Web の範囲のフィーチャー、その他の SharePoint コンポーネントを含めることができます。 (SharePoint アドインに含めることができる SharePoint コンポーネントの詳細については、「SharePoint アドインに含 めることができる SharePoint コンポーネントの種類」を参照してください)。.wsp ファイルには Office アドインも含まれている場合があります。.wsp ファイル内のコンポーネントは、アドイン Web にデプロイされます。 SharePoint ソリューション パッケージを含むアドイン パッケージの例については、「SharePoint のカスタムのリストおよびコンテンツ タイプを含む、プロバイダー向けのホスト型アドインを作成する」を参照してください。

  • カスタム アクションまたはアドイン パーツ付きのホスト Web フィーチャー: アドイン Web に展開される SharePoint コンポーネントに加え、SharePoint アドインは、1 つまたは複数のカスタム アクション (ショートカット メニュー アイテムやリボン拡張など) をホスト Web に展開することもできます。 パッケージの .wsp ファイルにはないものの、ホスト Web に配置されるコンポーネントを展開するフィーチャーをアドイン パッケージに含めることにより、これが実現されます。 この "ルーズな" フィーチャーは、ホスト Web フィーチャーと呼ばれます。

    アドイン パーツは、同じ方法でホスト Web にデプロイされます。 ホスト Web 機能は、標準の SharePoint feature.xml ファイルと 1 つ以上の関連付けられたelements.xml ファイルで構成されます。 たとえば、カスタム アクションのelements.xml ファイルには、カスタム アクションの CustomAction マークアップが含まれています。 アドイン パーツのマークアップを含めることもできます。 ホスト Web 機能には、これら 2 種類のコンポーネントのみを含めることができます。 これらのホスト Web 機能は、アドイン マニフェストでは項目化されません。 ただし、これらは OPC の意味では "パーツ" であり、アドイン マニフェストとこれらの各ファイルの間には明示的な OPC 関係があります。 ホスト Web 機能を含むアドイン パッケージの例については、「 SharePoint アドインを使用して展開するカスタム アクションを作成する」を参照してください。

    注:

    テナント管理者には、SharePoint アドインを複数の Web サイトにバッチ インストールするというオプションがあります。 この方法でインストールされているアドインは、テナント スコープを持っていることになります。 アドインがバッチ インストールではなく、各 Web サイトに別々にインストールされている場合は、Web スコープを持っています。 ホスト Web フィーチャーにリボン拡張やアドイン パーツが含まれている場合にアドインをバッチ インストールすると、リボン拡張やアドイン パーツは、ホスト Web に展開されません。そのため、テナント スコープのアドインと共にショートカット メニュー アイテムのみが展開されます。

    アドイン スコープをフィーチャー スコープと混同しないでください。 フィーチャー スコープは、フィーチャー内の要素の展開場所を決定します。 その候補には、ファーム、Web アプリケーション、サイト (つまり、サイト コレクション)、Web が挙げられます。 Web オプションのみが SharePoint アドイン内のフィーチャー (ホスト Web フィーチャーと、アドイン パッケージ内の .wsp 内部のフィーチャーの両方) に対して許可されます。

    アドイン スコープとは、アドインがインストールされる範囲です。 その候補には、Web (1 つまたは複数の Web サイトに対して、サイトごとにインストールされているアドインの場合) と、テナント (顧客のテナント内のすべてまたは一部の Web サイトにバッチ インストールされているアドインの場合) が挙げられます。

    テナント スコープと Web スコープの詳細については、「SharePoint アドインのテナントと展開スコープ」を参照してください。

  • ローカライズ リソース ファイル (.resx) : これらは、アドインのタイトルを含むアドイン マニフェストの各部と、アドイン パッケージ内のホスト Web フィーチャーの各部をローカライズするためのファイルです。 (.wsp ファイル、Azure Web サイト パッケージ、アドイン マニフェストなどの独自のパッケージに含まれるアドイン パッケージの個々のパーツには、それぞれ独自のローカライズ プロセスがあり、それらのプロセスは対象のアイテムが SharePoint アドインのパーツではない場合と全く同じように適用されます)。ホスト Web フィーチャー用の .resx ファイルがあるアドイン パッケージの例については、「SharePoint アドインをローカライズする」を参照してください。

  • Office アドイン マニフェスト: オプションであり、それぞれが Office アドインをパッケージ化する 1 つまたは複数の Office アドイン マニフェストになる場合があります。 このパーツは、一般の Marketplace にではなく SharePoint コーポレート アドイン カタログにアドインがアップロードされる場合のみ、アドイン パッケージに含めることができます。 詳細については、「SharePoint アドインを公開する」を参照してください。

SharePoint 用アドインのマニフェスト ファイル

すべての SharePoint アドインには、appmanifest.xml ファイルが含まれています。 appmanifest.xml は、アドインについて知る必要があるデータを SharePoint に通知し、アドインの最も重要なプロパティを定義します。 このマニフェストに指定されるアイテムの一部を次に示します。

  • アドインの内部名、製品 ID、およびバージョン。

  • 開始ページの URL。これは、アドインの起動時に開くページです。 これは、アドイン Web のページ、クラウドベースのページ、または ISV の Web サーバー上のページです。

    注:

    一部の環境では、StartPage 要素で指定可能なファイルの種類に制限がある場合があります。 詳細については、「StartPage 要素 (PropertiesDefinition complexType) (SharePoint アドイン マニフェスト)」を参照してください。 複数のクエリ パラメーターを StartPage 値で組み合わせて使用する場合は、& やセミコロンではなく、コード化されたアンパサンド & を使用する必要があります。

  • アドインのその他のプロパティ。 これには、アドインでサポートされるタイトルとロケール (両方とも必須)、インストール後、アップグレード後、アンインストール前の各イベントを処理するサービスの URL、およびアドイン Web の作成時に使用する Web テンプレートがあります。

  • アドインが必要とする、アドイン Web の外部の SharePoint リソースに対するアクセス許可要求。

  • 認証と承認を目的とするアドイン プリンシパルの ID。 アクセス許可を付与されるのはこのプリンシパルです。 これは、SharePoint ホスト型アドインでは必要ありません。

  • アドインをインストールするために、アドインで使用できるようにする前提条件のリスト (存在する場合)。 たとえば、特定の機能をインストールしてアクティブ化する必要がある場合や、特定のサービスのライセンスを取得してインストールする必要がある場合があります。

注:

アドイン マニフェスト ファイルはアドイン パッケージの唯一の必須アイテムですが、前述したリストのアイテムは、そのすべてがこのファイルの必須パーツというわけではありません。

アドイン マニフェスト マークアップの詳細については、「SharePoint アドインのマニフェスト向けのスキーマ リファレンス」を参照してください。このトピックは、必須の要素と属性に関する情報も含めて、そのノードの情報の代わりになるものではありません。 また、SharePoint アドイン マニフェストのスキーマは、Office アドイン マニフェストのスキーマとは異なります。 Office アドイン マニフェストのスキーマの詳細については、「Office アドインのマニフェスト向けのスキーマ リファレンス (v1.1)」を参照してください。

appmanifest.xml ファイルの例を次に示します。 この例でのアドインのスタート ページは、リモート サーバー上の ASP.NET ページであり、SharePoint サイト上のページではありません。 ページの URL には、リモート Web アプリケーションにホスト Web の URL を渡すクエリ文字列が含まれます。 文字列の {HostUrl} の部分は、アドイン起動時に解決されるトークンです。 このアドインは、ホスト Web 内のすべてのリストへの書き込みアクセス許可を要求します。 このアクセス許可を付与する必要があるアドイン プリンシパルは、リモート Web アプリケーションです。

アドイン マニフェストでは、SupportedLocales 要素または SupportedLanguages 要素を使用する必要があります。 SupportedLanguages は廃止されているため、SupportedLocales を使用します。 SupportedLanguages 要素はリリース後も引き続き機能しますが、使用しないようにしてください。 これらの要素の詳細については、「SupportedLocales 要素 (PropertiesDefinition complexType) (SharePoint アドイン マニフェスト)」および「SupportedLanguages 要素 (PropertiesDefinition complexType) (SharePoint アドイン マニフェスト)」を参照してください。

注:

AppPermissionRequest 要素の Scope 属性の値は URI のような構成になっていますが、実際はリテラル文字列です。 次の例の Scope 値には、プレースホルダーは存在しません。 アクセス許可の詳細については、「SharePoint でのアドインのアクセス許可」を参照してください。

<?xml version="1.0" encoding="utf-8" ?>
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     ProductID="{4a07f3bd-803d-45f2-a710-b9e944c3396e}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0"
     Name="MySampleApp"
>
  <Properties>
    <Title>My Sample App</Title>
    <StartPage>http://MyRemoteWebApplicationServer/default.aspx/?SPHostUrl={HostUrl}</StartPage>
    <SupportedLocales>
      <SupportedLocale CultureName="en-US" />
    </SupportedLocales>        
  </Properties>

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

  <AppPrincipal>
    <RemoteWebApplication ClientId="1ee82b34-7c1b-471b-b27e-ff272accd564" />
  </AppPrincipal>
</App>

アドイン マニフェスト内の URL トークン

SharePoint には、 アドインの StartPage 要素やその他の場所やアドインのコンポーネントで使用できるトークンがいくつか用意されており、アドインが実行されるまで認識されない情報を表すことができます。 これらのトークンは SharePoint インフラストラクチャによって解決されます。 URL の先頭で使用されるトークンや、URL の中でクエリ パラメーターの値などとして使用できるトークンがあります。 これらのトークンと、その他のいくつかのトークンは、SharePoint のさまざまな開発コンテキストでも使用できます。

すべてのトークンとそれらを使用できる場所の詳細については、「SharePoint アドインの URL 文字列とトークン」を参照してください。SharePoint の他のトークンと URL の概要については、「SharePoint 2013 の URL とトークン」を参照してください。

注:

これらのトークンは、AppPermissionRequest 要素の Scope 属性では使用されません。

関連項目