מבוא

Google Slides API מאפשר ליצור ולשנות מצגות ב-Google Slides.

אפשר לשלב את האפליקציות עם Google Slides API כדי ליצור באופן אוטומטי מצגות יפהפיות מנתונים שהמשתמשים או המערכת סיפקו. לדוגמה, אפשר להשתמש בפרטי לקוח ממסד נתונים ולשלב אותם עם תבניות שעוצבו מראש ואפשרויות הגדרה נבחרות כדי ליצור מצגות שלמות תוך חלק קטן מהזמן שייקח ליצור אותן באופן ידני.

סקירה כללית על ה-API

באוסף מצגות יש שיטות שמאפשרות לקבל ולעדכן רכיבים במצגת.

סביר להניח שרוב העבודה עם ה-API של Slides היא יצירה ועדכון של מצגות. ניתן לעשות זאת באמצעות השיטה 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.

דפים ורכיבים של דפים מזוהים באמצעות מזהי אובייקטים.

דפים

ב-Google Slides קיימים סוגי הדפים הבאים:

תואר שני ראשי שקפים מגדירים את ברירת המחדל של סגנונות הטקסט, הרקע ורכיבי הדף שיופיעו בכל השקפים שמשתמשים במאסטר הזה. יש להוסיף למאסטר את רכיבי הדף שחייבים להופיע בכל השקפים. לרוב המצגות יש מאסטר אחד, אבל לחלקן יש כמה מצגות או אין מאסטרים.
פריסות הפריסות משמשות כתבנית לאופן שבו רכיבי הדף יאורגנו כברירת מחדל בשקפים באמצעות פריסה. כל פריסה משויכת למאסטר אחד.
מגלשות הדפים האלה מכילים את התוכן שאתם מציגים לקהל שלכם. רוב השקפים מבוססים על תבנית ראשית ופריסה. אפשר לציין באיזו פריסה רוצים להשתמש בכל שקף כשיוצרים אותו.
הערות הדפים האלה מכילים את התוכן של דפי המידע במצגות, כולל צורה שמכילה את הערות הדובר בשקף. לכל שקף יש דף הערות תואם אחד. ב-Slides API אפשר לשנות רק את הטקסט שבצורה של הערות הדובר.
מאסטרים של הערות המאסטרים של ההערות מגדירים את סגנונות הטקסט ואת רכיבי הדפים שמוגדרים כברירת מחדל בכל דפי ההערות. המאסטרים של הפתקים זמינים לקריאה בלבד ב-Slides API.

רכיבי הדף

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

קבוצה קבוצה של אלמנטים בדף שנחשבים כיחידה בודדת. אפשר להזיז, לשנות את הגודל ולסובב אותם יחד.
צורה אובייקט חזותי פשוט, כמו מלבנים, שלוש נקודות ותיבות טקסט. צורות יכולות להכיל טקסט, ולכן הם הרכיבים הנפוצים ביותר בדף ליצירה של שקפים.
תמונה פריט גרפי שיובא אל Slides.
וידאו סרטון שיובא אל Slides.
קו קו חזותי, עקומה או מחבר.
טבלה רשת של תוכן.
WordArt רכיב טקסט חזותי שמתנהג יותר כמו צורה.
SheetsChart תרשים שיובא מ-Google Sheets ל-Slides.

עדכונים בכמות גדולה

השיטה batchUpdate מאפשרת לעדכן היבטים רבים במצגת. השינויים מקובצים יחד באצווה, כך שאם בקשה אחת נכשלת, אף אחד מהשינויים האחרים (שעשויים להיות תלויים) לא נכתב.

השיטה batchUpdate פועלת באמצעות אובייקט Request אחד או יותר, כאשר כל אחד מהם מציין סוג אחד של בקשה לביצוע. יש סוגים רבים של בקשות. לפניכם פירוט של סוגי הבקשות, בחלוקה לקטגוריות שונות.

עבודה עם Slides: CreateSlideRequest
UpdateSlidesPositionRequest
DuplicateObjectRequest
UpdatePagePropertiesRequest
DeleteObjectRequest
עבודה עם רכיבי דף: CreateShapeRequest
CreateLineRequest
UpdatePageElementTransformRequest
UpdateShapePropertiesRequest
DuplicateObjectRequest
DeleteObjectRequest
עבודה עם טבלאות: CreateTableRequest
InsertTableRowsRequest
InsertTableColumnsRequest
DeleteTableRowRequest
DeleteTableColumnRequest
UpdateTableRowPropertiesRequest
UpdateTableColumnPropertiesRequest
UpdateTableBorderPropertiesRequest
UpdateTableCellPropertiesRequest
MergeTableCellsRequest
UnmergeTableCellsRequest
DeleteObjectRequest
עבודה עם תרשימים: CreateSheetsChartRequest
RefreshSheetsChartRequest
ReplaceAllShapesWithSheetsChartRequest
DeleteObjectRequest
עבודה עם תמונות וסרטונים: CreateImageRequest
CreateVideoRequest
UpdateImagePropertiesRequest
UpdateVideoPropertiesRequest
ReplaceAllShapesWithImageRequest
DuplicateObjectRequest
DeleteObjectRequest
עבודה עם טקסט: InsertTextRequest
DeleteTextRequest
ReplaceAllTextRequest
CreateParagraphBulletsRequest
DeleteParagraphBulletsRequest
UpdateTextStyleRequest
UpdateParagraphStyleRequest

השיטה batchUpdate מחזירה גוף התגובה, שמכיל תגובה לכל בקשה. לכל תגובה יהיה אינדקס שזהה לאינדקס של הבקשה התואמת. בבקשות שאין להן תגובה רלוונטית, התשובה באינדקס הזה תהיה ריקה. בדרך כלל, לבקשות Create השונות מתקבלות תשובות, כך שאתם יודעים את המזהה של האובייקט החדש שנוסף.

עבודה עם מזהי אובייקטים

מצגת ב-Slides API מורכבת מדפים ומרכיבי דפים. האובייקטים האלה כוללים מחרוזת object ID שייחודית בתוך מצגת.

ציון מזהי אובייקטים במהלך היצירה

כשיוצרים דפים או אלמנטים בדף באמצעות השיטה batchUpdate, אפשר לציין מזהה אובייקט עבור האובייקט החדש. כך אפשר ליצור אובייקט ולשנות אותו באותה בקשת BundleUpdate, וכך לצמצם את מספר הקריאות ל-Slides API ולצמצם את השימוש במכסה.

ברוב המקרים מומלץ ליצור מזהה אובייקט אקראי. לדוגמה, אם אתם משתמשים ב-Java, java.util.UUID.randomUUID().toString() אמור לפעול היטב.

אם אתם רוצים לעקוב אחרי אובייקטים למשך פרק זמן ארוך יותר, אל תסתמכו על מזהה האובייקט כי הוא עשוי להשתנות. תוכלו לקרוא פרטים נוספים בקטע הבא.

מעקב אחר אובייקטים בלי להשתמש במזהה האובייקט

כששולחים בקשת API ל-Slides, מזהה האובייקט נשמר בדרך כלל. (כל החריגים מצוינים במסמכי התיעוד של השיטה). כשיוצרים עותק של מצגת שלמה באמצעות Drive API, אפשר לשמור גם מזהי אובייקטים.

עם זאת, לא ניתן להסתמך על כך שמזהה אובייקט לא ישתנה לאחר שינוי של מצגת בממשק המשתמש של Slides. לדוגמה, אם מישהו משתמש בממשק המשתמש של Slides כדי להעתיק ולהדביק רכיב בדף, ואז מוחק את הרכיב המקורי, לרכיב הדף יהיה מזהה ייחודי חדש, והמזהה שסיפקתם בעבר דרך ה-API יאבד. לכן, לא מומלץ לשמור מזהי אובייקטים באחסון של האפליקציה. במקום זאת, צריך לחפש אובייקטים במצגת לפי תוכן הטקסט או הטקסט החלופי.

במצגות חדשות, בדרך כלל נעשה שימוש בקבוצה עקבית של מזהים בברירת המחדל של שקפים, מאסטרים ותיבות טקסט. המזהים האלה עשויים להשתנות עם הזמן, ולכן לא מומלץ להסתמך על התכונה הזו. במקום זאת, אפשר למצוא את הרכיבים שרוצים לשנות באמצעות אובייקט המצגת שהוחזר על ידי הקריאות ל-create() או ל-get().