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

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

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

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

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

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

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

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

Google Chat のマニフェスト

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

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

• Chat UI の Chat アプリの名前、ロゴ、説明。
• Chat アプリ のトリガー。

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

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

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

Google Workspace アドオンのマニフェスト構成のサンプル

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

• addOns.common は、アドオンの名前、ロゴ、色、その他の一般的な設定を定義します。

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

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

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

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

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

  • ドライブの onItemsSelectedTrigger。

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

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

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

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

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

  • （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"
      }
    },
    "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 フィールドを マニフェスト ファイルに含めます。

注: ホワイトリスト（urlFetchWhitelist で使用）はサポートが終了した用語で、許可リストと同義であり、置き換えられています。詳しくは、包括的なドキュメントの作成をご覧ください。

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

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

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

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