L'API Google Slides consente di creare e modificare presentazioni di Presentazioni Google.
Le app possono integrarsi con l'API Google Slides per creare automaticamente presentazioni di slide accattivanti a partire dai dati forniti dall'utente e dal sistema. Ad esempio, potresti 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 di presentazioni fornisce metodi che consentono di recuperare e aggiornare gli elementi all'interno della presentazione.
La maggior parte del lavoro con l'API Slides probabilmente consisterà nella creazione e nell'aggiornamento delle presentazioni. Per farlo, utilizzerai il metodo batchUpdate; questo metodo accetta un elenco di oggetti Request che ti consentono di eseguire operazioni come:
- Creare slide
- Aggiungere elementi alle slide, ad esempio forme o tabelle
- Inserire, modificare e rimuovere testo
- Applicare trasformazioni agli elementi
- Modificare l'ordine delle slide
Per ulteriori dettagli, consulta Aggiornamenti batch. Per un semplice esempio end-to-end di come utilizzare l'API, consulta le guide introduttive.
Struttura di una presentazione
Una presentazione nell'API Slides è composta da pagine, che contengono elementi della pagina.
L'ID di una presentazione può essere derivato 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, il presentationId
corrisponde all'ID della
risorsa
File.
Le pagine e gli elementi della pagina sono identificati dagli ID oggetto.
Pagine
Presentazioni Google ha i seguenti tipi di pagine:
| Master | I master delle slide definiscono gli stili di testo, lo sfondo e gli elementi della pagina predefiniti che vengono visualizzati in tutte le slide che utilizzano questo master. Gli elementi della pagina che devono essere visualizzati su tutte le slide devono essere aggiunti al master. La maggior parte delle presentazioni ha un master, ma alcune possono averne diversi o nessuno. |
| Layout | I layout fungono da modello per la disposizione predefinita degli elementi della pagina sulle slide che utilizzano un layout. Ogni layout è associato a un master. |
| Slide | Queste pagine contengono i contenuti che stai presentando al tuo pubblico. La maggior parte delle slide si basa su un master e un layout. Puoi specificare il layout da utilizzare per ogni slide al momento della creazione. |
| Note | Queste pagine contengono i contenuti per i materiali della presentazione, inclusa una una forma che contiene le note del relatore della slide. Ogni slide ha una pagina di note corrispondente. Con l'API Slides è possibile modificare solo il testo nella forma delle note del relatore. |
| Master delle note | I master delle note definiscono gli stili di testo e gli elementi della pagina predefiniti per tutte le pagine di note. I master delle note sono di sola lettura nell'API Slides. |
Elementi pagina
Gli elementi della pagina sono i componenti visivi posizionati sulle pagine. L'API espone diversi tipi di elementi della pagina:
| Gruppo | Un insieme di elementi della pagina trattati come una singola unità. Possono essere spostati, scalati e ruotati insieme. |
| Forma | Un oggetto visivo semplice, come rettangoli, ellissi e caselle di testo. Le forme possono contenere testo, quindi sono gli elementi della pagina più comuni per creare slide. |
| Immagine | Un elemento grafico importato 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, non vengano scritte le altre modifiche (potenzialmente dipendenti).
Il metodo batchUpdate funziona accettando uno o più
Request
oggetti, ognuno dei quali specifica un singolo tipo di richiesta da eseguire. Esistono molti tipi diversi di richieste. Ecco una suddivisione dei tipi di richieste, raggruppate in categorie diverse.
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 a quell'indice sarà vuota. Le varie richieste Create in genere hanno risposte, in modo che tu conosca l'ID dell'oggetto appena aggiunto.
Utilizzo degli ID oggetto
Una presentazione nell'API Slides è composta da pagine ed elementi della 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 della pagina utilizzando il
batchUpdate, puoi facoltativamente 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 Slides e riducendo
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 correttamente.
Se la tua 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 invii una richiesta all'API Slides, l'ID oggetto viene normalmente mantenuto. (Eventuali eccezioni sono indicate nella documentazione di riferimento del metodo.) Anche la creazione di una copia di un'intera presentazione con l'API Drive mantiene gli ID oggetto.
Tuttavia, non puoi fare affidamento sul fatto che un ID oggetto rimanga invariato 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 che hai fornito in precedenza tramite l'API andrà perso. Di conseguenza, ti sconsigliamo di archiviare gli ID oggetto nello spazio di archiviazione della tua applicazione. In alternativa, devi trovare gli oggetti nella presentazione in base al contenuto del testo o al testo alternativo.
Le presentazioni appena create in genere utilizzano un insieme coerente di ID per slide, master e caselle di testo predefiniti. Questi ID sono soggetti a modifiche nel tempo, pertanto ti sconsigliamo di fare affidamento su questa funzionalità. In alternativa, trova gli elementi che vuoi modificare utilizzando l'oggetto presentazione restituito dalle chiamate a create() o get().