בקשות אצווה

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

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

בקשה

בדוגמה הזו לבקשת אצווה מוצגות הפעולות הבאות:

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

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

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

  • באמצעות השדה 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`
}