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.

   Nota: le icone dei documenti sono obsolete. L'icona dell'applicazione viene visualizzata accanto ai file di scorciatoie e scorciatoie di terze parti. Per altri tipi di file viene utilizzata una serie di icone standard.

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.
   Avviso: l'opzione per mostrare automaticamente la schermata di consenso OAuth 2.0 è stata ritirata. Non selezionare questa casella. L'applicazione deve avviare tutte le richieste di autorizzazione.

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.

    Nota: se un utente installa più app di Drive in grado di aprire un file, viene utilizzata l'app installata più di recente finché l'utente non ne sceglie un'altra.

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.

    Nota: lascia vuoto il campo Nome documento. Questo campo non è più utilizzato.

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:

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.

Nota: se pubblichi la tua app Drive su Google Workspace Marketplace, gli utenti e gli amministratori di dominio possono cercarla e installarla direttamente da Google Workspace Marketplace.

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.

Nota: tutte le app, incluse quelle che aprono i file dalle scorciatoie e le scorciatoie di terze parti, devono chiamare il metodo files.get per controllare le autorizzazioni dell'utente per un documento. Le app devono avvisare gli utenti con accesso di sola lettura quando aprono un file che non possono modificare o salvare (anziché farli perdere tempo con la modifica e poi mostrare un errore al salvataggio).

Argomenti correlati

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.