בקשות אצווה

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

סקירה כללית

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

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

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

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

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

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

פרטי אצווה

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

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

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

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

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

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

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

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

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

דוגמה

בדוגמה הבאה אפשר לראות את השימוש בקיבוץ באמצעות Sheets API.

בקשה

הבקשה באצווה לדוגמה הזו ממחישה איך:

כשמוסיפים את מזהה הגיליון לבקשה, המשתמשים יכולים להשתמש במזהה הגיליון לבקשות משנה אחרות באותה קריאה ל-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
            }
         }
      }
   }
]