בקשות אצווה

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

דוגמת הקוד הבאה מציגה את השימוש בקיבוץ באצווה באמצעות ה-API של Docs.

בקשה

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

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

  • מעדכנים את המילה 'Hello' באמצעות 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`
}