Google Slides API מאפשר ליצור ולשנות מצגות ב-Google Slides.
אפשר לשלב אפליקציות עם ה-API של Google Slides כדי ליצור באופן אוטומטי תבניות יפהפיות של שקפים מנתונים שהמשתמשים סיפקו והמערכת. לדוגמה, אפשר להשתמש בפרטי לקוחות ממסד נתונים ולשלב אותם עם תבניות מעוצבות מראש ואפשרויות הגדרה נבחרות כדי ליצור מצגות מוכנות תוך שבריר מהזמן שנדרש כדי ליצור אותן באופן ידני.
סקירה כללית של ה-API
אוסף המצגות מספק שיטות שמאפשרות לקבל ולעדכן רכיבים במצגת.
רוב העבודה שלכם עם ה-API של Slides היא יצירה ועדכון של מצגות. אפשר לעשות זאת באמצעות ה-method batchUpdate. השיטה הזו יוצרת רשימה של אובייקטים מסוג Request שמאפשרים לבצע פעולות כמו:
- יצירת שקפים
- להוסיף רכיבים לשקפים, כמו צורות או טבלאות
- הוספה, שינוי והסרה של טקסט
- החילו התמרות על יסודות
- שינוי סדר השקפים
לפרטים נוספים, ראו עדכונים באצווה. במדריכים לתחילת העבודה תמצאו דוגמה פשוטה לשימוש ב-API.
המבנה של מצגת
מצגת ב-API של Slides מורכבת מדפים, שכוללים אלמנטים של דפים.
ניתן לגזור את מזהה המצגת מכתובת ה-URL:
https://docs.google.com/presentation/d/presentationId/edit
מזהה המצגת הוא מחרוזת שמכילה אותיות, מספרים וכמה תווים מיוחדים. אפשר להשתמש בביטוי הרגולרי הבא כדי לחלץ את מזהה המצגת מכתובת URL ב-Google Sheets:
/presentation/d/([a-zA-Z0-9-_]+)
אם אתם מכירים את Drive API, ה-presentationId תואם למזהה של המשאב File.
דפים ורכיבי דפים מזוהים באמצעות מזהי אובייקטים.
iWork Pages
ב-Google Slides קיימים סוגי הדפים הבאים:
| תואר שני | המאסטרים של השקפים מגדירים את סגנונות ברירת המחדל של הטקסט, את הרקע ואת רכיבי הדף שמופיעים בכל השקפים שמשתמשים במאסטר הזה. את רכיבי הדף שחייבים להופיע בכל השקפים צריך להוסיף למאסטר. לרוב המצגות יש מאסטר אחד, אבל לחלקן יש כמה מצגות או ללא מאסטר. |
| פריסות | פריסות משמשות כתבנית לאופן שבו רכיבי הדף יאורגנו כברירת מחדל בשקפים באמצעות פריסה. כל פריסה משויכת למאסטר אחד. |
| מגלשות | הדפים האלה מכילים את התוכן שאתם מציגים לקהל. רוב השקפים מבוססים על מאסטר ופריסה. תוכלו לציין באיזו פריסה להשתמש בכל שקף בזמן יצירתו. |
| הערות | הדפים האלה מכילים את התוכן של דפי הפירוט למצגות, כולל צורה שמכילה את הערות הדובר בשקף. לכל שקף יש דף הערות תואם אחד. אפשר לשנות רק את הטקסט שמופיע בצורה של הערות הדובר באמצעות ה-API של Slides. |
| מאסטרים לפתקים | המאסטרים של ההערות מגדירים את ברירת המחדל של סגנונות הטקסט ואת רכיבי הדף בכל דפי ההערות. המאסטרים של ההערות מוגדרים לקריאה בלבד ב-Slides API. |
רכיבי הדף
רכיבי דף הם הרכיבים החזותיים שממוקמים בדפים. ה-API חושף כמה סוגים של אלמנטים בדף:
| קבוצה | קבוצה של רכיבי דף שנחשבים כיחידה בודדת. אפשר להזיז אותם, לשנות את הגודל שלהם ולסובב אותם יחד. |
| צורה | אובייקט חזותי פשוט, כמו מלבנים, אליפסות ותיבות טקסט. צורות יכולות להכיל טקסט, ולכן הן רכיבי הדף הנפוצים ביותר לבניית שקפים. |
| תמונה | גרפיקה יובאה אל Slides. |
| וידאו | סרטון יובא אל Slides. |
| קו | קו חזותי, עקומה או מחבר. |
| טבלה | רשת של תוכן. |
| WordArt | רכיב טקסט חזותי שמתנהג יותר כמו צורה. |
| SheetsChart | תרשים שיובא ל-Slides מ-Google Sheets. |
עדכונים בכמות גדולה
השיטה batchUpdate מאפשרת לעדכן היבטים רבים במצגת. השינויים מקובצים יחד בקבוצה, כך שאם בקשה אחת נכשלת, לא נכתב אף שינוי אחר (שעשוי להיות תלוי).
ה-method batchUpdate משתמשת באובייקט Request (בקשה) אחד או יותר, שכל אחד מהם מציין סוג אחד של בקשה לביצוע. יש הרבה סוגים שונים של בקשות. כאן מופיע פירוט של סוגי הבקשות שמקובצים לקטגוריות שונות.
ה-method batchUpdate מחזירה גוף תשובה, שמכיל Response לכל בקשה. כל תגובה מכילה את אותו אינדקס כמו הבקשה התואמת. בבקשות שאין להן תגובה רלוונטית, התגובה באינדקס הזה תהיה ריקה. בדרך כלל, לבקשות Create השונות יש תשובות, כך שאפשר לדעת מה המזהה של האובייקט החדש שנוסף.
עבודה עם מזהי אובייקטים
מצגת ב-API של Slides מורכבת מדפים ומרכיבי דפים. האובייקטים האלה כוללים מחרוזת מזהה אובייקט ייחודית במצגת.
ציון מזהי אובייקטים בזמן היצירה
כשיוצרים דפים או רכיבי דף באמצעות method batchUpdate, אפשר לציין מזהה אובייקט לאובייקט החדש. כך אפשר ליצור אובייקט ולשנות אותו באותה בקשת עדכון באצווה, וכך לצמצם את מספר הקריאות ל-API של Slides והשימוש במכסות.
ברוב המקרים מומלץ ליצור מזהה אובייקט אקראי. לדוגמה, אם אתם משתמשים ב-Java, הקוד java.util.UUID.randomUUID().toString() אמור לפעול כמו שצריך.
אם האפליקציה רוצה לעקוב אחרי אובייקטים לאורך תקופת זמן ארוכה יותר, לא כדאי להסתמך על מזהה האובייקט כי הוא עשוי להשתנות. פרטים נוספים מופיעים בקטע הבא.
מעקב אחרי אובייקטים בלי להשתמש במזהה האובייקט
כששולחים בקשת API ל-Slides, מזהה האובייקט נשמר בדרך כלל. (מקרים חריגים מצוינים במסמכי העזר של השיטה). כשיוצרים עותק של מצגת שלמה באמצעות Drive API, גם מזהי האובייקטים נשמרים.
עם זאת, אי אפשר להסתמך על כך שמזהה אובייקט לא ישתנה אחרי שמשנים מצגת בממשק המשתמש של Slides. לדוגמה, אם מישהו השתמש בממשק המשתמש של Slides כדי להעתיק ולהדביק רכיב דף ואז מוחק את המקור, לרכיב הדף יהיה מזהה ייחודי חדש, והמזהה שסיפקתם בעבר דרך ה-API יאבד. לכן לא מומלץ לשמור מזהי אובייקטים באחסון של האפליקציה. במקום זאת, כדאי למצוא אובייקטים במצגת לפי תוכן הטקסט או הטקסט החלופי שלה.
במצגות חדשות, בדרך כלל משתמשים בקבוצה עקבית של מזהים לשקפים שמוגדרים כברירת מחדל, למאסטרים ולתיבות טקסט. המזהים האלה עשויים להשתנות עם הזמן, ולכן לא מומלץ להשתמש בתכונה הזו. במקום זאת, תוכלו למצוא את הרכיבים שרוצים לשנות באמצעות אובייקט המצגת שמוחזר על ידי קריאות ל-create() או ל-get().