L'API Google Slides consente di creare e modificare presentazioni di Presentazioni Google.
Le app possono integrarsi con l'API Presentazioni Google per creare automaticamente bellissime presentazioni con i dati forniti dall'utente e dal sistema. Ad esempio, puoi utilizzare i dettagli dei clienti di un database e combinarli con modelli predefiniti e opzioni di configurazione selezionate per creare presentazioni complete in una frazione del tempo necessario per crearle manualmente.
Panoramica dell'API
La raccolta presentations fornisce metodi che ti consentono di recuperare e aggiornare gli elementi all'interno della presentazione.
La maggior parte del tuo lavoro con l'API Slides consisterà probabilmente nella creazione e nell'aggiornamento delle presentazioni. A questo scopo, utilizza il metodo batchUpdate, che accetta un elenco di oggetti Request che ti consentono di eseguire operazioni quali:
- Crea slide
- Aggiungere elementi alle diapositive, ad esempio forme o tabelle
- Inserire, modificare ed eliminare testo
- Applicare trasformazioni agli elementi
- Modificare l'ordine delle diapositive
Per ulteriori dettagli, consulta Aggiornamenti collettivi. Consulta le guide introduttive per un semplice esempio end-to-end di come utilizzare l'API.
La struttura di una presentazione
Una presentazione nell'API Slides è composta da pagine che contengono elementi di pagina.
L'ID di una presentazione può essere ricavato dall'URL:
https://docs.google.com/presentation/d/presentationId/edit
L'ID presentazione è una stringa contenente lettere, numeri e alcuni caratteri speciali. La seguente espressione regolare può essere utilizzata per estrarre l'ID presentazione da un URL di Fogli Google:
/presentation/d/([a-zA-Z0-9-_]+)
Se hai familiarità con l'API Drive, presentationId corrisponde all'ID della risorsa File.
Le pagine e gli elementi delle pagine sono identificati dagli ID oggetto.
Pagine
Google Presentazioni offre i seguenti tipi di pagine:
| Master | Gli schemi di diapositiva definiscono gli stili di testo, lo sfondo e gli elementi di pagina predefiniti visualizzati in tutte le diapositive che utilizzano questo schema. Gli elementi della pagina che devono apparire su tutte le diapositive devono essere aggiunti al master. La maggior parte delle presentazioni ha un master, ma alcune potrebbero averne diversi o nessuno. |
| Layout | I layout fungono da modello per l'organizzazione predefinita degli elementi della pagina nelle diapositive che li utilizzano. Ogni layout è associato a un master. |
| Presentazioni | Queste pagine contengono i contenuti che presenti al tuo pubblico. La maggior parte delle diapositive si basa su un modello e un layout. Puoi specificare il layout da utilizzare per ogni diapositiva al momento della creazione. |
| Note | Queste pagine contengono i contenuti per i materiali di supporto della presentazione, tra cui una forma che contiene le note per chi presenta della slide. Ogni diapositiva ha una pagina di note corrispondente. Solo il testo nella forma delle note del relatore può essere modificato con l'API Slides. |
| Note principali | I modelli di note definiscono gli stili di testo e gli elementi di pagina predefiniti per tutte le pagine di note. I modelli di note sono di sola lettura nell'API Slides. |
Elementi pagina
Gli elementi della pagina sono i componenti visivi posizionati nelle pagine. L'API espone diversi tipi di elementi di pagina:
| Gruppo | Un insieme di elementi di pagina trattati come una singola unità. Possono essere spostati, scalati e ruotati insieme. |
| Shape | Un semplice oggetto visivo, come rettangoli, ellissi e caselle di testo. Le forme possono contenere testo, quindi sono gli elementi di pagina più comuni per creare le diapositive. |
| Immagine | Un'immagine importata in Presentazioni. |
| Video | Un video importato in Presentazioni. |
| Linea | Una linea, una curva o un connettore visivo. |
| Tabella | Una griglia di contenuti. |
| WordArt | Un elemento di testo visivo che si comporta più come una forma. |
| SheetsChart | Un grafico importato in Presentazioni da Fogli Google. |
Aggiornamenti batch
Il metodo batchUpdate consente di aggiornare molti aspetti di una presentazione. Le modifiche vengono raggruppate in un batch in modo che, se una richiesta non va a buon fine, nessuna delle altre modifiche (potenzialmente dipendenti) venga scritta.
Il metodo batchUpdate funziona prendendo uno o più oggetti
Request, ognuno dei quali specifica un singolo tipo di richiesta da eseguire. Esistono
diversi tipi di richieste. Ecco una suddivisione dei tipi di richieste,
gruppate in diverse categorie.
Il metodo batchUpdate restituisce un corpo della risposta, che contiene una risposta per ogni richiesta. Ogni risposta occupa lo stesso indice della richiesta corrispondente. Per le richieste senza risposta applicabile, la risposta in quell'indice sarà vuota. Le varie richieste Create di solito hanno risposte, in modo da conoscere l'ID dell'oggetto appena aggiunto.
Utilizzo degli ID oggetto
Una presentazione nell'API Slides è composta da pagine ed elementi di pagina. Questi oggetti includono una stringa ID oggetto univoca all'interno di una presentazione.
Specifica degli ID oggetto al momento della creazione
Quando crei pagine o elementi di pagina utilizzando il metodo batchUpdate, se vuoi puoi specificare un ID oggetto per il nuovo oggetto. In questo modo puoi creare un oggetto e modificarlo all'interno della stessa richiesta batchUpdate, riducendo al minimo il numero di chiamate all'API Presentazioni e l'utilizzo della quota.
Nella maggior parte dei casi, ti consigliamo di generare un ID oggetto casuale. Ad esempio, se utilizzi Java, java.util.UUID.randomUUID().toString() dovrebbe funzionare bene.
Quando la tua applicazione vuole tenere traccia degli oggetti per un periodo di tempo più lungo, non fare affidamento sull'ID oggetto, in quanto potrebbe cambiare. Per ulteriori dettagli, consulta la sezione che segue.
Monitorare gli oggetti senza utilizzare l'ID oggetto
Quando effettui una richiesta all'API Slides, l'ID oggetto viene normalmente mantenuto. Eventuali eccezioni sono indicate nella documentazione di riferimento del metodo. Se crei una copia di un'intera presentazione con l'API Drive, vengono preservati anche gli ID oggetto.
Tuttavia, non puoi fare affidamento sul fatto che un ID oggetto non venga modificato dopo che una presentazione è stata modificata nell'interfaccia utente di Presentazioni. Ad esempio, se un utente utilizza l'interfaccia utente di Presentazioni per copiare e incollare un elemento della pagina e poi elimina l'originale, l'elemento della pagina avrà un nuovo ID univoco e l'ID fornito in precedenza tramite l'API andrà perso. Di conseguenza, ti sconsigliamo di memorizzare gli ID oggetto nello spazio di archiviazione della tua applicazione. Dovresti invece trovare gli oggetti nella presentazione tramite i contenuti di testo o il testo alternativo.
Le presentazioni appena create utilizzano in genere un insieme coerente di ID per le diapositive, le strutture di base e le caselle di testo predefinite. Questi ID sono soggetti a variazioni nel tempo, pertanto sconsigliamo di fare affidamento su questa funzionalità. Trova invece gli elementi che vuoi modificare utilizzando l'oggetto presentazione restituito dalle chiamate a create() o get().