בקשות אצווה

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

דוגמת הקוד הבאה מציגה את השימוש בקיבוץ באצווה באמצעות API של 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 ה-method לא מכילה תגובה, לכן ערך האינדקס של המערך ב-[2] מורכב מסוגריים מסולסלים ריקים. הבקשה באצווה מציגה את WriteControl מאפיין, שמראה איך בקשות הכתיבה בוצעו.

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