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 file di presentazioni di alta qualità 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 finite in una frazione del tempo necessario per crearle manualmente.
Panoramica dell'API
La raccolta presentations fornisce metodi che consentono di ottenere 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, utilizza il metodo batchUpdate; questo metodo accetta un elenco di oggetti Request che ti consentono di eseguire operazioni come:
- 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, vedi Aggiornamenti batch. 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 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, presentationId
corrisponde all'ID della
risorsa File.
Le pagine e gli elementi della pagina sono identificati da ID oggetto.
Pagine
Google Slides ha i seguenti tipi di pagine:
| Master | I modelli di slide definiscono gli stili di testo, lo sfondo e gli elementi della pagina predefiniti che vengono visualizzati in tutte le slide che utilizzano questo modello. Gli elementi della pagina che devono essere visualizzati in tutte le slide devono essere aggiunti alla slide master. La maggior parte delle presentazioni ha un solo master, 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 una pagina master. |
| Presentazioni | Queste pagine contengono i contenuti che presenti al tuo pubblico. La maggior parte delle slide si basa su una slide master e un layout. Puoi specificare quale layout utilizzare per ogni slide al momento della creazione. |
| Note | Queste pagine contengono i contenuti per i materiali di presentazione, inclusa una forma che contiene le note del relatore della slide. Ogni slide ha una pagina delle note corrispondente. Solo il testo nella forma delle note del relatore può essere modificato con l'API Slides. |
| Note principali | I master delle note definiscono gli stili di testo e gli elementi della pagina predefiniti per tutte le pagine delle 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 che vengono 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 le slide. |
| 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
molti tipi diversi di richieste. Ecco una suddivisione dei tipi di richieste,
raggruppate in diverse categorie.
Il metodo batchUpdate restituisce un corpo della risposta,
che contiene una
Response
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 normalmente 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 della pagina. Questi oggetti includono una stringa ID oggetto univoca all'interno di una presentazione.
Specifica degli ID oggetto durante la creazione
Quando crei pagine o elementi di pagina utilizzando il metodo
batchUpdate, puoi specificare facoltativamente 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 diminuendo 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.
Quando 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.
Monitorare gli oggetti senza utilizzare l'ID oggetto
Quando effettui una richiesta all'API Slides, l'ID oggetto viene normalmente preservato. Eventuali eccezioni sono indicate nella documentazione di riferimento del metodo. La creazione di una copia di un'intera presentazione con l'API Drive conserva anche gli ID oggetto.
Tuttavia, non puoi fare affidamento su un ID oggetto che rimane invariato dopo che una presentazione viene modificata nell'interfaccia utente di Presentazioni. Ad esempio, se qualcuno utilizza l'interfaccia utente di Presentazioni per copiare e incollare un elemento della pagina ed 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, non ti consigliamo di archiviare gli ID oggetto nello spazio di archiviazione della tua applicazione. Invece, dovresti trovare gli oggetti nella presentazione in base al contenuto di testo o al testo alternativo.
Le presentazioni appena create utilizzano in genere un insieme coerente di ID per le slide, i master e le caselle di testo predefiniti. Questi ID sono soggetti a modifiche nel tempo, quindi ti 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().