Apps Script プロジェクトでは、マニフェスト ファイルを使用して、スクリプトとそのオペレーションに関する特定の詳細を構成します。マニフェストを表示および編集する方法については、マニフェストをご覧ください。
このドキュメントでは、Google Workspace アドオンのマニフェストの構成について詳しく説明します。
Google Workspace アドオンのマニフェスト構造
Google Workspace アドオンは、Apps Script プロジェクトのマニフェスト ファイルを使用して、アドオンの外観と動作のさまざまな側面を定義します。Google Workspace アドオンのマニフェスト プロパティは、マニフェスト オブジェクト構造の addOns セクションにまとめられています。
Google Workspace アドオンのマニフェスト構成の例
以下のマニフェスト サンプルは、Google Workspace アドオンを定義するマニフェスト ファイルのセクションを示しています。以下の内容が含まれています。
- マニフェストの
addOns.commonセクションには、アドオンの名前、ロゴ URL、色など、ホストに依存しない一般的な設定を定義します。 - このマニフェストでは共通のホームページを定義しますが、カレンダー、ドライブ、ドキュメント、スプレッドシート、スライド固有のホームページも定義されます。Gmail ではデフォルトのホームページが使用されます。
- サンプルのマニフェスト設定では、次の設定が可能です。
- カレンダーの
eventOpenトリガーとeventUpdatedトリガー、2 つのカレンダー 会議ソリューション。 - 2 つの普遍的なアクション。
- ドライブ
onItemsSelectedTrigger。 - Gmail の作成アクションとコンテキスト トリガー
- ドキュメント、スプレッドシート、スライドのファイル固有のインターフェース。
- カレンダーの
oauthScopesフィールドは、プロジェクトの認可スコープを設定します（通常はアドオンに必要）。urlFetchWhitelistフィールドでは、HTTPS URL 接頭辞を設定します。これにより、取得したすべてのエンドポイントが接頭辞と一致するようになります（通常、アドオンに必要です）。詳細については、許可リストの URL をご覧ください。
サンプル内のリンクをクリックすると、マニフェストのリファレンス ドキュメントに、このフィールドの説明が表示されます。
// Sample configuration of the addOns section in a manifest file:
{
"addOns": {
"calendar": {
"createSettingsUrlFunction": "getConferenceSettingsPageUrl",
"conferenceSolution": [{
"id": "my-video-conf",
"logoUrl": "https://lh3.googleusercontent.com/...",
"name": "My Video Conference",
"onCreateFunction": "onCreateMyVideoConference"
}, {
"id": "my-streamed-conf",
"logoUrl": "https://lh3.googleusercontent.com/...",
"name": "My Streamed Conference",
"onCreateFunction": "onCreateMyStreamedConference"
}],
"currentEventAccess": "READ_WRITE",
"eventOpenTrigger": {
"runFunction": "onCalendarEventOpen"
},
"eventUpdateTrigger": {
"runFunction": "onCalendarEventUpdate"
},
"eventAttachmentTrigger": {
"label": "My Event Attachment",
"runFunction": "onCalendarEventAddAttachment"
},
"homepageTrigger": {
"runFunction": "onCalendarHomePageOpen",
"enabled": true
}
},
"common": {
"homepageTrigger": {
"runFunction": "onDefaultHomePageOpen",
"enabled": true
},
"layoutProperties": {
"primaryColor": "#ff392b",
"secondaryColor": "#d68617"
},
"logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
"name": "Demo Google Workspace Add-on",
"openLinkUrlPrefixes": [
"https://mail.google.com/",
"https://script.google.com/a/google.com/d/",
"https://drive.google.com/a/google.com/file/d/",
"https://en.wikipedia.org/wiki/",
"https://www.example.com/"
],
"universalActions": [{
"label": "Open settings",
"runFunction": "getSettingsCard"
}, {
"label": "Open Help URL",
"openLink": "https://www.example.com/help"
}],
"useLocaleFromApp": true
},
"drive": {
"homepageTrigger": {
"runFunction": "onDriveHomePageOpen",
"enabled": true
},
"onItemsSelectedTrigger": {
"runFunction": "onDriveItemsSelected"
}
},
"gmail": {
"composeTrigger": {
"selectActions": [
{
"text": "Add images to email",
"runFunction": "getInsertImageComposeCards"
}
],
"draftAccess": "METADATA"
},
"contextualTriggers": [
{
"unconditional": {},
"onTriggerFunction": "onGmailMessageOpen"
}
]
},
"docs": {
"homepageTrigger": {
"runFunction": "onEditorsHomepage"
},
"onFileScopeGrantedTrigger": {
"runFunction": "onFileScopeGrantedEditors"
}
},
"sheets": {
"homepageTrigger": {
"runFunction": "onEditorsHomepage"
},
"onFileScopeGrantedTrigger": {
"runFunction": "onFileScopeGrantedEditors"
}
},
"slides": {
"homepageTrigger": {
"runFunction": "onEditorsHomepage"
},
"onFileScopeGrantedTrigger": {
"runFunction": "onFileScopeGrantedEditors"
}
},
"oauthScopes": [
"https://www.googleapis.com/auth/calendar.addons.execute",
"https://www.googleapis.com/auth/calendar.addons.current.event.read",
"https://www.googleapis.com/auth/calendar.addons.current.event.write",
"https://www.googleapis.com/auth/drive.addons.metadata.readonly",
"https://www.googleapis.com/auth/gmail.addons.current.action.compose",
"https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/script.external_request",
"https://www.googleapis.com/auth/script.locale",
"https://www.googleapis.com/auth/script.scriptapp",
"https://www.googleapis.com/auth/drive.file",
"https://www.googleapis.com/auth/documents.currentonly",
"https://www.googleapis.com/auth/spreadsheets.currentonly",
"https://www.googleapis.com/auth/presentations.currentonly"
],
"urlFetchWhitelist": [
"https://www.example.com/myendpoint/"
],
}
許可リストの URL
スクリプトやアドオンで、ユーザーの操作に応じて URL を開くこともあります。Apps Script UrlFetch サービスを使用してスクリプトやアドオンで外部から情報を取得する必要がある場合もあります。どちらの場合も、プロジェクト マニフェストで開いたり取得したりした URL を許可リストに登録する必要があります。
許可リストへの登録は、スクリプトまたはアドオンによってアクセスが事前に承認されている特定の URL を指定するプロセスです。この要件により、ユーザーデータを保護できます。許可リストを定義すると、スクリプト プロジェクトは、許可リストに登録されていない URL にアクセスできません。 Google Workspace アドオンでは、取得または開くために URL を許可リストに登録する必要があります。
URL を許可リストに登録するには、その URL または一致する接頭辞を urlFetchWhitelist マニフェスト フィールドに追加します。 Google Workspaceアドオン プロジェクトの場合、開く URL または一致する接頭辞を addOns.common.openLinkUrlPrefixes マニフェスト フィールドに追加して、開く URL を許可リストに登録できます。
マニフェストに追加するプレフィックスは、次の要件を満たしている必要があります。
- 各プレフィックスは有効な URL である必要があります。
- 各プレフィックスは
http://ではなくhttps://を使用する必要があります。 - 各プレフィックスには完全なドメインが必要です。
- 各接頭辞のパスは空白にできません。たとえば、
https://www.google.com/は有効ですが、https://www.google.comは無効です。 - ワイルドカードを使用して URL サブドメインの接頭辞を照合できます。
- 1 つの
*ワイルドカードをすべてのリンクの照合にaddOns.common.openLinkUrlPrefixesフィールドで使用できますが、ユーザーのデータを危険にさらすおそれがあり、アドオンの審査プロセスが長引く可能性があるため、この方法はおすすめしません。ワイルドカードは、アドオン機能で必要な場合にのみ使用します。
URL が許可リストのプレフィックスと一致するかどうかを判断する際には、次のルールが適用されます。
- パスマッチングでは、大文字と小文字が区別されます。
- 接頭辞が URL と同一の場合は一致となります。
- URL がプレフィックスの子と同じか、または子の URL であれば、一致します。
たとえば、接頭辞 https://example.com/foo は次の URL と一致します。
https://example.com/foohttps://example.com/foo/https://example.com/foo/barhttps://example.com/foo?barhttps://example.com/foo#bar
ワイルドカードの使用
1 つのワイルドカード文字（*）を使用して、urlFetchWhitelist フィールドと addOns.common.openLinkUrlPrefixes フィールドの両方のサブドメインに一致させることができます。複数のサブドメインの照合に複数のワイルドカードを使用することはできません。ワイルドカードは URL の先頭の接頭辞を表す必要があります。
たとえば、接頭辞 https://*.example.com/foo は次の URL と一致します。
https://subdomain.example.com/foohttps://any.number.of.subdomains.example.com/foo
接頭辞 https://*.example.com/foo は次の URL に一致しません。
https://subdomain.example.com/bar（接尾辞の不一致）https://example.com/foo（少なくとも 1 つのサブドメインが存在する必要があります）
一部の接頭辞ルールは、マニフェストを保存しようとしたときに適用されます。たとえば、マニフェスト内に以下の接頭辞が存在している場合、それらの接頭辞を保存しようとするとエラーが発生します。
https://*.*.example.com/foo（複数のワイルドカードは禁止されています）https://subdomain.*.example.com/foo（ワイルドカードは先頭の接頭辞として使用する必要があります）