Manifest per i componenti aggiuntivi di Google Workspace

Un progetto Apps Script utilizza un file manifest per configurare alcuni dettagli dello script e del suo funzionamento. Per informazioni su come visualizzare e modificare un manifest, consulta la sezione Manifest.

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

Struttura del manifest per i componenti aggiuntivi di Google Workspace

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

Esempio di configurazione del file manifest dei componenti aggiuntivi 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 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 di Calendar, Drive, Documenti, Fogli e Presentazioni. Gmail utilizza la home page predefinita.
• Le impostazioni del file manifest di esempio consentono di:
  • Attivatori di Calendar eventOpen e eventUpdated e due soluzioni per le conferenze di Calendar.
  • Due azioni universali.
  • Un onItemsSelectedTrigger in auto.
  • Un'azione di scrittura di Gmail e un attivatore contestuale.
  • Un linkPreviewTrigger di Documenti. Per scoprire di più su questo attivatore, consulta Visualizzare l'anteprima dei link con smart chip.
  • Interfacce specifiche dei file per Documenti, Fogli e Presentazioni.
• Il campo oauthScopes imposta gli ambiti di autorizzazione per il progetto (in genere richiesto per i componenti aggiuntivi).
• Il campo urlFetchWhitelist è un campo che garantisce che tutti gli endpoint recuperati corrispondano a un elenco specificato di prefissi URL HTTPS. Per maggiori informazioni, consulta la pagina relativa alla lista consentita di URL.

I link nell'esempio indirizzano alle descrizioni del campo nella documentazione di riferimento del file manifest.

Nota: i manifest includono altri componenti relativi alle proprietà Apps Script. I campi sotto il campo addOns sono relativi direttamente ai componenti aggiuntivi di Google Workspace. Questo esempio è solo una parte di un file manifest completo e non è un manifest completamente funzionale.

{
  "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/"
  ]
}

Inserisci URL nella lista consentita

Puoi utilizzare le liste consentite per designare URL specifici preapprovati per l'accesso da parte dello script o del 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 inseriti nella lista consentita.

Questo campo è facoltativo quando installi un deployment di prova, ma è obbligatorio quando crei un deployment con il controllo delle versioni.

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

• Recupera o recupera informazioni da una posizione esterna (ad esempio 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 visualizza 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 per l'apertura, includi il campo addOns.common.openLinkUrlPrefixes nel file manifest.

Nota: Whitelist, come utilizzato in urlFetchWhitelist, è un termine obsoleto che è sinonimo di lista consentita e viene sostituito. Per saperne di più, consulta Scrivere una documentazione inclusiva.

Aggiungere prefissi alla lista consentita

Quando specifichi liste consentite nel tuo 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, ma https://www.google.com non lo è.
• Puoi utilizzare i caratteri jolly per trovare corrispondenze con i prefissi dei sottodomini URL.
• È possibile utilizzare un singolo carattere jolly * nel campo addOns.common.openLinkUrlPrefixes per trovare corrispondenze di tutti i link, ma si tratta di un'operazione sconsigliata perché potrebbe esporre a rischi i dati di un utente e può prolungare il processo di revisione dei componenti aggiuntivi. Utilizza un carattere jolly solo se la funzionalità del componente aggiuntivo lo richiede.

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

• La corrispondenza del percorso è sensibile alle maiuscole.
• Se il prefisso è identico all'URL, è una corrispondenza.
• Se l'URL è uguale o è un URL secondario del prefisso, la 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 trovare una corrispondenza con un sottodominio per entrambi i campi urlFetchWhitelist e addOns.common.openLinkUrlPrefixes. Non puoi utilizzare più di un carattere jolly per trovare corrispondenze con 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 il prefisso vengono applicate quando provi a salvare il manifest. Ad esempio, i seguenti prefissi causano un errore se sono presenti nel file manifest quando tenti di salvare:

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