בקשות אצווה

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

סקירה

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

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

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

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

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

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

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

בקשה באצווה מורכבת מקריאה אחת ל-method 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
            },
            "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"
  }
}

מחליפים את REQUIRED_REVISION_ID במזהה הגרסה של המסמך שעליו חלה בקשת הכתיבה.

תשובה

התשובה באצווה לדוגמה הזו מציגה מידע על האופן שבו הוחלו כל בקשת משנה בתוך הבקשה באצווה. לא נמצאה תגובה ב-InsertTextRequest או ב-UpdateTextStyleRequest, כך שערכי האינדקס של המערך ב-[0] וב-[1] מכילים סוגריים מסולסלים ריקים. הבקשה באצווה מציגה את האובייקט WriteControl, שמראה איך הבקשות בוצעו.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}