Un complemento usa un archivo de manifiesto para configurar ciertos detalles sobre la app y su funcionamiento.
Esta documentación abarca los detalles de la configuración de un manifiesto para un el complemento de Google Workspace.
Estructura del manifiesto para complementos de Google Workspace
Los complementos de Google Workspace usan el archivo de manifiesto para definir varios aspectos del complementos la apariencia y el comportamiento.
Las propiedades del manifiesto para los complementos de Google Workspace son las siguientes:
organizado en la sección addOns
de la estructura del objeto del manifiesto.
- Para obtener información sobre los archivos de manifiesto de Apps Script, consulta Estructura del manifiesto.
- Para obtener información sobre los archivos de manifiesto para complementos compilados con
Extremos HTTP, consulta Recurso REST:
projects.deployments
Ejemplo de configuración del manifiesto del complemento de Google Workspace
El siguiente ejemplo de manifiesto muestra la sección de un archivo de manifiesto que define complementos de Google Workspace, incluidos los siguientes aspectos:
- El
addOns.common
del manifiesto define el nombre, la URL del logotipo, los colores y otras configuración general independiente del host para el complemento. - El manifiesto define una página principal común, pero también define Calendario, Drive, Documentos páginas principales específicas de Hojas de cálculo y Presentaciones. Gmail usa la página principal predeterminada.
- La configuración del manifiesto de muestra habilita lo siguiente:
- Activadores de
eventOpen
yeventUpdated
del calendario. - (Solo Apps Script) Dos calendarios soluciones para conferencias.
- Dos acciones universales.
- Una
onItemsSelectedTrigger
de Drive - Una acción de redacción y un activador contextual de Gmail.
- Un objeto
linkPreviewTriggers
de Documentos. Para obtener información sobre este activador, Consulta Obtén una vista previa de vínculos con chips inteligentes. - Un objeto
createActionTriggers
de Documentos. Para obtener información sobre este activador, consulta Crea recursos de terceros desde el menú @. - Las interfaces específicas de archivos para Documentos, Hojas de cálculo, y Presentaciones.
- Activadores de
- El campo
oauthScopes
establece permisos de autorización para el proyecto (suele ser necesario para complementos). - (Solo Apps Script)
urlFetchWhitelist
es un campo que garantiza que cualquier extremo recuperado coincida con un una lista de prefijos de URLs HTTPS. Para obtener más información, consulta URL de la lista de entidades permitidas.
Los vínculos del ejemplo dirigen a las descripciones. de ese campo en la documentación de referencia del manifiesto para Apps Script y HTTP Complementos de 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" } } }, "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" ] }
URLs de la lista de entidades permitidas
Usas listas de entidades permitidas para designar URLs específicas que están preaprobadas para el acceso. por tu guion o complemento. Las listas de entidades permitidas ayudan a proteger data; Cuando defines una lista de entidades permitidas, los proyectos de secuencias de comandos no pueden acceder a las URLs que tienen no se incluyó en la lista de entidades permitidas.
Este campo es opcional cuando instalas una implementación de prueba, pero es obligatorio cuando crearás una implementación con control de versiones.
Usas listas de entidades permitidas cuando tu secuencia de comandos o complemento tiene buen rendimiento. las siguientes acciones:
- Recupera u recupera información de una ubicación externa (como HTTPS
extremos) mediante Apps Script
UrlFetch
servicio. Para incluir URLs en la lista de entidades permitidas para la recuperación, incluye el campourlFetchWhitelist
en tu archivo de manifiesto. - Abre o muestra una URL en respuesta a una acción del usuario (obligatorio para
Complementos de Google Workspace que abren o muestran URLs externas a
Google). Para incluir URLs en la lista de entidades permitidas de apertura, incluye el campo
addOns.common.openLinkUrlPrefixes
en tu .
Agrega prefijos a tu lista de entidades permitidas
Cuando especificas listas de entidades permitidas en tu archivo de manifiesto (incluyendo
addOns.common.openLinkUrlPrefixes
o urlFetchWhitelist
), debes
incluir una lista de prefijos de URL. Los prefijos que agregues al manifiesto deben
cumplan con los siguientes requisitos:
- Cada prefijo debe ser una URL válida.
- Cada prefijo debe usar
https://
, nohttp://
. - Cada prefijo debe tener un dominio completo.
- Cada prefijo debe tener una ruta de acceso que no esté vacía. Por ejemplo,
https://www.google.com/
. es válido, perohttps://www.google.com
no lo es. - Puedes usar comodines para hacer coincidir los prefijos de subdominios de URL.
- Se puede usar un solo comodín
*
en eladdOns.common.openLinkUrlPrefixes
para que coincida con todos los vínculos, pero esto no se recomienda, ya que puede exponer un de los datos del usuario a poner en riesgo y prolongar proceso de revisión de complementos. Solo usa un comodín si la funcionalidad de tu complemento lo requiere.
Para determinar si una URL coincide con un prefijo de la lista de entidades permitidas, se aplican las siguientes reglas aplicar:
- La coincidencia de rutas distingue entre mayúsculas y minúsculas.
- Si el prefijo es idéntico a la URL, es una coincidencia.
- Si la URL es la misma o un elemento secundario del prefijo, se trata de una coincidencia.
Por ejemplo, el prefijo https://example.com/foo
coincide con las siguientes URLs:
https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar
Usa comodines
Puedes usar un solo carácter comodín (*
) para hacer coincidir un subdominio para
urlFetchWhitelist
y addOns.common.openLinkUrlPrefixes
. No puedes usar más de un comodín para hacer coincidir varios subdominios.
el comodín debe representar el prefijo inicial de la URL.
Por ejemplo, el prefijo https://*.example.com/foo
coincide con lo siguiente:
URL:
https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo
El prefijo https://*.example.com/foo
no coincide con lo siguiente
URL:
https://subdomain.example.com/bar
(el sufijo no coincide)https://example.com/foo
(debe haber al menos un subdominio)
Algunas de las reglas de prefijo se aplican de manera forzosa cuando intentas guardar el manifiesto. Para ejemplo, los siguientes prefijos generan un error si están presentes en tu manifiesto cuando intentas guardar:
https://*.*.example.com/foo
(se prohíben varios comodines)https://subdomain.*.example.com/foo
(se deben utilizar comodines como prefijos iniciales)