בקשות אצווה

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

סקירה כללית

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

אנחנו ממליצים למשתמשים לקבץ יחד בקשות מרובות. ריכזנו כאן כמה דוגמאות למצבים שבהם אפשר להשתמש בקיבוץ:

• התחלתם להשתמש ב-API ויש לכם המון נתונים להעלאה.
• צריך לעדכן מטא-נתונים או מאפיינים, כמו עיצוב, באובייקטים מרובים.
• עליך למחוק אובייקטים רבים.

שיקולים בנוגע למגבלות, להרשאות ולתלות

לפניכם רשימה של פריטים אחרים שכדאי לקחת בחשבון כשמשתמשים בעדכון בכמות גדולה:

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

פרטי אצווה

בקשה באצווה מורכבת מקריאה אחת ל-method batchUpdate עם מספר בקשות משנה, למשל להוספה ולעיצוב של מצגת.

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

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

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

הפורמט של בקשה באצווה

בקשה היא בקשת JSON יחידה שמכילה מספר בקשות משנה מקננות עם נכס נדרש אחד: requests. הבקשות נוצרות במערך של בקשות נפרדות. בכל בקשה נעשה שימוש ב-JSON כדי לייצג את אובייקט הבקשה ולהכיל את המאפיינים שלו.

הפורמט של תשובות באצווה

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

המאפיין של אובייקט ה-JSON הראשי נקרא replies. התשובות מוחזרות במערך, כשכל תגובה לאחת מהבקשות מקבלת את אותו סדר אינדקס של הבקשה התואמת. לחלק מהבקשות אין תגובות, והתגובה באינדקס המערך הזה ריקה.

דוגמה

בדוגמת הקוד הבאה אפשר לראות את השימוש בקיבוץ ב-Slides באמצעות ה-API.

בקשה

הבקשה באצווה לדוגמה מדגימה איך:

• הוספת משאב presentations.pages למצגת קיימת עם insertionIndex של 1 באמצעות method CreateSlideRequest.

• מוסיפים shapeType מסוג TEXT_BOX לשקף החדש באמצעות method CreateShapeRequest.

• מזינים את הטקסט Hello World לשדה החדש באמצעות method InsertTextRequest.

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

תשובה

בדוגמה הזו מוצג מידע על האופן שבו הוחלה כל בקשת משנה בתוך בקשת האצווה. שימו לב שהשיטה InsertTextRequest לא מכילה תגובה, ולכן ערך האינדקס של המערך ב-[2] יכלול סוגריים מסולסלים ריקים. הבקשה באצווה מציגה את המאפיין WriteControl, שמראה איך בקשות הכתיבה בוצעו.

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}