בקשות אצווה

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

בדוגמה הבאה מוצג שימוש בצבירה עם Sheets API.

בקשה

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

• מוסיפים גיליון לגיליון אלקטרוני קיים, עם הערך 12345 בשדה sheetId, באמצעות הפקודה AddSheetRequest.
• מוסיפים נתונים לגיליון החדש, החל מתא A1, באמצעות הסמל UpdateCellsRequest.
• מוסיפים לגיליון החדש namedRange או תצוגת מסנן.

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

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

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

תשובה

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

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]