Un componente aggiuntivo utilizza un file manifest per configurare determinati dettagli sull'app e sul suo funzionamento.
Questa documentazione illustra i dettagli della configurazione di un manifest per un componente aggiuntivo di Google Workspace.
Struttura manifest per i componenti aggiuntivi di Google Workspace
I componenti aggiuntivi di Google Workspace utilizzano il file manifest per definire diversi aspetti del componenti aggiuntivi aspetto e comportamento.
Le proprietà del file manifest per i componenti aggiuntivi di Google Workspace sono
organizzati nella sezione addOns
della struttura degli oggetti manifest.
- Per informazioni sui file manifest di Apps Script, consulta Struttura del manifest.
- Per informazioni sui file manifest per i componenti aggiuntivi creati con endpoint HTTP, consulta REST Resource:
projects.deployments
Esempio di configurazione manifest del componente aggiuntivo di Google Workspace
Il seguente esempio di manifest mostra la sezione di un file manifest che definisce un componente aggiuntivo di Google Workspace, inclusi i seguenti aspetti:
- La sezione
addOns.common
del file manifest definisce il nome, l'URL del logo, i colori e altre impostazioni generali indipendenti dall'host per il componente aggiuntivo. - Il file manifest definisce una home page comune, ma anche home page specifiche per Calendar, Drive, Documenti, Fogli e Presentazioni. Gmail utilizza la home page predefinita.
- Le impostazioni di esempio per i file manifest abilitano quanto segue:
- Trigger
eventOpen
eeventUpdated
del calendario. - (Solo Apps Script) Due soluzioni per le conferenze di Calendar.
- Due azioni universali.
onItemsSelectedTrigger
in Drive.- Un'azione di scrittura di Gmail e un attivatore contestuale.
- Un oggetto
linkPreviewTriggers
di Documenti. Per scoprire di più su questo attivatore, consulta Visualizza l'anteprima dei link con gli smart chip. - Un oggetto
createActionTriggers
di Documenti. Per saperne di più su questo trigger, consulta la sezione Creare risorse di terze parti dal menu @. - Interfacce specifiche per i file di Documenti, Fogli e Presentazioni.
- Trigger
- Il campo
oauthScopes
imposta gli ambiti di autorizzazione per il progetto (in genere richiesto per i componenti aggiuntivi). - (Solo Apps Script) Il campo
urlFetchWhitelist
garantisce che tutti gli endpoint recuperati corrispondano a un elenco specificato di prefissi URL HTTPS. Per ulteriori informazioni, consulta URL della lista consentita.
I link nell'esempio rimandano alle descrizioni di quel campo nella documentazione di riferimento del manifest corrispondente per Apps Script e i componenti aggiuntivi di Google Workspace HTTP.
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" ] }
URL nella lista consentita
Puoi utilizzare le liste consentite per designare URL specifici pre-approvati per l'accesso dallo script o dal componente aggiuntivo. Le liste consentite aiutano a proteggere i dati degli utenti. Quando definisci una lista consentita, i progetti di script non possono accedere agli URL che non sono stati inclusi nella lista.
Questo campo è facoltativo quando installi un deployment di prova, ma è obbligatorio quando un deployment con controllo delle versioni.
Utilizzi le liste consentite quando lo script o il componente aggiuntivo vengono eseguiti le seguenti azioni:
- Recupera o recupera informazioni da una posizione esterna (ad esempio endpoint HTTPS) utilizzando il servizio
UrlFetch
di Apps Script. Per inserire gli URL nella lista consentita per il recupero, includi il campourlFetchWhitelist
nel file manifest. - Apre o mostra un URL in risposta a un'azione dell'utente (obbligatorio per i componenti aggiuntivi di Google Workspace che aprono o mostrano URL esterni a Google). Per inserire nella lista consentita gli URL da aprire, includi il campo
addOns.common.openLinkUrlPrefixes
nel file manifest.
Aggiunta di prefissi alla lista consentita
Quando specifichi le liste consentite nel file manifest (includendo il campo addOns.common.openLinkUrlPrefixes
o urlFetchWhitelist
), devi includere un elenco di prefissi URL. I prefissi aggiunti al manifest devono soddisfare i seguenti requisiti:
- Ogni prefisso deve essere un URL valido.
- Ogni prefisso deve utilizzare
https://
, nonhttp://
. - Ogni prefisso deve avere un dominio completo.
- Ogni prefisso deve avere un percorso non vuoto. Ad esempio,
https://www.google.com/
è valido, mentrehttps://www.google.com
non lo è. - Puoi utilizzare i caratteri jolly per trovare corrispondenze ai prefissi dei sottodomini dell'URL.
- È possibile utilizzare un singolo carattere jolly
*
nel campoaddOns.common.openLinkUrlPrefixes
per trovare corrispondenze per tutti i link, ma questa operazione non è consigliata in quanto può mettere a rischio i dati di un utente e prolungare la procedura di revisione dei componenti aggiuntivi. Solo utilizza un carattere jolly se la funzionalità del componente aggiuntivo lo richiede.
Per determinare se un URL corrisponde a un prefisso nella lista consentita, si applicano le seguenti regole:
- La corrispondenza del percorso è sensibile alle maiuscole.
- Se il prefisso è identico all'URL, viene considerata una corrispondenza.
- Se l'URL è uguale o è un elemento secondario del prefisso, si tratta di una corrispondenza.
Ad esempio, il prefisso https://example.com/foo
corrisponde ai seguenti URL:
https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar
Utilizzo dei caratteri jolly
Puoi utilizzare un singolo carattere jolly (*
) per trovare la corrispondenza di un sottodominio sia per il
urlFetchWhitelist
e addOns.common.openLinkUrlPrefixes
campi. Non puoi utilizzare più di un carattere jolly per associare più sottodomini e il carattere jolly deve rappresentare il prefisso iniziale dell'URL.
Ad esempio, il prefisso https://*.example.com/foo
corrisponde alla seguente
URL:
https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo
Il prefisso https://*.example.com/foo
non corrisponde ai seguenti
URL:
https://subdomain.example.com/bar
(mancata corrispondenza del suffisso)https://example.com/foo
(deve essere presente almeno un sottodominio)
Alcune delle regole per i prefissi vengono applicate quando provi a salvare il file manifest. Ad esempio, i seguenti prefissi causano un errore se sono presenti nel manifest quando provi a salvare:
https://*.*.example.com/foo
(non sono consentiti più caratteri jolly)https://subdomain.*.example.com/foo
(i caratteri jolly devono essere utilizzati come prefisso iniziale)