Office アドイン活用【基本② マニフェストファイル】
連載2回目です。
週2回ほどで継続していきたいですね...！！
今回は「基本②」ということで、
Office アドインの本体とも言える、マニフェストファイルの内容について解説していきたいと思います！
【注意】
このブログに記載した内容は、一開発者としての見解を述べたものになっており、
ジョルダン株式会社の公式見解ではありません。
また、当ブログでは、ジョルダン株式会社開発の「乗換案内Biz for Office」を基として解説を行います。
そもそもマニフェストファイルとはなんぞや？という話ですが、簡単にまとめると、
・Officeアドインの設定が書き込まれたXMLファイル
・1つのOfficeアドインごとに1つのマニフェストファイルが対応し、ExcelなどOfficeアプリケーションからの起動命令で、マニフェストファイルの読込みが行われる
・Excel&Wordと、Outlookでは、マニフェストファイルの記法が一部異なる
ということになります。
MS公式ページでは、以下をご参照ください。
Office 用アプリの XML マニフェスト
実際のマニフェストファイルを記載してみます。
■Excel・Word・PowerPoint・Project編
<?xml version="1.0" encoding="utf-8"?> <OfficeApp xsi:type="TaskPaneApp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/office/appforoffice/1.0"> <Id>abcdefgh-ijkl-mnop-qrst-uvwxyz123456</Id>※1 <Version>1.0.0.0</Version> <ProviderName>ここに会社名など</ProviderName> <DefaultLocale>ja-JP</DefaultLocale> <DisplayName DefaultValue="ここにアプリの名前" /> <Description DefaultValue="ここにアプリの説明文" /> <IconUrl DefaultValue="https://iconimage.url/images/icon.png" /> <SupportUrl DefaultValue="https://support.url/index.html" /> <AppDomains> <AppDomain>https://login.microsoftonline.com</AppDomain>※2 <AppDomain>https://login.windows.net/</AppDomain> <AppDomain>https://login.live.com/</AppDomain> </AppDomains> <Capabilities> <Capability Name="Workbook" />※3 </Capabilities> <DefaultSettings> <SourceLocation DefaultValue="https://application-url.xyz/" /> </DefaultSettings> <Permissions>ReadWriteDocument</Permissions> </OfficeApp>
一部の内容について、順に解説を行っていきます。
※1 Guid
アプリケーションの固有IDになります。
このIDが同じである場合、同じアプリケーションと判定されます。
よくやってしまうのですが、開発・検証・本番環境用のマニフェストファイルをコピペで作る場合、このIDの修正を忘れてしまうと、
"同じアプリケーション"として判定されてしまうことがあるので、気をつけましょう。
Guidは以下のサイトで作成できます。
Generate GUIDs online
GUIDを作成するVBScript | 初心者備忘録
※2 AppDomain
DefaultSettings > SourceLocationに記載のURL以外で、アプリ内で遷移する可能性のあるドメイン名を、ここで列挙していきます。
例えば、アプリ内でGoogleにアクセスすることがある場合、以下のような記述を追加します。
<AppDomain>https://www.google.co.jp/</AppDomain>
この記述がない場合どうなるか？ですが、Excel2013を例として解説すると、
Googleへのリンクをクリックすると、
Internet Explorer セキュリティという、謎のメッセージが立ち上がります。
「許可する」を押下した場合でも、
"target=_blank"のような記述がないにも関わらず、IEが立ち上がってしまい、Googleへ遷移します。
上記のAppDomain記述を追記することで、
アプリ内でGoogleに遷移することができます。
アプリで遷移する可能性のあるサイトのURLは、すべてこのAppDomainに記載しておいてください。
※ただし、この後Googleで検索を行い、別サイトに遷移しようとしても、結局セキュリティ警告が出てしまいます。
このことから、Officeアドインは不特定多数のサイトにアクセスするアプリには不適ということがわかります。
※3 Capability
Officeアプリケーションの種類になります。
<Capability Name="Workbook" />※Excel <Capability Name="Presentation" />※PowerPoint <Capability Name="Project" />※Project <Capability Name="Document" />※Word
■Outlook編
前述の通り、Outlookとそれ以外のマニフェストファイルの記法は少々異なります。
<?xml version="1.0" encoding="UTF-8"?> <!--Created:cb85b80c-f585-40ff-8bfc-12ff4d0e34a9--> <OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp"> <Id>abcdefgh-ijkl-mnop-qrst-uvwxyz123456</Id> <Version>1.0.0.0</Version> <ProviderName>ここに会社名など</ProviderName> <DefaultLocale>ja-JP</DefaultLocale> <DisplayName DefaultValue="ここにアプリの名前" /> <Description DefaultValue="ここにアプリの説明文"/> <IconUrl DefaultValue="https://iconimage.url/images/icon.png" /> <SupportUrl DefaultValue="https://support.url/index.html" /> <AppDomains> <AppDomain>https://login.microsoftonline.com</AppDomain> <AppDomain>https://login.windows.net/</AppDomain> <AppDomain>https://login.live.com/</AppDomain> </AppDomains> <Hosts> <Host Name="Mailbox" /> </Hosts> <Requirements> <Sets> <Set Name="MailBox" MinVersion="1.1" /> </Sets> </Requirements> <FormSettings>※1 <Form xsi:type="ItemRead"> <DesktopSettings> <SourceLocation DefaultValue="~remoteAppUrl/AppRead/Home/Home.html"/> <RequestedHeight>250</RequestedHeight> </DesktopSettings> </Form> <Form xsi:type="ItemEdit"> <DesktopSettings> <SourceLocation DefaultValue="~remoteAppUrl/AppCompose/Home/Home.html"/> </DesktopSettings> </Form> </FormSettings> <Permissions>ReadWriteItem</Permissions> <Rule xsi:type="RuleCollection" Mode="Or"> <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" />※2 <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit" /> <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" /> <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" /> </Rule> <DisableEntityHighlighting>false</DisableEntityHighlighting> </OfficeApp>
※1 FormSettings
※2 Rule
この2つは連動している部分も多いので、一緒に解説します。
まず"Rule"ですが、Outlookのどの機能でアプリを起動するか、その設定になります。
ItemTypeが"Message"だとメール、"Appointment"だと予定表になります。
そしてFormTypeですが、"Edit"だと新規作成時（作成モード）、"Read"だと読み取り時（閲覧モード）になります。
例えばItemType="Appointment" FormType="Edit"のルールを登録しておくと、
予定表の新規登録画面で、アプリを呼び出す事ができます。
一方、ItemType="Appointment" FormType="Read"のルールを登録しておくと、
すでに登録している予定表から、アプリを呼び出す事ができます。
"Edit"と"Read"の2点ですが、似て非なるものと思ってください。
例えばアプリを起動した後のレイアウトですが、
作成モードの場合はこのように縦長ですが、
閲覧モードの場合は横長です。
他にも例として、予定表の件名に関するoffice.jsのプロパティ"Office.context.mailbox.item.subject"ですが、
作成モードでは、件名の取得または設定できるgetAsync メソッドと setAsync メソッドを備えた Subject オブジェクトを返却しますが、
閲覧モードでは、予定の件名の文字列を返却します。
型からして違うわけです。
（参考：Appointment.subject プロパティ (JavaScript API for Office)）
このように見た目の面でも機能面でも、2つのモードではまったく別物です。
モードによって、アプリの呼び出すURLを変更することができます。
FormSettingsのFormで、SourceLocationを変更して下さい。
実際「乗換案内Biz for Office」の場合、予定表に登録することを主としているので、
予定表の作成モードのみ対応しております。
このような場合、マニフェストファイルを以下のように修正してください。
<FormSettings> <Form xsi:type="ItemEdit"> <DesktopSettings> <SourceLocation DefaultValue="~remoteAppUrl/AppCompose/Home/Home.html"/> </DesktopSettings> </Form> </FormSettings> <Permissions>ReadWriteItem</Permissions> <Rule xsi:type="RuleCollection" Mode="Or"> <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit" /> </Rule> <DisableEntityHighlighting>false</DisableEntityHighlighting> </OfficeApp>
こうすることで、
予定表の閲覧時、アプリが表示されなくなりました。
何をしたいのかに応じて、このあたりの設定は変更しましょう。
以上、マニフェストファイルの解説を行いました。
特にOutlookの"作成モードと閲覧モード"については、その後のoffice.js実装時にも大きく影響を受ける部分ですので、
今のうちに確認しておきましょう。
基本的な部分については、以上で終了となります。
次回以降は、いよいよ本格的な開発内容の解説です！
次回は認証処理や、Exchangeなどを使用するために必要な、"AzureAD"についてお話する予定です。
気長にお待ちください！
