L'API Presentazioni Google consente di creare e modificare presentazioni di Presentazioni Google.
Le app possono integrarsi con l'API Presentazioni Google per creare automaticamente presentazioni efficaci a partire dai dati forniti dall'utente e dal sistema. Ad esempio, puoi utilizzare i dettagli dei clienti ricavati da un database e combinarli con modelli predefiniti e opzioni di configurazione selezionate per creare presentazioni completate in una frazione del tempo necessario per crearle manualmente.
Panoramica dell'API
La raccolta delle presentazioni offre metodi che ti consentono di recuperare e aggiornare gli elementi all'interno della presentazione.
La maggior parte del tuo lavoro con l'API Presentazioni sarà probabilmente incentrata sulla creazione e l'aggiornamento di presentazioni. Per farlo devi usare il metodo batchUpdate, che richiede un elenco di oggetti Request che ti consentono di eseguire operazioni quali:
- Crea slide
- Aggiungere elementi alle slide come forme o tabelle
- Inserire, modificare e rimuovere testo
- Applicare le trasformazioni agli elementi
- Modificare l'ordine delle slide
Per ulteriori dettagli, consulta Aggiornamenti collettivi. Consulta le guide introduttive per un semplice esempio end-to-end sull'uso dell'API.
La struttura di una presentazione
Una presentazione nell'API Presentazioni è 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. Per estrarre l'ID presentazione da un URL di Fogli Google puoi utilizzare la seguente espressione regolare:
/presentation/d/([a-zA-Z0-9-_]+)
Se hai dimestichezza con l'API Drive, presentationId corrisponde all'ID della risorsa File.
Le pagine e gli elementi di pagina sono identificati da ID oggetto.
Pages
Presentazioni Google include i seguenti tipi di pagine:
| Master | Gli schemi delle slide definiscono gli stili di testo predefiniti, lo sfondo e gli elementi di pagina che vengono visualizzati in tutte le slide che utilizzano lo schema. Gli elementi di pagina che devono essere visualizzati in tutte le slide devono essere aggiunti allo schema. La maggior parte delle presentazioni ha un unico schema, ma alcune possono averne diversi o nessuno. |
| Layout | I layout fungono da modello per la disposizione predefinita degli elementi della pagina nelle slide che utilizzano un layout. Ogni layout è associato a un master. |
| Slide | Queste pagine includono i contenuti che stai presentando al tuo pubblico. La maggior parte delle slide si basa su uno schema e un layout. Puoi specificare il layout da utilizzare per ogni slide al momento della creazione. |
| Note | Queste pagine includono i contenuti per i documenti stampabili della presentazione, tra cui una forma che contiene le note del relatore della slide. Ogni slide ha una pagina di note corrispondente. Solo il testo nella forma delle note del relatore può essere modificato con l'API Presentazioni. |
| Schemi delle note | Gli schemi delle note definiscono gli stili di testo e gli elementi di pagina predefiniti di tutte le pagine delle note. I master Notes sono di sola lettura nell'API Presentazioni. |
Elementi pagina
Gli elementi di pagina sono i componenti visivi che vengono 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, ridimensionati e ruotati insieme. |
| Shape | Un oggetto visivo semplice, ad esempio rettangoli, ellissi e caselle di testo. Le forme possono contenere testo, pertanto sono gli elementi di pagina più comuni per la creazione di slide. |
| Immagine | Un'immagine importata in Presentazioni. |
| Video | Un video importato in Presentazioni. |
| A linee | Una linea visiva, una curva o un connettore. |
| 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 collettivi
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 accetta uno o più oggetti Request, ciascuno dei quali specifica un singolo tipo di richiesta da eseguire. Esistono tanti tipi diversi di richieste. Ecco un'analisi dei tipi di richieste,
raggruppate 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 nell'indice sarà vuota. Di solito le varie richieste Create hanno risposte, pertanto conosci l'ID dell'oggetto appena aggiunto.
Utilizzare gli ID oggetto
Una presentazione nell'API Presentazioni è composta da pagine ed elementi di pagina. Questi oggetti includono una stringa ID oggetto univoca all'interno di una presentazione.
Specificare gli ID oggetto al momento della creazione
Quando crei pagine o elementi di pagina con il metodo batchUpdate, puoi facoltativamente specificare un ID oggetto per il nuovo oggetto. Ciò consente di creare un oggetto e di modificarlo all'interno della stessa richiesta batchUpdate, riducendo al minimo il numero di chiamate all'API Presentazioni e riducendo l'utilizzo della quota.
Consigliamo di generare un ID oggetto casuale nella maggior parte dei casi. Ad esempio, se
utilizzi Java, java.util.UUID.randomUUID().toString() dovrebbe funzionare correttamente.
Se l'applicazione vuole tenere traccia degli oggetti per un periodo di tempo più lungo, non fare affidamento sull'ID oggetto, perché potrebbe cambiare. Per ulteriori dettagli, consulta la sezione seguente.
Tenere traccia degli oggetti senza utilizzare l'ID oggetto
Quando effettui una richiesta all'API Presentazioni, l'ID oggetto viene normalmente conservato. (Eventuali eccezioni sono indicate nella documentazione di riferimento del metodo.) Anche la creazione di una copia di un'intera presentazione con l'API Drive consente di conservare gli ID oggetto.
Tuttavia, non puoi dipendere dal fatto che un ID oggetto rimanga invariato dopo la modifica di una presentazione nell'interfaccia utente di Presentazioni. Ad esempio, se un utente utilizza l'interfaccia utente di Presentazioni per copiare e incollare un elemento di pagina e poi elimina l'originale, l'elemento di pagina avrà ora un nuovo ID univoco e l'ID fornito in precedenza tramite l'API andrà perso. Di conseguenza, non è consigliabile archiviare gli ID oggetto nello spazio di archiviazione dell'applicazione. Dovresti trovare gli oggetti nella presentazione in base ai suoi contenuti testuali o testo alternativo.
Le nuove presentazioni create di solito utilizzano un set coerente di ID per slide, schemi e caselle di testo predefiniti. Questi ID sono soggetti a modifiche nel tempo, pertanto ti consigliamo di non utilizzare questa funzione. Cerca invece gli elementi che vuoi modificare utilizzando l'oggetto Presentation restituito dalle chiamate a create() o get().