בקשות אצווה

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

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

בקשה

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

  • הוספת הטקסט 'Hello World' לתחילת מסמך קיים, עם הערך 1 ב-location, באמצעות הפונקציה InsertTextRequest.

  • מעדכנים את המילה 'שלום' באמצעות UpdateTextStyleRequest. השדות startIndex ו-endIndex מגדירים את range של הטקסט המעוצב בתוך הקטע.

  • באמצעות textStyle, מגדירים את סגנון הגופן כמודגש ואת הצבע ככחול רק למילה 'שלום'.

  • באמצעות השדה WriteControl תוכלו לקבוע איך יתבצעו בקשות הכתיבה. מידע נוסף זמין במאמר יצירת עקביות במצב באמצעות WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

מחליפים את TAB_ID ו-REQUIRED_REVISION_ID במזהה הכרטיסייה ובמזהה הגרסה, בהתאמה, של המסמך שבו הבקשה לכתיבה חלה.

תשובה

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

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}