מבוא

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

מרכיבי דף

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

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

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