Configurare un'integrazione di Drive dell'interfaccia utente

Per visualizzare la tua app in Google Drive quando un utente crea o apre un file, devi prima configurare un'integrazione dell'interfaccia utente (UI) di Drive. La configurazione è necessaria anche per mostrare la tua app in Google Workspace Marketplace.

Abilita l'API Drive

Prima di utilizzare le API Google, devi attivarle in un progetto Google Cloud. Puoi attivare una o più API in un singolo progetto Google Cloud.

Per iniziare l'integrazione con la UI di Google Drive, devi abilitare l'API Drive. In questo modo avrai accesso alle funzionalità di integrazione dell'API e dell'interfaccia utente.

  • Nella console Google Cloud, abilita l'API Google Drive.

    Attiva l'API

Configurare l'integrazione con l'interfaccia utente di Drive

  1. Nella console API Google, vai a Menu > API e servizi > API e servizi abilitati.

    Vai ad API e servizi abilitati

  2. Nella parte inferiore della dashboard API e servizi, fai clic su API Google Drive. Viene visualizzata la pagina di configurazione dell'API Google Drive.
  3. Seleziona la scheda Integrazione nell'interfaccia utente di Drive.
  4. (Facoltativo) Inserisci un nome nel campo Nome applicazione. Il nome dell'applicazione viene mostrato agli utenti nella scheda Gestisci app delle impostazioni di Drive.
  5. (Facoltativo) Inserisci una breve descrizione di una riga nel campo Descrizione breve. La descrizione breve viene mostrata agli utenti nella scheda Gestisci app nelle impostazioni di Drive.
  6. (Facoltativo) Inserisci una descrizione completa nel campo Descrizione lunga.

  7. Carica una o più icone di applicazione da visualizzare nell'elenco di app di Drive collegate di un utente e nel menu contestuale "Apri con". Le icone devono essere in formato PNG con uno sfondo trasparente. Potrebbero essere necessarie fino a 24 ore prima che le icone vengano visualizzate su Drive.

  8. Per utilizzare l'elemento del menu "Apri con" dell'interfaccia utente di Drive, inserisci l'URL della tua app nel campo Apri URL. Questo URL viene utilizzato dal menu contestuale "Apri con".

    • Questo URL deve contenere un nome di dominio completo; localhost non funziona.
    • Questo URL deve essere accessibile agli utenti previsti dell'applicazione. Se hai più versioni dell'applicazione, ad esempio una per il rilascio pubblico e una per il rilascio con limitazioni per utenti selezionati, ogni versione deve utilizzare un URL univoco. Puoi quindi creare configurazioni di app diverse per ogni versione.
    • Devi verificare la proprietà di questo URL prima di poter inserire la tua app in Google Workspace Marketplace.
    • Per impostazione predefinita, a questo URL viene aggiunto un parametro di query state per trasmettere i dati dall'interfaccia utente di Drive alla tua app. Per informazioni sui contenuti del parametro state, consulta Il parametro state.

  9. (Facoltativo) Inserisci i tipi MIME e le estensioni dei file predefiniti nei campi Tipi MIME predefiniti ed Estensioni file predefinite. I tipi MIME e le estensioni file predefinite rappresentano i file che l'app è progettata per aprire in modo univoco. Ad esempio, l'app potrebbe aprire un formato integrato per la sovrapposizione e la modifica delle immagini. Includi solo tipi di media standard e assicurati che non contengano errori di battitura e di ortografia. Se l'app apre solo file di scorciatoie o di terze parti, puoi lasciare vuoto il tipo MIME.

  10. (Facoltativo) Inserisci i tipi MIME e le estensioni di file secondari nei campi Tipi MIME secondari ed Estensioni di file secondari. I tipi MIME secondari e le estensioni file rappresentano i file che possono essere aperti dall'app, ma non sono specifici per l'app. Ad esempio, l'app potrebbe essere un'app di modifica delle immagini che apre immagini PNG e JPG. Includi solo tipi di media standard e assicurati che non contengano errori di battitura e di ortografia. Se la tua app apre solo file di scorciatoie o scorciatoie di terze parti, puoi lasciare vuoto il tipo MIME.

  11. Per utilizzare il pulsante "Nuovo" della UI di Drive e consentire agli utenti di creare un file con la tua app, seleziona la casella Creazione di file. Vengono visualizzati i campi Nuovo URL e Nome documento (facoltativo).

    • Questo URL deve contenere un nome di dominio completo; localhost non funziona.
    • Devi verificare la proprietà di questo URL prima di poter mostrare la tua app nel marketplace di Google Workspace.
    • Per impostazione predefinita, a questo URL viene aggiunto un parametro di query state per trasmettere i dati dall'interfaccia utente di Drive alla tua app. Per informazioni sui contenuti del parametro state, consulta Il parametro state.

  12. Inserisci un URL nel campo Nuovo URL. Questo URL viene utilizzato dal pulsante "Nuovo" per reindirizzare l'utente alla tua applicazione.

  13. (Facoltativo) Se vuoi che la tua app apra i file supportati da Google Workspace, seleziona la casella Importazione.

  14. (Facoltativo) Se la tua app deve gestire i file sui Drive condivisi, seleziona la casella Supporto dei Drive condivisi. Per saperne di più su come supportare i Drive condivisi nella tua app, vedi Implementare il supporto dei Drive condivisi.

  15. Fai clic su Invia.

Richiedi l'ambito drive.install

Per consentire alle app di essere visualizzate come opzione nel menu "Apri con" o "Nuovo", richiedi l'ambito https://www.googleapis.com/auth/drive.install per l'integrazione con l'interfaccia utente di Drive. Quando richiedono questo ambito, gli utenti visualizzano un dialog simile al seguente:

Finestra di dialogo di installazione dell'interfaccia utente di Google Drive.
Figura 1. La finestra di dialogo di installazione quando utilizzi gli ambiti per la UI di Drive.

Per ulteriori informazioni sugli ambiti che puoi richiedere per le app di Drive e su come richiederli, consulta le informazioni su autorizzazione e autenticazione specifiche per API.

Il parametro state

Per impostazione predefinita, un parametro state viene aggiunto sia all'URL aperto sia all'URL nuovo per trasmettere i dati dall'interfaccia utente di Drive alla tua app. Questo parametro contiene una stringa codificata in JSON con le variabili del modello e i dati relativi alla richiesta alla tua app. Le variabili incluse dipendono dal tipo di URL utilizzato (URL aperto o Nuovo URL):

Variabile di modello Descrizione Applicazione URL
{ids} Un elenco separato da virgole di ID file aperti. Apri URL
{exportIds} Un elenco separato da virgole degli ID file da esportare (utilizzato solo quando si aprono i documenti Google integrati). Apri URL
{resourceKeys} Un dizionario JSON di ID file mappati alle rispettive chiavi delle risorse. Apri URL
{folderId} L'ID della cartella principale. Nuovo URL
{folderResourceKey} La chiave della risorsa della cartella padre. Nuovo URL
{userId} L'ID profilo che identifica l'utente. URL di apertura e Nuovo URL
{action} L'azione in corso. Il valore è open se si utilizza un URL di apertura o create se si utilizza un nuovo URL. URL di apertura e Nuovo URL

Il parametro state è codificato nell'URL, quindi la tua app deve gestire i caratteri di escape e analizzarlo come JSON. Le app possono rilevare il valore create nel parametro state per verificare una richiesta di creazione di un file.

Esempio di informazioni sullo stato in JSON per un nuovo URL

Le informazioni state per un nuovo URL sono:

{
  "action":"create",
  "folderId":"FOLDER_ID",
  "folderResourceKey":"FOLDER_RESOURCE_KEY",
  "userId":"USER_ID"
}

Esempio di informazioni sullo stato in JSON per un URL aperto

Le informazioni state per un URL aperto sono:

{
  "ids": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

Gli ID e le chiavi delle risorse vengono utilizzati per recuperare i metadati dei file e scaricare i contenuti dei file. Una volta che l'app ha l'ID file e un token di accesso, può controllare le autorizzazioni, recuperare i metadati del file e scaricare i contenuti del file come descritto nel metodo files.get.

Un'app installata deve essere in grado di creare, gestire e aprire le azioni avviate dall'interfaccia utente di Drive. Per scoprire di più, consulta Eseguire l'integrazione con il pulsante "Nuovo" dell'interfaccia utente di Drive o Eseguire l'integrazione con il menu contestuale "Apri con" dell'interfaccia utente di Drive.