Configurare un'integrazione di Drive dell'interfaccia utente

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

Attivare l'API Drive

Prima di utilizzare le API di 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 l'interfaccia utente di Google Drive, devi abilitare l'API Drive. Questo ti permette di accedere all'API e alle funzionalità di integrazione dell'interfaccia utente.

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

  Abilita l'API

Configurare l'integrazione dell'interfaccia utente di Drive

1. Nella console API di Google, vai al 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 dell'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 breve descrizione viene mostrata agli utenti nella scheda Gestisci app delle impostazioni di Drive.
6. (Facoltativo) Inserisci una descrizione completa nel campo Descrizione lunga.

7. Carica una o più icone dell'applicazione da visualizzare nell'elenco di app Drive collegate di un utente e nel menu contestuale "Apri con". Le icone devono essere in formato PNG con uno sfondo trasparente. La visualizzazione delle icone in Drive può richiedere fino a 24 ore.

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

8. Per utilizzare la voce di menu "Apri con" della UI di Drive, inserisci l'URL dell'app nel campo Apri URL. Questo URL è 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 la release pubblica e una per la release limitata per determinati utenti, 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, un parametro di query state viene aggiunto a questo URL 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 per il consenso OAuth 2.0 è 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 e Estensioni file predefinite. I tipi MIME e le estensioni dei file predefiniti rappresentano i file per cui la tua app è stata creata in modo univoco per essere aperti. Ad esempio, l'app potrebbe aprire un formato integrato per la sovrapposizione e la modifica delle immagini. Includi solo tipi di contenuti multimediali standard e assicurati che non presentino errori di battitura ed errori ortografici. Se l'app apre solo file di scorciatoie o di scorciatoie di terze parti, puoi lasciare vuoto il tipo MIME.

10. (Facoltativo) Inserisci i tipi MIME secondari e le estensioni file nei campi Tipi MIME secondari ed Estensioni file secondarie. I tipi MIME secondari e le estensioni file rappresentano i file che l'app può aprire, ma non sono specifici per l'app. Ad esempio, l'app potrebbe essere un'app per la modifica di immagini che apre immagini PNG e JPG. Includi solo tipi di contenuti multimediali standard e assicurati che non presentino errori di battitura ed errori ortografici. Se l'app apre solo file di scorciatoie o di 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, verrà 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 facoltativi.

    • Questo URL deve contenere un nome di dominio completo; localhost non funziona.
    • Devi verificare la proprietà di questo URL prima di poter inserire la tua app in Google Workspace Marketplace.
    • Per impostazione predefinita, un parametro di query state viene aggiunto a questo URL 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 è usato 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 l'app apra i file supportati da Google Workspace, seleziona la casella Importazione.

14. (Facoltativo) Se l'app deve gestire i file sui Drive condivisi, seleziona la casella Supporto dei Drive condivisi. Per ulteriori informazioni 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 la visualizzazione delle app come opzione nel menu "Apri con" o "Nuovo", richiedi l'integrazione dell'ambito https://www.googleapis.com/auth/drive.install con l'interfaccia utente di Drive. Quando richiedono questo ambito, gli utenti ricevono una finestra di dialogo simile alla 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 Informazioni su autorizzazione e autenticazione specifiche per l'API.

Nota: se pubblichi la tua app per 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 di apertura sia al nuovo URL per trasferire i dati dall'interfaccia utente di Drive alla tua app. Questo parametro contiene una stringa con codifica JSON con variabili del modello e dati relativi alla richiesta all'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 da aprire.	Apri URL
{exportIds}	Un elenco separato da virgole di ID file da esportare (utilizzato solo quando si aprono 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.	Apri URL e nuovo URL
{action}	L'azione eseguita. Il valore è open se utilizzi un URL aperto o create quando utilizzi un nuovo URL.	Apri URL e nuovo URL

Il parametro state è codificato nell'URL, pertanto 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"
}

Informazioni di esempio 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 dispone dell'ID file e di 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 dalle scorciatoie di terze parti, devono chiamare il metodo files.get per verificare le autorizzazioni dell'utente per un documento. Le app devono avvisare gli utenti di sola lettura che aprono un file che non possono modificare o salvare (invece di concedere loro del tempo per apportare modifiche e mostrare un errore al momento del salvataggio).

Argomenti correlati

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