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 Calendar, Google Drive, Google Docs, Google Sheets, Google Slides별 홈페이지도 정의합니다. Gmail은 기본 홈페이지를 사용합니다.
샘플 매니페스트 설정은 다음을 사용 설정합니다.
- Calendar eventOpen 및 eventUpdated 트리거
- (Apps Script만 해당) 두 개의 Calendar 회의 솔루션
- 두 개의 범용 작업
- Drive onItemsSelectedTrigger
- Gmail 작성 작업 및 컨텍스트 트리거
- Docs linkPreviewTriggers 객체 스마트 칩을 사용한 미리보기 링크를 참고하세요.
- Docs createActionTriggers 객체 @ 메뉴에서 서드 파티 리소스 만들기를 참고하세요.
- Docs, Sheets, Slides의 파일별 인터페이스
- Google Meet sidePanelUri 및 addOnOrigins 옵션
- (HTTP만 해당) 승인 헤더를 전송하고 세분화된 동의를 지원하는 두 개의 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 필드를 매니페스트 파일에 포함합니다.

허용 목록에 프리픽스 추가

매니페스트 파일에서 허용 목록을 지정할 때 (addOns.common.openLinkUrlPrefixes 또는 urlFetchWhitelist 필드를 포함하여) URL 프리픽스 목록을 포함해야 합니다. 매니페스트에 추가하는 프리픽스는 다음 요구사항을 충족해야 합니다.

각 프리픽스는 유효한 URL이어야 합니다.
각 프리픽스는 http://가 아닌 https://를 사용해야 합니다.
각 프리픽스에는 전체 도메인이 있어야 합니다.
각 프리픽스에는 비어 있지 않은 경로가 있어야 합니다. 예를 들어 https://www.google.com/ 은 유효하지만 https://www.google.com은 유효하지 않습니다.
와일드 카드를 사용하여 URL 하위 도메인 프리픽스를 일치시킬 수 있습니다.
단일 * 와일드 카드를 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

와일드 카드 사용

단일 와일드 카드 문자 (*)를 사용하여 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 (하위 도메인이 하나 이상 있어야 함)

매니페스트를 저장하려고 할 때 일부 프리픽스 규칙이 적용됩니다. 예를 들어 저장하려고 할 때 매니페스트에 다음 프리픽스가 있으면 오류가 발생합니다.

https://*.*.example.com/foo (여러 와일드 카드는 금지됨)
https://subdomain.*.example.com/foo (와일드 카드는 선행 프리픽스로 사용해야 함)