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

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

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

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

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

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

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

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

Google Chat のマニフェスト

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

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

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

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

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

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

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

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

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

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

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

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

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

    • ドライブ onItemsSelectedTrigger。

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

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

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

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

    • Meet の sidePanelUri オプションと addOnOrigins オプション。

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

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

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

マニフェスト サンプルのリンクは、 Apps Script と HTTP 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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/logoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
    },
  },
  "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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
      ]
    },
    "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 フィールドを含めます。

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

マニフェスト ファイルで許可リストを指定する場合（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

ワイルドカードの使用

単一のワイルドカード文字（*）を使用して、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 （ワイルドカードは先頭の接頭辞として使用する必要があります）