בעזרת Google Slides API אפשר ליצור ולשנות מצגות ב-Google Slides.
אפליקציות יכולות להשתלב עם Google Slides API כדי ליצור באופן אוטומטי מצגות יפות על סמך נתונים שהמשתמשים והמערכת מספקים. לדוגמה, אפשר להשתמש בפרטי לקוחות ממסד נתונים ולשלב אותם עם תבניות מוכנות מראש ואפשרויות הגדרה נבחרות כדי ליצור מצגות מוכנות בזמן קצר בהרבה ממה שיידרש ליצירה ידנית.
סקירה כללית על API
אוסף המצגות מספק שיטות שמאפשרות לקבל ולעדכן אלמנטים במצגת.
ברוב המקרים, העבודה עם Slides API תתמקד ביצירה ובעדכון של מצגות. כדי לעשות זאת, משתמשים בשיטה batchUpdate. השיטה הזו מקבלת רשימה של אובייקטים מסוג Request, שמאפשרים לבצע פעולות כמו:
- יצירת שקפים
- הוספת רכיבים לשקפים כמו צורות או טבלאות
- הוספה, שינוי והסרה של טקסט
- החלת טרנספורמציות על רכיבים
- שינוי סדר השקפים
פרטים נוספים זמינים במאמר בנושא עדכונים בכמות גדולה. במדריכים למתחילים מופיעה דוגמה פשוטה מקצה לקצה לשימוש ב-API.
המבנה של מצגת
מצגת ב-Slides API מורכבת מדפים שמכילים רכיבי דף.
אפשר להסיק את מזהה המצגת מכתובת ה-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 יש את סוגי הדפים הבאים:
| תואר שני | שקופיות ראשיות מגדירות את סגנונות הטקסט, הרקע והאלמנטים של הדף שמופיעים בכל השקופיות שמשתמשות בשקופית הראשית הזו. צריך להוסיף לתבנית הבסיסית את רכיבי הדף שחייבים להופיע בכל השקפים. לרוב המצגות יש שקף ראשי אחד, אבל לחלקן יש כמה שקפים ראשיים או אף אחד. |
| פריסות | פריסות משמשות כתבנית לאופן שבו רכיבי הדף יסודרו כברירת מחדל בשקפים שמשתמשים בפריסה. כל פריסה משויכת לתבנית בסיסית אחת. |
| סליידים | הדפים האלה מכילים את התוכן שאתם מציגים לקהל. רוב השקפים מבוססים על שקף ראשי ועל פריסה. אתם יכולים לציין באיזה פריסה להשתמש לכל שקף כשיוצרים אותו. |
| הערות | הדפים האלה מכילים את התוכן של דפי מידע על המצגת, כולל צורה שמכילה את הערות הדובר של השקף. לכל שקף יש דף הערות תואם. אפשר לשנות באמצעות Slides API רק את הטקסט בצורת הערות הדובר. |
| שקפים ראשיים של הערות | שקופיות אב של הערות מגדירות את סגנונות הטקסט ורכיבי הדף שמוגדרים כברירת מחדל לכל דפי ההערות. הערות ראשיות הן לקריאה בלבד ב-Slides API. |
מרכיבי דף
רכיבי דף הם הרכיבים החזותיים שמוצבים בדפים. ה-API חושף כמה סוגים של רכיבי דף:
| קבוצה | קבוצה של רכיבי דף שמטופלים כיחידה אחת. אפשר להזיז, לשנות את הגודל ולסובב אותם יחד. |
| צורה | אובייקט ויזואלי פשוט, כמו מלבנים, אליפסות ותיבות טקסט. צורות יכולות להכיל טקסט, ולכן הן הרכיבים הנפוצים ביותר בדף ליצירת שקפים. |
| תמונה | גרפיקה שיובאה ל-Slides. |
| וידאו | סרטון שיובא ל-Slides. |
| קו | קו, עקומה או מחבר חזותי. |
| טבלה | רשת של תוכן. |
| WordArt | רכיב טקסט ויזואלי שמתנהג יותר כמו צורה. |
| SheetsChart | תרשים שיובא ל-Slides מ-Google Sheets. |
עדכונים באצווה
השיטה batchUpdate מאפשרת לעדכן הרבה היבטים של מצגת. השינויים מקובצים יחד בחבילה, כך שאם בקשה אחת נכשלת, אף אחד מהשינויים האחרים (שיכול להיות שהם תלויים בה) לא נכתב.
השיטה batchUpdate פועלת על ידי קבלת אובייקט Request אחד או יותר, שכל אחד מהם מציין סוג בקשה יחיד לביצוע. יש סוגים רבים ושונים של בקשות. לפניכם פירוט של סוגי הבקשות, שמחולקות לקטגוריות שונות.
ה-method batchUpdate מחזיר response body, שמכיל Response לכל בקשה. כל תגובה תופסת את אותו אינדקס כמו הבקשה המתאימה. אם אין תגובה רלוונטית לבקשה, התגובה באינדקס הזה תהיה ריקה. בדרך כלל יש תשובות לבקשות השונות של Create, כך שתוכלו לדעת את המזהה של האובייקט החדש שנוסף.
עבודה עם מזהי אובייקטים
מצגת ב-Slides API מורכבת מדפים ומרכיבי דף. האובייקטים האלה כוללים מחרוזת של מזהה אובייקט שהיא ייחודית במצגת.
ציון מזהי אובייקטים בזמן היצירה
כשיוצרים דפים או רכיבי דף באמצעות השיטה batchUpdate, אפשר לציין מזהה אובייקט לאובייקט החדש. כך אפשר ליצור אובייקט ולשנות אותו באותה בקשת batchUpdate, לצמצם את מספר הקריאות ל-Slides API ולהקטין את
השימוש במכסה.
ברוב המקרים מומלץ ליצור מזהה אובייקט אקראי. לדוגמה, אם משתמשים ב-Java, הפקודה java.util.UUID.randomUUID().toString() אמורה לפעול היטב.
אם האפליקציה שלכם רוצה לעקוב אחרי אובייקטים לאורך זמן, אל תסתמכו על מזהה האובייקט, כי הוא עשוי להשתנות. פרטים נוספים מופיעים בקטע הבא.
מעקב אחרי אובייקטים בלי להשתמש במזהה האובייקט
כששולחים בקשה ל-Slides API, מזהה האובייקט נשמר בדרך כלל. (חריגים מפורטים במסמכי העיון של השיטה). כשיוצרים עותק של מצגת שלמה באמצעות Drive API, מזהי האובייקטים נשמרים.
עם זאת, אי אפשר להסתמך על כך שמזהה אובייקט לא ישתנה אחרי שינוי של מצגת בממשק המשתמש של Slides. לדוגמה, אם מישהו משתמש בממשק המשתמש של Slides כדי להעתיק ולהדביק רכיב בדף ואז מוחק את המקור, לרכיב בדף יהיה עכשיו מזהה ייחודי חדש, והמזהה שסיפקתם קודם דרך ה-API יאבד. לכן, לא מומלץ לאחסן מזהי אובייקטים באחסון של האפליקציה. במקום זאת, צריך לחפש אובייקטים במצגת לפי תוכן הטקסט או הטקסט החלופי שלהם.
בדרך כלל, מצגות חדשות שנוצרות משתמשות במערכת עקבית של מזהים לשקפים, לתבניות ולתיבות טקסט שמוגדרים כברירת מחדל. יכול להיות שהמזהים האלה ישתנו עם הזמן, ולכן אנחנו לא ממליצים להסתמך על התכונה הזו. במקום זאת, צריך למצוא את הרכיבים שרוצים לשנות באמצעות אובייקט המצגת שמוחזר על ידי קריאות ל-create() או ל-get().