מבוא

באמצעות 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 יש את סוגי הדפים הבאים:

רכיבי דף

רכיבי הדף הם הרכיבים החזותיים שממוקמים בדפים. ה-API חושף כמה סוגים של רכיבי דף:

עדכונים באצווה

השיטה 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()‎.