Manifest per i componenti aggiuntivi di Google Workspace

Un progetto Apps Script utilizza un file manifest per configurare determinati dettagli relativi allo script e al suo funzionamento. Per scoprire come visualizzare e modificare un manifest, consulta i file manifest.

Questa documentazione illustra i dettagli della configurazione di un manifest per un componente aggiuntivo di Google Workspace.

Struttura del file manifest per i componenti aggiuntivi di Google Workspace

I componenti aggiuntivi di Google Workspace utilizzano il file manifest del progetto Apps Script per definire diversi aspetti dell'aspetto e del comportamento del componente. Le proprietà del manifest per i componenti aggiuntivi di Google Workspace sono organizzate nella sezione addOns della struttura dell'oggetto manifest.

Esempio di configurazione del manifest del componente aggiuntivo di Google Workspace

Il seguente esempio di file 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 manifest definisce il nome, l'URL del logo, i colori e altre impostazioni generali indipendenti dall'host per il componente aggiuntivo.
• Il manifest definisce una home page comune, ma definisce anche home page specifiche di Calendar, Drive, Documenti, Fogli e Presentazioni. Gmail utilizza la home page predefinita.
• Le impostazioni del file manifest di esempio abilitano quanto segue:
  • Trigger eventOpen e eventUpdated e due soluzioni per conferenze di Calendar.
  • Due azioni universali.
  • Un Drive onItemsSelectedTrigger.
  • Un'azione di scrittura e un attivatore contestuale di Gmail.
  • Un file di Documenti linkPreviewTrigger. Per scoprire di più su questo attivatore, consulta Visualizzare l'anteprima dei link con smart chip.
  • Interfacce specifiche per i file per Documenti, Fogli e Presentazioni.
• Il campo oauthScopes imposta gli ambiti di autorizzazione per il progetto (in genere è obbligatorio per i componenti aggiuntivi).
• Il campo urlFetchWhitelist è un campo che garantisce che qualsiasi endpoint recuperato corrisponda a un elenco specificato di prefissi URL HTTPS. Questo campo è facoltativo per i deployment di test, ma è obbligatorio per i deployment. Per maggiori informazioni, consulta la pagina URL della lista consentita.

I link nell'esempio rimandano alle descrizioni di quel campo nella documentazione di riferimento del manifest.

Nota: i manifest includono altri componenti correlati alle proprietà Apps Script. I campi all'interno del campo addOns fanno riferimento direttamente ai componenti aggiuntivi di Google Workspace. Questo esempio è solo una parte di un file manifest completo e non è un manifest completamente funzionale.

// Sample configuration of the addOns section in a manifest file:
{
  "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 lista consentita

Puoi utilizzare le liste consentite per designare URL specifici preapprovati per l'accesso da parte del tuo script o componente aggiuntivo. Le liste consentite contribuiscono 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 consentita.

Puoi utilizzare le liste consentite quando lo script o il componente aggiuntivo esegue le seguenti azioni:

• Recupera o recupera informazioni da una posizione esterna (come gli endpoint HTTPS) utilizzando il servizio Apps Script UrlFetch. Per inserire gli URL nella lista consentita per il recupero, includi il campo urlFetchWhitelist nel file manifest.
• Apre o mostra un URL in risposta all'azione di un utente (obbligatorio per i componenti aggiuntivi di Google Workspace che aprono o mostrano URL esterni a Google). Per inserire gli URL nella lista consentita per l'apertura, includi il campo addOns.common.openLinkUrlPrefixes nel file manifest.

Nota: Whitelist, come utilizzato in urlFetchWhitelist, è un termine deprecato sinonimo di allowlist. Per ulteriori informazioni, consulta la sezione Scrivere una documentazione inclusiva.

Aggiungere 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://, non http://.
• Ogni prefisso deve avere un dominio completo.
• Ogni prefisso deve avere un percorso non vuoto. Ad esempio, https://www.google.com/ è valido, mentre https://www.google.com non lo è.
• Puoi utilizzare caratteri jolly per creare corrispondenze con i prefissi URL del sottodominio.
• Un singolo carattere jolly * può essere utilizzato nel campo addOns.common.openLinkUrlPrefixes per corrispondere a tutti i link, ma questa azione non è consigliata in quanto può esporre i dati di un utente al rischio e prolungare il processo di revisione dei componenti aggiuntivi. Utilizzare un carattere jolly solo se la funzionalità di componente aggiuntivo lo richiede.

Per determinare se un URL corrisponde a un prefisso incluso nella lista consentita, si applicano le seguenti regole:

• La corrispondenza dei percorsi è sensibile alle maiuscole.
• Se il prefisso è identico all'URL, si tratta di una corrispondenza.
• Se l'URL è uguale o 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 di caratteri jolly

Puoi utilizzare un singolo carattere jolly (*) per creare una corrispondenza con un sottodominio per entrambi i campi urlFetchWhitelist e addOns.common.openLinkUrlPrefixes. Non puoi utilizzare più di un carattere jolly per creare corrispondenze di più sottodomini e il carattere jolly deve rappresentare il prefisso iniziale dell'URL.

Ad esempio, il prefisso https://*.example.com/foo corrisponde ai seguenti 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 (suffisso non corrispondente)
• https://example.com/foo (deve essere presente almeno un sottodominio)

Alcune regole per i prefissi vengono applicate quando provi a salvare il manifest. Ad esempio, i seguenti prefissi causano un errore se sono presenti nel manifest quando provi a salvare:

• https://*.*.example.com/foo (sono vietati più caratteri jolly)
• https://subdomain.*.example.com/foo (I caratteri jolly devono essere utilizzati come prefisso iniziale)