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