Manifest per i componenti aggiuntivi di Google Workspace

Un componente aggiuntivo utilizza un file manifest per configurare determinati dettagli dell'app e del 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 dell'aspetto e del comportamento dei componenti aggiuntivi.

Le proprietà del file manifest per i componenti aggiuntivi di Google Workspace sono organizzate nella sezione addOns della struttura degli oggetti manifest.

• Per informazioni sui file manifest di Apps Script, consulta la pagina relativa alla struttura dei file manifest.
• Per informazioni sui file manifest per i componenti aggiuntivi creati con endpoint HTTP, fai riferimento a Risorsa REST: 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 il file manifest abilitano quanto segue:
  • Trigger di calendario eventOpen e eventUpdated.
  • (Solo Apps Script) Due soluzioni per conferenze di Calendar.
  • Due azioni universali.
  • onItemsSelectedTrigger in Drive.
  • Un'azione di scrittura di Gmail e un attivatore contestuale.
  • Un oggetto linkPreviewTriggersDocumenti. Per scoprire di più su questo trigger, consulta l'articolo Visualizzare l'anteprima dei link con smart chip.
  • Un oggetto createActionTriggers Documenti. Per saperne di più su questo trigger, consulta Creare risorse di terze parti dal menu @.
  • Interfacce specifiche per i file di Documenti, Fogli e Presentazioni.
• Il campo oauthScopes imposta gli ambiti di autorizzazione per il progetto (solitamente richiesta per i componenti aggiuntivi).
• (Solo Apps Script) 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 Inserisci URL nella lista consentita.

I link nell'esempio indirizzano alle descrizioni di tale campo nella documentazione di riferimento del file manifest corrispondente per i componenti aggiuntivi di Google Workspace Apps Script e HTTP.

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

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

Autorizzare gli URL

Puoi utilizzare le liste consentite per designare URL specifici pre-approvati per l'accesso da parte del tuo script o componente aggiuntivo. Le liste consentite aiutano a proteggere i dati utente. 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 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 gli endpoint HTTPS) utilizzando il servizio UrlFetch di Apps Script. 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 (obbligatoria 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: la lista consentita, come usata in urlFetchWhitelist, è un termine obsoleto che è sinonimo e sostituito da lista consentita. Per saperne di più, vedi Scrivere una documentazione inclusiva.

Aggiunta di prefissi alla lista consentita

Quando specifichi liste consentite nel file manifest (includendo il campo addOns.common.openLinkUrlPrefixes o urlFetchWhitelist), devi includere un elenco di prefissi URL. I prefissi che aggiungi al file 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 trovare corrispondenze con i prefissi dei sottodomini degli URL.
• È possibile utilizzare un singolo carattere jolly * nel campo addOns.common.openLinkUrlPrefixes per trovare corrispondenze per tutti i link, ma questa operazione è sconsigliata perché può esporre i dati di un utente ai rischi e può prolungare il processo di revisione dei componenti aggiuntivi. Utilizza un carattere jolly soltanto se la funzionalità del componente aggiuntivo lo richiede.

Per determinare se un URL corrisponde a un prefisso consentito, 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 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 trovare la corrispondenza di 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 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 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)