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 つのユニバーサル アクション。
- Google ドライブ
onItemsSelectedTrigger。 - Gmail の作成アクションとコンテキスト トリガー。
- ドキュメントの
linkPreviewTrigger。このトリガーについては、スマートチップを使用してリンクをプレビューするをご覧ください。 - ドキュメント、スプレッドシート、スライドのファイル固有のインターフェース。
- カレンダーの
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"
},
"linkPreviewTriggers": [
{
"runFunction": "onLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "example-path"
}
],
"labelText": "Link preview",
"localizedLabelText": {
"es": "Link preview localized in Spanish"
},
"logoUrl": "https://www.example.com/images/smart-chip-icon.png"
}
]
},
"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",
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"urlFetchWhitelist": [
"https://www.example.com/myendpoint/"
],
}
URL を許可リストに登録
許可リストを使用して、スクリプトまたはアドオンによるアクセスが事前に承認されている特定の URL を指定します。許可リストはユーザーデータの保護に役立ちます。許可リストを定義すると、スクリプト プロジェクトは許可リストに登録されていない URL にアクセスできません。
許可リストは、スクリプトまたはアドオンで次の操作を行うときに使用します。
- Apps Script
UrlFetchサービスを使用して、外部ロケーション（HTTPS エンドポイントなど）から情報を取得または取得します。取得する URL を許可リストに登録するには、マニフェスト ファイルにurlFetchWhitelistフィールドを含めます。 - ユーザー アクションに応じて URL を開くか表示します（Google URL の外部にある URL を開くまたは表示する Google Workspace アドオンの場合は必須）。開く URL を許可リストに登録するには、マニフェスト ファイルに
addOns.common.openLinkUrlPrefixesフィールドを含めます。
許可リストへのプレフィックスの追加
マニフェスト ファイルで許可リスト（addOns.common.openLinkUrlPrefixes フィールドまたは urlFetchWhitelist フィールドを含む）を指定する場合は、URL 接頭辞のリストを含める必要があります。マニフェストに追加する接頭辞は、次の要件を満たしている必要があります。
- 各プレフィックスは有効な URL である必要があります。
- 各接頭辞は、
http://ではなく、https://を使用する必要があります。 - 各プレフィックスには完全なドメインが必要です。
- 各接頭辞のパスは空にできません。たとえば、
https://www.google.com/は有効ですが、https://www.google.comは無効です。 - ワイルドカードを使用すると、URL サブドメインのプレフィックスを一致させることができます。
addOns.common.openLinkUrlPrefixesフィールドで 1 つの*ワイルドカードを使用してすべてのリンクを照合できますが、ユーザーのデータが危険にさらされ、アドオンのレビュー プロセスが長引く可能性があるため、この操作はおすすめしません。アドオン機能に必要な場合にのみ、ワイルドカードを使用します。
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（ワイルドカードは先頭接頭辞として使用する必要があります）