בקשות באצווה

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

בדוגמת הקוד הבאה אפשר לראות איך משתמשים ב-batching עם Slides API.

בקשה

בדוגמה הזו לבקשת Batch אפשר לראות איך:

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

תשובה

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

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