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

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 のメール作成アクションとコンテキスト トリガー。
    • ドキュメントの linkPreviewTrigger。このトリガーの詳細については、スマートチップを使用してリンクをプレビューするをご覧ください。
    • ドキュメント、スプレッドシート、スライドのファイル固有の インターフェースです
  • oauthScopes フィールドでは、プロジェクトの認証スコープを設定します(通常、アドオンで必要です)。
  • urlFetchWhitelist フィールドは、フェッチされたエンドポイントが、指定された HTTPS URL 接頭辞のリストと一致することを確認するフィールドです。詳細については、URL を許可リストに登録するをご覧ください。

サンプル内のリンクから、マニフェスト リファレンス ドキュメントの該当フィールドの説明に直接移動できます。

{
  "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 を開く、または表示する 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

ワイルドカードの使用

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