בקשות אצווה

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

בדוגמת הקוד הבאה מוצגת שימוש בצבירה עם API של Google Slides.

בקשה

בבקשת האצווה הזו מוצגים השלבים הבאים:

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

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

• מוסיפים את הטקסט 'Hello World' לשדה החדש באמצעות השיטה 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
   }
}