Google Workspace アドオンのマニフェスト

アドオンは、マニフェスト ファイルを使用して、アプリとその動作に関する特定の詳細を構成します。

このドキュメントでは、Google Workspace アドオンのマニフェストの構成について詳しく説明します。

Google Workspace アドオンのマニフェスト構造

Google Workspace アドオンでは、マニフェスト ファイルを使用して、アドオンの外観と動作のいくつかの側面を定義します。

Google Workspace アドオンのマニフェスト プロパティは、マニフェスト オブジェクト構造の addOns セクションに編成されています。

• Apps Script マニフェスト ファイルの詳細については、マニフェストの構造をご覧ください。

• HTTP エンドポイントでビルドされたアドオンのマニフェスト ファイルについては、projects.deployments リソースをご覧ください。

Google Chat のマニフェスト

デベロッパー プレビュー: Google Workspace デベロッパー プレビュー プログラムの一部として利用できます。このプログラムでは、特定の機能に早期アクセスできます。

Google Workspace アドオンが Google Chat を拡張する場合は、Google Cloud コンソールで Google Chat API を有効にして構成することで、Google Chat アプリを構成する必要があります。

一般的なマニフェスト構成設定（addons.common など）は Chat では無視されます。アドオン マニフェストを使用する代わりに、Chat API を使用して次の Chat 設定を構成します。

• Chat アプリの名前、ロゴ、説明。Chat UI にのみ表示されます。
• Chat アプリのトリガー。

Apps Script でアドオンを作成した場合は、マニフェストで次のオブジェクトを追加または更新する必要があります。

• addons.chat（必須）
• oauthScopes（Google Chat アプリが OAuth スコープを使用する場合必須）

アドオンの Chat 設定を構成する手順については、Google Chat アプリを構成するをご覧ください。

Google Workspace アドオン マニフェストの構成例

次のマニフェスト サンプルは、Google Workspace アドオンを定義するマニフェスト ファイルのセクションを示しています。このセクションには、次の要素が含まれます。

• マニフェストの addOns.common セクションでは、アドオンの名前、ロゴの URL、色など、ホストに依存しない一般的な設定を定義します。

• マニフェストでは、共通のホームページを定義するだけでなく、カレンダー、ドライブ、ドキュメント、スプレッドシート、スライド固有のホームページも定義します。Gmail ではデフォルトのホームページが使用されます。

• サンプル マニフェストの設定では、次のことが可能になります。

  • カレンダーの eventOpen トリガーと eventUpdated トリガー。

  • （Apps Script のみ）2 つのカレンダー会議ソリューション。

  • 2 つのユニバーサル アクション。

  • ドライブ onItemsSelectedTrigger。

  • Gmail の作成アクションとコンテキスト トリガー。

  • Docs の linkPreviewTriggers オブジェクト。このトリガーについて詳しくは、スマートチップを使用してリンクをプレビューするをご覧ください。

  • Docs の createActionTriggers オブジェクト。このトリガーの詳細については、@ メニューからサードパーティのリソースを作成するをご覧ください。

  • ドキュメント、スプレッドシート、スライド用のファイル固有のインターフェース。

  • （HTTP のみ）認証ヘッダーを送信し、詳細な同意をサポートするための 2 つの HttpOptions 。

• oauthScopes フィールドには、プロジェクトの認可スコープを設定します（通常はアドオンに必要）。

• （Apps Script のみ）urlFetchWhitelist フィールドは、取得されたエンドポイントが指定された HTTPS URL 接頭辞のリストと一致することを確認するフィールドです。詳細については、URL の許可リストをご覧ください。

マニフェスト サンプルのリンクは、 Apps Script と HTTP Google Workspace アドオンのマニフェスト リファレンス ドキュメントの対応するフィールドの説明にリダイレクトします。

注: マニフェストには他のコンポーネントも含まれます。addOns フィールドの下のフィールドは、Google Workspace アドオンに直接関連しています。この例は完全なマニフェスト ファイルの一部であり、完全な機能のマニフェストではありません。

Apps Script

{
  "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://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"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "exampleFunction",
          "logoUrl": "https://www.example.com/images/case.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/"
  ]
}

HTTP

{
  "addOns": {
    "calendar": {
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=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://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "actions": [
          {
            "label": "Add images to email",
            "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=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"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    }
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "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"
  ]
}

URL を許可リストに登録する

許可リストを使用すると、スクリプトまたはアドオンによるアクセスが事前承認されている特定の URL を指定できます。許可リストはユーザーデータの保護に役立ちます。許可リストを定義すると、許可リストに追加されていない URL にスクリプト プロジェクトがアクセスできなくなります。

このフィールドは、テスト用デプロイをインストールする場合は省略可能ですが、バージョニングされたデプロイを作成する場合は必須です。

許可リストは、スクリプトまたはアドオンが次のアクションを実行する場合に使用します。

• Apps Script の UrlFetch サービスを使用して、外部ロケーション（HTTPS エンドポイントなど）から情報を取得またはフェッチします。取得する URL を許可リストに登録するには、マニフェスト ファイルに urlFetchWhitelist フィールドを含めます。
• ユーザー操作に応じて URL を開くか表示します（Google の外部 URL を開くか表示する Google Workspace アドオンに必須）。開く URL を許可リストに登録するには、マニフェスト ファイルに addOns.common.openLinkUrlPrefixes フィールドを追加します。

注: urlFetchWhitelist で使用されている「ホワイトリスト」という用語はサポートが終了しており、許可リストに置き換えられています。詳細については、インクルーシブなドキュメントの作成をご覧ください。

許可リストに接頭辞を追加する

マニフェスト ファイルで許可リストを指定する（addOns.common.openLinkUrlPrefixes フィールドまたは urlFetchWhitelist フィールドを含める）場合は、URL 接頭辞のリストを指定する必要があります。マニフェストに追加する接頭辞は、次の要件を満たしている必要があります。

• 各プレフィックスは有効な URL である必要があります。
• 各接頭辞には http:// ではなく https:// を使用する必要があります。
• 各接頭辞には完全なドメインが必要です。
• 各接頭辞には空でないパスが必要です。たとえば、https://www.google.com/ は有効ですが、https://www.google.com は無効です。
• ワイルドカードを使用して、URL サブドメインの接頭辞と一致させることができます。
• addOns.common.openLinkUrlPrefixes フィールドで 1 つの * ワイルドカードを使用してすべてのリンクを照合できますが、ユーザーのデータがリスクにさらされる可能性があるため、アドオンの審査プロセスが長引く可能性があるため、推奨されません。ワイルドカードは、アドオン機能で必要とされる場合にのみ使用してください。

URL が許可リストの接頭辞と一致するかどうかを判断する際は、次のルールが適用されます。

• パスのマッチングでは大文字と小文字が区別されます。
• 接頭辞が URL と一致する場合、一致と見なされます。
• URL が同じか、接頭辞の子である場合は、一致しています。

たとえば、接頭辞 https://example.com/foo は次の URL と一致します。

• https://example.com/foo
• https://example.com/foo/
• https://example.com/foo/bar
• https://example.com/foo?bar
• https://example.com/foo#bar

ワイルドカードの使用

1 つのワイルドカード文字（*）を使用して、urlFetchWhitelist フィールドと addOns.common.openLinkUrlPrefixes フィールドの両方でサブドメインを照合できます。複数のワイルドカードを使用して複数のサブドメインを照合することはできません。また、ワイルドカードは URL の先頭の接頭辞を表す必要があります。

たとえば、接頭辞 https://*.example.com/foo は次の URL と一致します。

• https://subdomain.example.com/foo
• https://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 （ワイルドカードは先頭の接頭辞として使用する必要があります）