Manifest per i componenti aggiuntivi di Google Workspace

Un componente aggiuntivo utilizza un file manifest per configurare alcuni 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 del 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.

Le proprietà del manifest per i componenti aggiuntivi di Google Workspace sono organizzate nella sezione addOns.

• Per informazioni sui file manifest di Google Apps Script, consulta Struttura del manifest.

• Per informazioni sui file manifest per i componenti aggiuntivi creati con endpoint HTTP, consulta projects.deployments.

Manifest per Google Chat

Se il tuo componente aggiuntivo di Google Workspace estende Google Chat, configura un' app di Google Chat attivando e configurando l'API Google Chat nella console Google Cloud.

Le impostazioni di configurazione del manifest comuni (incluso addons.common) vengono ignorate in Chat. Utilizza l'API Chat per configurare le seguenti impostazioni di Chat:

• Il nome, il logo e la descrizione dell'app di Chat per l'interfaccia utente di Chat.
• Trigger dell'app di Chat.

Se hai creato il componente aggiuntivo in Apps Script, aggiungi o aggiorna i seguenti oggetti nel manifest:

• addons.chat (obbligatorio)
• oauthScopes (obbligatorio se l'app di Google Chat utilizza OAuth)

Per configurare le impostazioni di Chat per un componente aggiuntivo, consulta Configurare un'app di Google Chat.

Esempio di configurazione del manifest di un componente aggiuntivo di Google Workspace

I seguenti esempi mostrano la parte di un manifest che definisce un componente aggiuntivo di Google Workspace, inclusi i seguenti aspetti:

• addOns.common definisce il nome, il logo, i colori e altre impostazioni generali per il componente aggiuntivo.

• Il manifest definisce una home page comune, ma anche home page specifiche di Google Calendar, Google Drive, Documenti Google, Fogli Google e Presentazioni Google. Gmail utilizza la home page predefinita.

• Le impostazioni del manifest di esempio consentono di:

  • Trigger eventOpen e eventUpdated di Calendar.

  • (Solo Apps Script) Due soluzioni per le conferenze di Calendar.

  • Due azioni universali.

  • Un trigger onItemsSelectedTrigger di Drive.

  • Un'azione di composizione di Gmail e un trigger contestuale.

  • Un oggetto linkPreviewTriggers di Documenti. Consulta Visualizzare l'anteprima dei link con smart chip.

  • Un oggetto createActionTriggers di Documenti. Consulta Creare risorse di terze parti dal menu @.

  • Interfacce specifiche per i file di Documenti, Fogli e Presentazioni.

  • Un'opzione sidePanelUri e addOnOrigins di Google Meet.

  • (Solo HTTP) Due HttpOptions per l'invio di un'intestazione di autorizzazione e il supporto del consenso granulare.

• Il campo oauthScopes imposta gli ambiti di autorizzazione del progetto.

• (Solo Apps Script) urlFetchWhitelist garantisce che gli endpoint recuperati corrispondano ai prefissi URL HTTPS specificati. Consulta Liste consentite di URL.

I link negli esempi reindirizzano alle descrizioni dei campi nel manifest riferimento per Apps Script e HTTP componenti aggiuntivi di Google Workspace.

I manifest includono altri componenti. I campi in addOns sono correlati direttamente ai componenti aggiuntivi di Google Workspace. Questo esempio mostra solo una parte di un file manifest completo e non è funzionale da solo.

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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/logoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
    },
  },
  "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"
      }
    },
    "meet": {
      "homepageTrigger",
      "Web": [
        {
          "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
          "supportsScreenSharing": true,
          "addOnOrigins": [
            "https://www.myownpersonaldomain.com",
            "https://www.myownpersonaldomain.com:443"
          ],
          "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl",
          "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
        }
      ]
    },
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "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"
  ]
}

Liste consentite di URL

Utilizza le liste consentite per designare URL specifici che sono pre-approvati per l'accesso da parte dello script o del componente aggiuntivo. Le liste consentite contribuiscono a proteggere i dati utente. Quando definisci una lista consentita, i progetti di script non possono accedere agli URL che non sono stati aggiunti alla lista consentita.

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

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

• Recupera o recupera informazioni da una posizione esterna (ad es. endpoint HTTPS ) utilizzando il servizio UrlFetch di Apps Script. Per consentire gli URL per il recupero, includi il urlFetchWhitelist campo 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 visualizzano URL esterni a Google). Per consentire gli URL per l'apertura, includi il addOns.common.openLinkUrlPrefixes campo nel tuo file manifest.

Nota: Whitelist, come utilizzato in urlFetchWhitelist, è un termine ritirato che è sinonimo di lista consentita e sostituito da quest'ultima. Per ulteriori informazioni, consulta Scrivere 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 che aggiungi 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 la corrispondenza con i prefissi dei sottodomini URL.
• È possibile utilizzare un singolo carattere jolly * nel addOns.common.openLinkUrlPrefixes campo per trovare la corrispondenza con tutti i link, ma non è consigliabile perché può esporre i dati di un utente a rischi e può prolungare la procedura di revisione del componente aggiuntivo. Utilizza un carattere jolly solo se la funzionalità del componente aggiuntivo lo richiede.

Quando determini se un URL corrisponde a un prefisso nella lista consentita, si applicano le seguenti regole:

• La corrispondenza del percorso fa distinzione tra maiuscole e minuscole.
• Se il prefisso è identico all'URL, si tratta di 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

Utilizzare i caratteri jolly

Puoi utilizzare un singolo carattere jolly (*) per trovare la corrispondenza con un sottodominio per i campi urlFetchWhitelist e addOns.common.openLinkUrlPrefixes. Non puoi utilizzare più di un carattere jolly per trovare la corrispondenza 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 (mancata corrispondenza del suffisso)
• https://example.com/foo (deve essere presente almeno un sottodominio)

Alcune delle regole dei prefissi vengono applicate quando tenti di salvare il manifest. Ad esempio, i seguenti prefissi causano un errore se sono presenti nel manifest quando tenti di salvarlo:

• https://*.*.example.com/foo (i caratteri jolly multipli non sono consentiti)
• https://subdomain.*.example.com/foo (i caratteri jolly devono essere utilizzati come prefisso iniziale)