בקשות אצווה

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

בדוגמה הבאה מוצג שימוש באוסף פעולות עם Sheets API.

בקשה

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

• כדי להוסיף גיליון לגיליון אלקטרוני קיים, עם sheetId של 12345, משתמשים בפקודה 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
            }
         }
      }
   }
]