בקשות אצווה

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

סקירה

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

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

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

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

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

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

פירוט לגבי בקשות באצווה

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

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

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

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

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

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

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

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

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

דוגמה

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

בקשה

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

{
   "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"
         }
      }
   ]
}

תשובה

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

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