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

יש כמה עקרונות שמומלץ לפעול לפיהם כשמשתמשים ב-Google Docs API. האפשרויות הן:

  • עריכה אחורה כדי לשפר את היעילות
  • תוכנית לשיתוף פעולה
  • שמירה על עקביות של המצב באמצעות השדה WriteControl

העקרונות האלה מוסברים בחלקים הבאים.

עריכה אחורה כדי לשפר את היעילות

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

תוכנית לשיתוף פעולה

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

איך מסמך יכול להשתנות בין הפעלת method.

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

קביעת עקביות של מצב באמצעות WriteControl

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

כך משתמשים בו:

  1. מקבלים את המסמך באמצעות השיטה documents.get ושומרים את revisionId מהמשאב documents שמוחזר.
  2. כותבים את בקשות העדכון.
  3. מוסיפים אובייקט WriteControl אופציונלי עם אחת משתי אפשרויות:
    1. השדה requiredRevisionId מוגדר לערך revisionId של המסמך שעליו חלה בקשת הכתיבה. אם המסמך עבר שינוי מאז בקשת הקריאה של ה-API, בקשת הכתיבה לא מעובדת ומחזירה שגיאה.
    2. השדה targetRevisionId מוגדר לערך revisionId של המסמך שבקשת הכתיבה חלה עליו. אם המסמך השתנה מאז בקשת הקריאה של ה-API, השינויים בבקשת הכתיבה יחולו על השינויים של שותף העריכה. התוצאה של בקשת הכתיבה משלבת גם את השינויים בבקשת הכתיבה וגם את השינויים של שותף העריכה בגרסה חדשה של המסמך. שרת Docs אחראי למיזוג התוכן.

בדוגמה הזו לבקשת אצווה מופיעות דוגמה לבניית בקשה באצווה באמצעות WriteControl.