בקשות אצווה

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

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

בקשה

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

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

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